| Home | Libraries | People | FAQ | More

### Reverse Mode autodiff policies

This header provides default policy implementations for using the gradient-based optimizers with `boost::math::differentiation::reverse_mode::rvar` These policies handle:

- preparing the reverse-mode tape before evaluating an objective,
- extracting gradients from rvar arguments after backpropagation,
- initializing `rvar` containers and establishing tape checkpoints.

##### Synopsis

    #include <boost/math/optimization/detail/rdiff_optimization_policies>

    namespace boost {
    namespace math {
    namespace optimization {

    namespace rdiff = boost::math::differentiation::reverse_mode;

    /**
     * @brief> function evaluation policy for reverse mode autodiff
     * @arg objective> objective function to evaluate
     * @arg x> argument list
     */
    template<typename RealType>
    struct reverse_mode_function_eval_policy
    {
      template<typename Objective, class ArgumentContainer>
      rdiff::rvar<RealType, 1> operator()(Objective&& objective,
                                          ArgumentContainer& x);
    };

    /**
     * @brief> gradient evaluation policy
     * @arg obj_f> objective
     * @arg x> argument list
     * @arg f_eval_olicy> funciton evaluation policy. These need to be
     *                    done in tandem
     * @arg obj_v> reference to variable inside gradient class
     */
    template<typename RealType>
    struct reverse_mode_gradient_evaluation_policy
    {
      template<class Objective,
               class ArgumentContainer,
               class FunctionEvaluationPolicy>
      void operator()(Objective&& obj_f,
                      ArgumentContainer& x,
                      FunctionEvaluationPolicy&& f_eval_pol,
                      RealType& obj_v,
                      std::vector<RealType>& g)
    };
     /*
     * init policies
     */

    /* default rvar policy */
    template<typename RealType>
    struct tape_initializer_rvar
    {
        template<class ArgumentContainer>
        void operator()(ArgumentContainer& x) const noexcept;
    };

    /* random uniform */
    template<typename RealType>
    struct random_uniform_initializer_rvar
    {
      RealType low_, high_;
      size_t seed_;
      random_uniform_initializer_rvar(RealType low = 0,
                                      RealType high = 1,
                                      size_t seed = std::random_device{}());

      template<class ArgumentContainer>
      void operator()(ArgumentContainer& x) const;
    };

    /* constant initializer */
    template<typename RealType>
    struct costant_initializer_rvar
    {
      RealType constant;
      explicit costant_initializer_rvar(RealType v = 0);

      template<class ArgumentContainer>
      void operator()(ArgumentContainer& x) const;
    };
    } // namespace optimization
    } // namespace math
    } // namespace boost

##### Function evaluation policies

A function evaluation policy defines how an objective is evaluated at the current parameters, and is responsible for any AD bookkeeping required before the call.

##### reverse_mode_function_eval_policy

    template<typename RealType> struct reverse_mode_function_eval_policy { template<typename Objective, class ArgumentContainer> rdiff::rvar<RealType, 1> operator()(Objective&& objective, ArgumentContainer& x); };

This policy evaluates the objective objective(x) using reverse-mode AD and ensures the active tape is in a valid state before evaluation:

ArgumentContainer must contain rdiff::rvar<RealType,1> values.

##### Gradient evaluation policies

A gradient evaluation policy defines how gradients are computed and extracted into an ordinary numeric container.

##### reverse_mode_gradient_evaluation_policy

    template<typename RealType> struct reverse_mode_gradient_evaluation_policy { template<class Objective, class ArgumentContainer, class FunctionEvaluationPolicy> void operator()(Objective&& obj_f, ArgumentContainer& x, FunctionEvaluationPolicy&& f_eval_pol, RealType& obj_v, std::vector<RealType>& g); };

This policy computes the objective value and gradient using reverse-mode autodiff

##### Initialization policies

Initialization policies prepare the argument container and the reverse-mode tape for optimization. They establish tape checkpoints that are later used by function/gradient evaluation policies.

##### tape_initializer_rvar

    template<typename RealType> struct tape_initializer_rvar { template<class ArgumentContainer> void operator()(ArgumentContainer& x) const noexcept; };

This policy: * statically requires `ArgumentContainer::value_type` to be `rdiff::rvar<RealType,1>`, * adds a checkpoint to the active reverse-mode tape via `tape.add_checkpoint()`

##### random_uniform_initializer_rvar

    template<typename RealType>
    struct random_uniform_initializer_rvar
    {
    random_uniform_initializer_rvar(RealType low = 0,
    RealType high = 1,
    size_t seed = std::random_device{}());

    template<class ArgumentContainer>
    void operator()(ArgumentContainer& x) const;
    };

This policy initializes each element of x independently as:

    x[i] = rdiff::rvar<RealType,1>(U(low, high))

using

    boost::random::mt19937

and

    boost::random::uniform_real_distribution<RealType>

##### costant_initializer_rvar

    template<typename RealType>
    struct costant_initializer_rvar
    {
    explicit costant_initializer_rvar(RealType v = 0);

    template<class ArgumentContainer>
    void operator()(ArgumentContainer& x) const;
    };

This policy initializes each element of x to the constant value v