Expression.h

Go to the documentation of this file.

/* ----------------------------------------------------------------------------

 * 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

 * -------------------------------------------------------------------------- */

#pragma once

#include <gtsam/nonlinear/internal/JacobianMap.h>
#include <gtsam/inference/Symbol.h>
#include <gtsam/base/OptionalJacobian.h>
#include <gtsam/base/VectorSpace.h>

#include <map>

// Forward declare tests
class ExpressionFactorShallowTest;

namespace gtsam {

// Forward declares
class Values;
template<typename T> class ExpressionFactor;

namespace internal {
template<typename T> class ExecutionTrace;
template<typename T> class ExpressionNode;
}

template<typename T>
class Expression {

public:

  typedef Expression<T> type;

protected:

  // Paul's trick shared pointer, polymorphic root of entire expression tree
  std::shared_ptr<internal::ExpressionNode<T> > root_;

  Expression(const std::shared_ptr<internal::ExpressionNode<T> >& root) : root_(root) {}

public:

  // Expressions wrap trees of functions that can evaluate their own derivatives.
  // The meta-functions below are useful to specify the type of those functions.
  // Example, a function taking a camera and a 3D point and yielding a 2D point:
  //   Expression<Point2>::BinaryFunction<PinholeCamera<Cal3_S2>,Point3>::type
  template<class A1>
  struct UnaryFunction {
    typedef std::function<
        T(const A1&, typename MakeOptionalJacobian<T, A1>::type)> type;
  };

  template<class A1, class A2>
  struct BinaryFunction {
    typedef std::function<
        T(const A1&, const A2&, typename MakeOptionalJacobian<T, A1>::type,
            typename MakeOptionalJacobian<T, A2>::type)> type;
  };

  template<class A1, class A2, class A3>
  struct TernaryFunction {
    typedef std::function<
        T(const A1&, const A2&, const A3&,
            typename MakeOptionalJacobian<T, A1>::type,
            typename MakeOptionalJacobian<T, A2>::type,
            typename MakeOptionalJacobian<T, A3>::type)> type;
  };

  Expression(const T& value);

  Expression(const Key& key);

  Expression(const Symbol& symbol);

  Expression(unsigned char c, std::uint64_t j);

  template<typename A>
  Expression(typename UnaryFunction<A>::type function,
      const Expression<A>& expression);

  template<typename A1, typename A2>
  Expression(typename BinaryFunction<A1, A2>::type function,
      const Expression<A1>& expression1, const Expression<A2>& expression2);

  template<typename A1, typename A2, typename A3>
  Expression(typename TernaryFunction<A1, A2, A3>::type function,
      const Expression<A1>& expression1, const Expression<A2>& expression2,
      const Expression<A3>& expression3);

  template<typename A>
  Expression(const Expression<A>& expression,
      T (A::*method)(typename MakeOptionalJacobian<T, A>::type) const);

  template<typename A1, typename A2>
  Expression(const Expression<A1>& expression1,
      T (A1::*method)(const A2&, typename MakeOptionalJacobian<T, A1>::type,
          typename MakeOptionalJacobian<T, A2>::type) const,
      const Expression<A2>& expression2);

  template<typename A1, typename A2, typename A3>
  Expression(const Expression<A1>& expression1,
      T (A1::*method)(const A2&, const A3&,
          typename MakeOptionalJacobian<T, A1>::type,
          typename MakeOptionalJacobian<T, A2>::type,
          typename MakeOptionalJacobian<T, A3>::type) const,
      const Expression<A2>& expression2, const Expression<A3>& expression3);

  virtual ~Expression() {
  }

  std::set<Key> keys() const;

  void dims(std::map<Key, int>& map) const;

  void print(const std::string& s) const;

  T value(const Values& values, std::vector<Matrix>* H = nullptr) const;

  T value(const Values& values, std::vector<Matrix>& H) const {
    return value(values, &H);
  }

  virtual std::shared_ptr<Expression> clone() const {
    return std::make_shared<Expression>(*this);
  }

  const std::shared_ptr<internal::ExpressionNode<T> >& root() const;

  size_t traceSize() const;

  Expression<T>& operator+=(const Expression<T>& e);

protected:

  Expression() {}

  typedef std::pair<KeyVector, FastVector<int> > KeysAndDims;
  KeysAndDims keysAndDims() const;

  T valueAndDerivatives(const Values& values, const KeyVector& keys,
      const FastVector<int>& dims, std::vector<Matrix>& H) const;

  T traceExecution(const Values& values, internal::ExecutionTrace<T>& trace,
      char* traceStorage) const;

  T valueAndJacobianMap(const Values& values,
      internal::JacobianMap& jacobians) const;

  // be very selective on who can access these private methods:
  friend class ExpressionFactor<T> ;
  friend class internal::ExpressionNode<T>;

  // and add tests
  friend class ::ExpressionFactorShallowTest;
};

template <typename T>
class ScalarMultiplyExpression : public Expression<T> {
  // Check that T is a vector space
  GTSAM_CONCEPT_ASSERT(IsVectorSpace<T>);

 public:
  explicit ScalarMultiplyExpression(double s, const Expression<T>& e);
};

template <typename T>
class BinarySumExpression : public Expression<T> {
  // Check that T is a vector space
  GTSAM_CONCEPT_ASSERT(IsVectorSpace<T>);

 public:
  explicit BinarySumExpression(const Expression<T>& e1, const Expression<T>& e2);
};


template <typename T, typename A>
Expression<T> linearExpression(
    const std::function<T(A)>& f, const Expression<A>& expression,
    const Eigen::Matrix<double, traits<T>::dimension, traits<A>::dimension>& dTdA) {
  // Use lambda to endow f with a linear Jacobian
  typename Expression<T>::template UnaryFunction<A>::type g =
      [=](const A& value, typename MakeOptionalJacobian<T, A>::type H) {
        if (H)
          *H << dTdA;
        return f(value);
      };
  return Expression<T>(g, expression);
}

template <typename T>
ScalarMultiplyExpression<T> operator*(double s, const Expression<T>& e) {
  return ScalarMultiplyExpression<T>(s, e);
}

template <typename T>
BinarySumExpression<T> operator+(const Expression<T>& e1, const Expression<T>& e2) {
  return BinarySumExpression<T>(e1, e2);
}

template <typename T>
BinarySumExpression<T> operator-(const Expression<T>& e1, const Expression<T>& e2) {
  // TODO(frank, abe): Implement an actual negate operator instead of multiplying by -1
  return e1 + (-1.0) * e2;
}

template<typename T>
Expression<T> operator*(const Expression<T>& e1, const Expression<T>& e2);

template<typename T>
std::vector<Expression<T> > createUnknowns(size_t n, char c, size_t start = 0);

} // namespace gtsam

#include <gtsam/nonlinear/Expression-inl.h>