/* ---------------------------------------------------------------------------- * GTSAM Copyright 2010, Georgia Tech Research Corporation, * Atlanta, Georgia 30332-0415 * All Rights Reserved * Authors: Frank Dellaert, et al. (see THANKS for the full author list) * See LICENSE for the license information * -------------------------------------------------------------------------- */ /** * @file Expression-inl.h * @date September 18, 2014 * @author Frank Dellaert * @author Paul Furgale * @brief Internals for Expression.h, not for general consumption */ #pragma once #include #include #include #include #include #include // for placement new struct TestBinaryExpression; // template meta-programming headers #include #include #include #include #include #include #include #include #include namespace MPL = boost::mpl::placeholders; class ExpressionFactorBinaryTest; // Forward declare for testing namespace gtsam { template class Expression; typedef std::map JacobianMap; /// Move terms to array, destroys content void move(JacobianMap& jacobians, std::vector& H) { assert(H.size()==jacobians.size()); size_t j = 0; JacobianMap::iterator it = jacobians.begin(); for (; it != jacobians.end(); ++it) it->second.swap(H[j++]); } //----------------------------------------------------------------------------- /** * Value and Jacobians */ template class Augmented { private: T value_; JacobianMap jacobians_; typedef std::pair Pair; /// Insert terms into jacobians_, adding if already exists void add(const JacobianMap& terms) { BOOST_FOREACH(const Pair& term, terms) { JacobianMap::iterator it = jacobians_.find(term.first); if (it != jacobians_.end()) it->second += term.second; else jacobians_[term.first] = term.second; } } /// Insert terms into jacobians_, premultiplying by H, adding if already exists void add(const Matrix& H, const JacobianMap& terms) { BOOST_FOREACH(const Pair& term, terms) { JacobianMap::iterator it = jacobians_.find(term.first); if (it != jacobians_.end()) it->second += H * term.second; else jacobians_[term.first] = H * term.second; } } public: /// Construct value that does not depend on anything Augmented(const T& t) : value_(t) { } /// Construct value dependent on a single key Augmented(const T& t, Key key) : value_(t) { size_t n = t.dim(); jacobians_[key] = Eigen::MatrixXd::Identity(n, n); } /// Construct value, pre-multiply jacobians by dTdA Augmented(const T& t, const Matrix& dTdA, const JacobianMap& jacobians) : value_(t) { add(dTdA, jacobians); } /// Construct value, pre-multiply jacobians Augmented(const T& t, const Matrix& dTdA1, const JacobianMap& jacobians1, const Matrix& dTdA2, const JacobianMap& jacobians2) : value_(t) { add(dTdA1, jacobians1); add(dTdA2, jacobians2); } /// Construct value, pre-multiply jacobians Augmented(const T& t, const Matrix& dTdA1, const JacobianMap& jacobians1, const Matrix& dTdA2, const JacobianMap& jacobians2, const Matrix& dTdA3, const JacobianMap& jacobians3) : value_(t) { add(dTdA1, jacobians1); add(dTdA2, jacobians2); add(dTdA3, jacobians3); } /// Return value const T& value() const { return value_; } /// Return jacobians const JacobianMap& jacobians() const { return jacobians_; } /// Return jacobians JacobianMap& jacobians() { return jacobians_; } /// Not dependent on any key bool constant() const { return jacobians_.empty(); } /// debugging void print(const KeyFormatter& keyFormatter = DefaultKeyFormatter) { BOOST_FOREACH(const Pair& term, jacobians_) std::cout << "(" << keyFormatter(term.first) << ", " << term.second.rows() << "x" << term.second.cols() << ") "; std::cout << std::endl; } /// Move terms to array, destroys content void move(std::vector& H) { move(jacobians_, H); } }; //----------------------------------------------------------------------------- /** * The CallRecord class stores the Jacobians of applying a function * with respect to each of its arguments. It also stores an executation trace * (defined below) for each of its arguments. * * It is sub-classed in the function-style ExpressionNode sub-classes below. */ template struct CallRecord { static size_t const N = 0; virtual void print(const std::string& indent) const { } virtual void startReverseAD(JacobianMap& jacobians) const { } virtual void reverseAD(const Matrix& dFdT, JacobianMap& jacobians) const { } typedef Eigen::Matrix Jacobian2T; virtual void reverseAD2(const Jacobian2T& dFdT, JacobianMap& jacobians) const { } }; //----------------------------------------------------------------------------- /** * The ExecutionTrace class records a tree-structured expression's execution * It is a tagged union that obviates the need to create * a ExecutionTrace subclass for Constants and Leaf Expressions. Instead * the key for the leaf is stored in the space normally used to store a * CallRecord*. Nothing is stored for a Constant. */ template class ExecutionTrace { enum { Constant, Leaf, Function } kind; union { Key key; CallRecord* ptr; } content; public: /// Pointer always starts out as a Constant ExecutionTrace() : kind(Constant) { } /// Change pointer to a Leaf Record void setLeaf(Key key) { kind = Leaf; content.key = key; } /// Take ownership of pointer to a Function Record void setFunction(CallRecord* record) { kind = Function; content.ptr = record; } /// Print void print(const std::string& indent = "") const { if (kind == Constant) std::cout << indent << "Constant" << std::endl; else if (kind == Leaf) std::cout << indent << "Leaf, key = " << content.key << std::endl; else if (kind == Function) { std::cout << indent << "Function" << std::endl; content.ptr->print(indent + " "); } } /// Return record pointer, quite unsafe, used only for testing template boost::optional record() { if (kind != Function) return boost::none; else { Record* p = dynamic_cast(content.ptr); return p ? boost::optional(p) : boost::none; } } // *** This is the main entry point for reverseAD, called from Expression::augmented *** // Called only once, either inserts identity into Jacobians (Leaf) or starts AD (Function) void startReverseAD(JacobianMap& jacobians) const { if (kind == Leaf) { // This branch will only be called on trivial Leaf expressions, i.e. Priors size_t n = T::Dim(); jacobians[content.key] = Eigen::MatrixXd::Identity(n, n); } else if (kind == Function) // This is the more typical entry point, starting the AD pipeline // It is inside the startReverseAD that the correctly dimensioned pipeline is chosen. content.ptr->startReverseAD(jacobians); } // Either add to Jacobians (Leaf) or propagate (Function) void reverseAD(const Matrix& dTdA, JacobianMap& jacobians) const { if (kind == Leaf) { JacobianMap::iterator it = jacobians.find(content.key); if (it != jacobians.end()) it->second += dTdA; else jacobians[content.key] = dTdA; } else if (kind == Function) content.ptr->reverseAD(dTdA, jacobians); } // Either add to Jacobians (Leaf) or propagate (Function) typedef Eigen::Matrix Jacobian2T; void reverseAD2(const Jacobian2T& dTdA, JacobianMap& jacobians) const { if (kind == Leaf) { JacobianMap::iterator it = jacobians.find(content.key); if (it != jacobians.end()) it->second += dTdA; else jacobians[content.key] = dTdA; } else if (kind == Function) content.ptr->reverseAD2(dTdA, jacobians); } /// Define type so we can apply it as a meta-function typedef ExecutionTrace type; }; /// Primary template calls the generic Matrix reverseAD pipeline template struct Select { typedef Eigen::Matrix Jacobian; static void reverseAD(const ExecutionTrace& trace, const Jacobian& dTdA, JacobianMap& jacobians) { trace.reverseAD(dTdA, jacobians); } }; /// Partially specialized template calls the 2-dimensional output version template struct Select<2, A> { typedef Eigen::Matrix Jacobian; static void reverseAD(const ExecutionTrace& trace, const Jacobian& dTdA, JacobianMap& jacobians) { trace.reverseAD2(dTdA, jacobians); } }; //----------------------------------------------------------------------------- /** * Expression node. The superclass for objects that do the heavy lifting * An Expression has a pointer to an ExpressionNode underneath * allowing Expressions to have polymorphic behaviour even though they * are passed by value. This is the same way boost::function works. * http://loki-lib.sourceforge.net/html/a00652.html */ template class ExpressionNode { protected: size_t traceSize_; /// Constructor, traceSize is size of the execution trace of expression rooted here ExpressionNode(size_t traceSize = 0) : traceSize_(traceSize) { } public: /// Destructor virtual ~ExpressionNode() { } /// Return keys that play in this expression as a set virtual std::set keys() const { std::set keys; return keys; } /// Return dimensions for each argument virtual std::map dimensions() const { std::map map; return map; } // Return size needed for memory buffer in traceExecution size_t traceSize() const { return traceSize_; } /// Return value virtual T value(const Values& values) const = 0; /// Return value and derivatives virtual Augmented forward(const Values& values) const = 0; /// Construct an execution trace for reverse AD virtual T traceExecution(const Values& values, ExecutionTrace& trace, char* raw) const = 0; }; //----------------------------------------------------------------------------- /// Constant Expression template class ConstantExpression: public ExpressionNode { /// The constant value T constant_; /// Constructor with a value, yielding a constant ConstantExpression(const T& value) : constant_(value) { } friend class Expression ; public: /// Return value virtual T value(const Values& values) const { return constant_; } /// Return value and derivatives virtual Augmented forward(const Values& values) const { return Augmented(constant_); } /// Construct an execution trace for reverse AD virtual T traceExecution(const Values& values, ExecutionTrace& trace, char* raw) const { return constant_; } }; //----------------------------------------------------------------------------- /// Leaf Expression template class LeafExpression: public ExpressionNode { /// The key into values Key key_; /// Constructor with a single key LeafExpression(Key key) : key_(key) { } friend class Expression ; public: /// Return keys that play in this expression virtual std::set keys() const { std::set keys; keys.insert(key_); return keys; } /// Return dimensions for each argument virtual std::map dimensions() const { std::map map; map[key_] = T::dimension; return map; } /// Return value virtual T value(const Values& values) const { return values.at(key_); } /// Return value and derivatives virtual Augmented forward(const Values& values) const { return Augmented(values.at(key_), key_); } /// Construct an execution trace for reverse AD virtual T traceExecution(const Values& values, ExecutionTrace& trace, char* raw) const { trace.setLeaf(key_); return values.at(key_); } }; //----------------------------------------------------------------------------- // Below we use the "Class Composition" technique described in the book // C++ Template Metaprogramming: Concepts, Tools, and Techniques from Boost // and Beyond. Abrahams, David; Gurtovoy, Aleksey. Pearson Education. // to recursively generate a class, that will be the base for function nodes. // The class generated, for two arguments A1, A2, and A3 will be // // struct Base1 : Argument, FunctionalBase { // ... storage related to A1 ... // ... methods that work on A1 ... // }; // // struct Base2 : Argument, Base1 { // ... storage related to A2 ... // ... methods that work on A2 and (recursively) on A2 ... // }; // // struct Base2 : Argument, Base2 { // ... storage related to A3 ... // ... methods that work on A3 and (recursively) on A2 and A3 ... // }; // // struct FunctionalNode : Base3 { // Provides convenience access to storage in hierarchy by using // static_cast &>(*this) // } // // All this magic happens when we generate the Base3 base class of FunctionalNode // by invoking boost::mpl::fold over the meta-function GenerateFunctionalNode //----------------------------------------------------------------------------- /// meta-function to generate fixed-size JacobianTA type template struct Jacobian { typedef Eigen::Matrix type; }; /// meta-function to generate JacobianTA optional reference template struct Optional { typedef Eigen::Matrix Jacobian; typedef boost::optional type; }; /** * Base case for recursive FunctionalNode class */ template struct FunctionalBase: ExpressionNode { static size_t const N = 0; // number of arguments typedef CallRecord Record; /// Construct an execution trace for reverse AD void trace(const Values& values, Record* record, char*& raw) const { } }; /** * Building block for recursive FunctionalNode class * The integer argument N is to guarantee a unique type signature, * so we are guaranteed to be able to extract their values by static cast. */ template struct Argument { /// Expression that will generate value/derivatives for argument boost::shared_ptr > expression; }; /** * Building block for Recursive Record Class * Records the evaluation of a single argument in a functional expression */ template struct JacobianTrace { A value; ExecutionTrace trace; typename Jacobian::type dTdA; }; /** * Recursive Definition of Functional ExpressionNode */ template struct GenerateFunctionalNode: Argument, Base { static size_t const N = Base::N + 1; ///< Number of arguments in hierarchy typedef Argument This; ///< The storage we have direct access to /// Return keys that play in this expression virtual std::set keys() const { std::set keys = Base::keys(); std::set myKeys = This::expression->keys(); keys.insert(myKeys.begin(), myKeys.end()); return keys; } /// Return dimensions for each argument virtual std::map dimensions() const { std::map map = Base::dimensions(); std::map myMap = This::expression->dimensions(); map.insert(myMap.begin(), myMap.end()); return map; } /// Recursive Record Class for Functional Expressions struct Record: JacobianTrace, Base::Record { typedef T return_type; typedef JacobianTrace This; /// Print to std::cout virtual void print(const std::string& indent) const { Base::Record::print(indent); static const Eigen::IOFormat matlab(0, 1, " ", "; ", "", "", "[", "]"); std::cout << This::dTdA.format(matlab) << std::endl; This::trace.print(indent); } /// Start the reverse AD process virtual void startReverseAD(JacobianMap& jacobians) const { Base::Record::startReverseAD(jacobians); Select::reverseAD(This::trace, This::dTdA, jacobians); } /// Given df/dT, multiply in dT/dA and continue reverse AD process virtual void reverseAD(const Matrix& dFdT, JacobianMap& jacobians) const { Base::Record::reverseAD(dFdT, jacobians); This::trace.reverseAD(dFdT * This::dTdA, jacobians); } /// Version specialized to 2-dimensional output typedef Eigen::Matrix Jacobian2T; virtual void reverseAD2(const Jacobian2T& dFdT, JacobianMap& jacobians) const { Base::Record::reverseAD2(dFdT, jacobians); This::trace.reverseAD2(dFdT * This::dTdA, jacobians); } }; /// Construct an execution trace for reverse AD void trace(const Values& values, Record* record, char*& raw) const { Base::trace(values, record, raw); // recurse // Write an Expression execution trace in record->trace // Iff Constant or Leaf, this will not write to raw, only to trace. // Iff the expression is functional, write all Records in raw buffer // Return value of type T is recorded in record->value record->Record::This::value = This::expression->traceExecution(values, record->Record::This::trace, raw); // raw is never modified by traceExecution, but if traceExecution has // written in the buffer, the next caller expects we advance the pointer raw += This::expression->traceSize(); } }; /** * Recursive GenerateFunctionalNode class Generator */ template struct FunctionalNode { typedef typename boost::mpl::fold, GenerateFunctionalNode >::type Base; struct type: public Base { // Argument types and derived, note these are base 0 ! typedef TYPES Arguments; typedef typename boost::mpl::transform >::type Jacobians; typedef typename boost::mpl::transform >::type Optionals; /// Reset expression shared pointer template void reset(const boost::shared_ptr >& ptr) { static_cast &>(*this).expression = ptr; } /// Access Expression shared pointer template boost::shared_ptr > expression() const { return static_cast const &>(*this).expression; } /// Provide convenience access to Record storage struct Record: public Base::Record { /// Access Value template const A& value() const { return static_cast const &>(*this).value; } /// Access Jacobian template typename Jacobian::type& jacobian() { return static_cast&>(*this).dTdA; } }; /// Construct an execution trace for reverse AD Record* trace(const Values& values, char* raw) const { // Create the record and advance the pointer Record* record = new (raw) Record(); raw = (char*) (record + 1); // Record the traces for all arguments // After this, the raw pointer is set to after what was written Base::trace(values, record, raw); // Return the record for this function evaluation return record; } }; }; //----------------------------------------------------------------------------- /// Unary Function Expression template class UnaryExpression: public FunctionalNode >::type { public: typedef boost::function::type)> Function; typedef typename FunctionalNode >::type Base; typedef typename Base::Record Record; private: Function function_; /// Constructor with a unary function f, and input argument e UnaryExpression(Function f, const Expression& e1) : function_(f) { this->template reset(e1.root()); ExpressionNode::traceSize_ = sizeof(Record) + e1.traceSize(); } friend class Expression ; public: /// Return value virtual T value(const Values& values) const { return function_(this->template expression()->value(values), boost::none); } /// Return value and derivatives virtual Augmented forward(const Values& values) const { using boost::none; Augmented a1 = this->template expression()->forward(values); // Declare Jacobians using boost::mpl::at_c; typename at_c::type H1; T t = function_(a1.value(), H1); return Augmented(t, H1, a1.jacobians()); } /// Construct an execution trace for reverse AD virtual T traceExecution(const Values& values, ExecutionTrace& trace, char* raw) const { Record* record = Base::trace(values, raw); trace.setFunction(record); return function_(record->template value(), record->template jacobian()); } }; //----------------------------------------------------------------------------- /// Binary Expression template class BinaryExpression: public FunctionalNode >::type { public: typedef boost::function< T(const A1&, const A2&, typename Optional::type, typename Optional::type)> Function; typedef typename FunctionalNode >::type Base; typedef typename Base::Record Record; private: Function function_; /// Constructor with a ternary function f, and three input arguments BinaryExpression(Function f, const Expression& e1, const Expression& e2) : function_(f) { this->template reset(e1.root()); this->template reset(e2.root()); ExpressionNode::traceSize_ = // sizeof(Record) + e1.traceSize() + e2.traceSize(); } friend class Expression ; friend class ::ExpressionFactorBinaryTest; public: /// Return value virtual T value(const Values& values) const { using boost::none; return function_(this->template expression()->value(values), this->template expression()->value(values), none, none); } /// Return value and derivatives virtual Augmented forward(const Values& values) const { using boost::none; Augmented a1 = this->template expression()->forward(values); Augmented a2 = this->template expression()->forward(values); // Declare Jacobians using boost::mpl::at_c; typename at_c::type H1; typename at_c::type H2; T t = function_(a1.value(), a2.value(),H1,H2); return Augmented(t, H1, a1.jacobians(), H2, a2.jacobians()); } /// Construct an execution trace for reverse AD virtual T traceExecution(const Values& values, ExecutionTrace& trace, char* raw) const { Record* record = Base::trace(values, raw); trace.setFunction(record); return function_(record->template value(), record->template value(), record->template jacobian(), record->template jacobian()); } }; //----------------------------------------------------------------------------- /// Ternary Expression template class TernaryExpression: public FunctionalNode >::type { public: typedef boost::function< T(const A1&, const A2&, const A3&, typename Optional::type, typename Optional::type, typename Optional::type)> Function; typedef typename FunctionalNode >::type Base; typedef typename Base::Record Record; private: Function function_; /// Constructor with a ternary function f, and three input arguments TernaryExpression(Function f, const Expression& e1, const Expression& e2, const Expression& e3) : function_(f) { this->template reset(e1.root()); this->template reset(e2.root()); this->template reset(e3.root()); ExpressionNode::traceSize_ = // sizeof(Record) + e1.traceSize() + e2.traceSize() + e3.traceSize(); } friend class Expression ; public: /// Return value virtual T value(const Values& values) const { using boost::none; return function_(this->template expression()->value(values), this->template expression()->value(values), this->template expression()->value(values), none, none, none); } /// Return value and derivatives virtual Augmented forward(const Values& values) const { using boost::none; Augmented a1 = this->template expression()->forward(values); Augmented a2 = this->template expression()->forward(values); Augmented a3 = this->template expression()->forward(values); // Declare Jacobians using boost::mpl::at_c; typename at_c::type H1; typename at_c::type H2; typename at_c::type H3; T t = function_(a1.value(), a2.value(), a3.value(),H1,H2,H3); return Augmented(t, H1, a1.jacobians(), H2, a2.jacobians(), H3, a3.jacobians()); } /// Construct an execution trace for reverse AD virtual T traceExecution(const Values& values, ExecutionTrace& trace, char* raw) const { Record* record = Base::trace(values, raw); trace.setFunction(record); return function_( record->template value(), record->template value(), record->template value(), record->template jacobian(), record->template jacobian(), record->template jacobian()); } }; //----------------------------------------------------------------------------- }