Public Member Functions | Static Public Member Functions | List of all members
corbo::ForwardDifferences Class Reference

Finite differences via forward differences. More...

#include <finite_differences.h>

Inheritance diagram for corbo::ForwardDifferences:
Inheritance graph
[legend]

Public Member Functions

void computeHessian (std::function< void(int, const double &)> inc_fun, std::function< void(Eigen::Ref< Eigen::VectorXd >)> eval_fun, int dim_f, Eigen::Ref< Eigen::MatrixXd > hessian, const double *multipliers=nullptr) override
 Compute Hessian of a desired function. More...
 
void computeHessian2 (std::function< void(int, const double &)> inc_fun, std::function< void(Eigen::VectorXd &)> eval_fun, int dim_f, Eigen::Ref< Eigen::MatrixXd > hessian, const double *multipliers=nullptr) override
 Compute Hessian of a desired function (overload which accepts a slightly different callback function) More...
 
void computeJacobian (std::function< void(int, const double &)> inc_fun, std::function< void(Eigen::Ref< Eigen::VectorXd >)> eval_fun, Eigen::Ref< Eigen::MatrixXd > jacobian) override
 Compute Jacobian of a desired function. More...
 
void computeJacobian2 (std::function< void(int, const double &)> inc_fun, std::function< void(Eigen::VectorXd &)> eval_fun, Eigen::Ref< Eigen::MatrixXd > jacobian) override
 Compute Jacobian of a desired function (overload which accepts a slightly different callback function) More...
 
void computeJacobianAndHessian (std::function< void(int, const double &)> inc_fun, std::function< void(Eigen::Ref< Eigen::VectorXd >)> eval_fun, Eigen::Ref< Eigen::MatrixXd > jacobian, Eigen::Ref< Eigen::MatrixXd > hessian, const double *multipliers=nullptr) override
 Compute Jacobian and Hessian of a desired function. More...
 
void computeJacobianAndHessian2 (std::function< void(int, const double &)> inc_fun, std::function< void(Eigen::VectorXd &)> eval_fun, Eigen::Ref< Eigen::MatrixXd > jacobian, Eigen::Ref< Eigen::MatrixXd > hessian, const double *multipliers=nullptr) override
 Compute Jacobian and Hessian of a desired function (overload which accepts a slightly different callback function) More...
 
FiniteDifferencesInterface::Ptr getInstance () const override
 Return a newly allocated instances of the inherited class. More...
 
template<typename IncFun , typename EvalFun >
void jacobianHessian (IncFun inc_fun, EvalFun eval_fun, Eigen::Ref< Eigen::MatrixXd > jacobian, Eigen::Ref< Eigen::MatrixXd > hessian, const double *multipliers=nullptr)
 Compute Jacobian and Hessian of a desired function. More...
 
- Public Member Functions inherited from corbo::FiniteDifferencesInterface
virtual ~FiniteDifferencesInterface ()
 Virtual destructor. More...
 

Static Public Member Functions

template<typename IncFun , typename EvalFun >
static void hessian (IncFun inc_fun, EvalFun eval_fun, int dim_f, Eigen::Ref< Eigen::MatrixXd > hessian, const double *multipliers=nullptr)
 Compute Hessian of a desired function. More...
 
template<typename IncFun , typename EvalFun >
static void jacobian (IncFun inc_fun, EvalFun eval_fun, Eigen::Ref< Eigen::MatrixXd > jacobian)
 Compute Jacobian of a desired function. More...
 

Additional Inherited Members

- Public Types inherited from corbo::FiniteDifferencesInterface
using InputVector = Eigen::VectorXd
 
using Ptr = std::shared_ptr< FiniteDifferencesInterface >
 
using StateVector = Eigen::VectorXd
 
using UPtr = std::unique_ptr< FiniteDifferencesInterface >
 

Detailed Description

Finite differences via forward differences.

Forward differences approximate $ \dot{x} = f(x) $ in the following manner:

\[ \frac{x_{k+1} - x_k}{\delta} = f(x_k) \]

See also
FiniteDifferencesInterface CentralDifferences NumericalIntegratorExplicitInterface
Author
Christoph Rösmann (chris.nosp@m.toph.nosp@m..roes.nosp@m.mann.nosp@m.@tu-d.nosp@m.ortm.nosp@m.und.d.nosp@m.e)

Definition at line 49 of file finite_differences.h.

Member Function Documentation

◆ computeHessian()

void corbo::ForwardDifferences::computeHessian ( std::function< void(int, const double &)>  inc_fun,
std::function< void(Eigen::Ref< Eigen::VectorXd >)>  eval_fun,
int  dim_f,
Eigen::Ref< Eigen::MatrixXd >  hessian,
const double *  multipliers = nullptr 
)
overridevirtual

Compute Hessian of a desired function.

Given a function $ f(x) $ with $ f: \mathbb{R}^p \to \mathbb{R}^n $. This method computes the $ n $ Hessian matrices of $ f(x) $ (element-wise) and accumulates them (optionally with individual scale factors). In case $ n=1 $, the Hessian is as follows:

\[ Hf_{1x}(x_0) = \begin{bmatrix} \partial^2_{x_1 x_1} f_1(x_0) & \partial^2_{x_1 x_2} f_1(x_0) & \cdots & \partial^2_{x_1 x_p} f_1(x_0) \\ \partial^2_{x_2 x_1} f_1(x_0) & \partial^2_{x_2 x_2} f_1(x_0) & \cdots & \partial^2_{x_2 x_p} f_1(x_0) \\ \vdots \\ \partial^2_{x_p x_1} f_1(x_0) & \partial^2_{x_p x_2} f_1(x_0) & \cdots & \partial^2_{x_p x_p} f_1(x_0) \end{bmatrix} \]

The Hessian is evaluated at $ x_0 $.

Function prototypes inc_fun and eval_fun are similar to computeJacobian(). In case the function callback is defined in terms of taking an Eigen::VectorXd& into account rather than Eigen::Ref<Eigen::VectorXd> refer to overload computeHessian2()

See also
computeHessian2 computeJacobianAndHessian
Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[in]dim_fDimension of the function value vector (obtained from eval_fun)
[out]hessianThe resulting Hessian matrix (warning: hessian must be preallocated as p x p matrix)
[in]multipliers(optional) Vector of multipliers for scaling individual Hessian terms [dim_f x 1].

Implements corbo::FiniteDifferencesInterface.

Definition at line 41 of file finite_differences.cpp.

◆ computeHessian2()

void corbo::ForwardDifferences::computeHessian2 ( std::function< void(int, const double &)>  inc_fun,
std::function< void(Eigen::VectorXd &)>  eval_fun,
int  dim_f,
Eigen::Ref< Eigen::MatrixXd >  hessian,
const double *  multipliers = nullptr 
)
overridevirtual

Compute Hessian of a desired function (overload which accepts a slightly different callback function)

Refer to the documentation of computeHessian(). This method takes type Eigen::VectorXd& into account for the function evaluation callback rather than Eigen::Ref<Eigen::VectorXd>.

See also
computeHessian computeJacobianAndHessian2
Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[in]dim_fDimension of the function value vector (obtained from eval_fun)
[out]hessianThe resulting Hessian matrix (warning: hessian must be preallocated as p x p matrix)
[in]multipliers(optional) Vector of multipliers for scaling individual Hessian terms [dim_f x 1].

Implements corbo::FiniteDifferencesInterface.

Definition at line 47 of file finite_differences.cpp.

◆ computeJacobian()

void corbo::ForwardDifferences::computeJacobian ( std::function< void(int, const double &)>  inc_fun,
std::function< void(Eigen::Ref< Eigen::VectorXd >)>  eval_fun,
Eigen::Ref< Eigen::MatrixXd >  jacobian 
)
overridevirtual

Compute Jacobian of a desired function.

Given a function $ f(x) $ with $ f: \mathbb{R}^p \to \mathbb{R}^n $. This method computes the Jacobian matrix

\[ Jf_x(x_0) = \begin{bmatrix} \partial_{x_1} f_1(x_0) & \partial_{x_2} f_1(x_0) & \cdots & \partial_{x_p} f_1(x_0) \\ \partial_{x_1} f_2(x_0) & \partial_{x_2} f_2(x_0) & \cdots & \partial_{x_p} f_2(x_0) \\ \vdots \\ \partial_{x_1} f_p(x_0) & \partial_{x_2} f_p(x_0) & \cdots & \partial_{x_p} f_p(x_0) \end{bmatrix} \]

The Jacobian is evaluated at $ x_0 $.

The function $ f $ is defined by a function of the following prototype:

void fun(Eigen::Ref<Eigen::VectorXd> values);

Hereby, fun should return the function values via output argument values as (n x 1) vector by implicitly taking the current working point $ x_0 $ into account. Note, you might want to bind other parameters to fun by using lambdas or std::bind().

Furthermore, a second function needs to be provided, in particular an implempation of the increment operator. Within Jacobian computation, the variable $ x $ needs to be varied (for computing finite differences). This can be achieved in a callback fashion by providing the increment function according to the following prototype:

void inc(int idx, const double& value);

Herebey, the first parameter determines which index (element in $ x $) needs to be incremented, and the second contains the actual increment value.

Example implementation:

Eigen::Vector2d x(1,1); // variable x initialized with [1, 1]^T as current working point (dimension p=2)
auto inc = [&x](int idx, const double& value){x[idx] += value;}; // define increment as simple x[idx]+=value, also bind x.
auto fun = [&x](Eigen::Ref<Eigen::VectorXd> values)
{
values[0] = x[0] * x[0] + 1; // f1 = x1^2 + 1
values[1] = x[1] * x[0] + 2; // f2 = x1*x2 + 2
}; // dimension n=2
Eigen::MatrixXd jacobian(2,2); // we must initialize/pre-allocate the jacobian with the correct size [p x n]
computeJacobian(inc, fun, jacobian);

In case the function callback is defined in terms of taking an Eigen::VectorXd& into account rather than Eigen::Ref<Eigen::VectorXd> refer to overload computeJacobian2()

See also
computeJacobian2 computeJacobianAndHessian
Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[out]jacobianThe resulting Jacobian matrix (warning: jacobian must be preallocated as n x p matrix)

Implements corbo::FiniteDifferencesInterface.

Definition at line 29 of file finite_differences.cpp.

◆ computeJacobian2()

void corbo::ForwardDifferences::computeJacobian2 ( std::function< void(int, const double &)>  inc_fun,
std::function< void(Eigen::VectorXd &)>  eval_fun,
Eigen::Ref< Eigen::MatrixXd >  jacobian 
)
overridevirtual

Compute Jacobian of a desired function (overload which accepts a slightly different callback function)

Refer to the documentation of computeJacobian(). This method takes type Eigen::VectorXd& into account for the function evaluation callback rather than Eigen::Ref<Eigen::VectorXd>.

See also
computeJacobian computeJacobianAndHessian2
Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[out]jacobianThe resulting Jacobian matrix (warning: jacobian must be preallocated as n x p matrix)

Implements corbo::FiniteDifferencesInterface.

Definition at line 35 of file finite_differences.cpp.

◆ computeJacobianAndHessian()

void corbo::ForwardDifferences::computeJacobianAndHessian ( std::function< void(int, const double &)>  inc_fun,
std::function< void(Eigen::Ref< Eigen::VectorXd >)>  eval_fun,
Eigen::Ref< Eigen::MatrixXd >  jacobian,
Eigen::Ref< Eigen::MatrixXd >  hessian,
const double *  multipliers = nullptr 
)
overridevirtual

Compute Jacobian and Hessian of a desired function.

This method is often faster than invoking computeJacobian() and computeHessian() separately.

Refer to the individual methods to obtain details regarding arguments and usage.

EvalFun should be of type void(Eigen::VectorXd& values) or similar and should return current function values. IncFun should be of type void(int idx, double value) and should increment component idx by value. The dimension of the function provided by eval_f is obtained by checking the number of allocated rows of the jacobian variable. In case dim_f > 1, the hessian is computed for each dimension and summed up. Optionally, individual hessians might be scaled by a multiplier which is common in solving nonlinear programs (e.g., Lagrangian). If provided, the multiplier vector should be of size [dim_f x 1].

Function prototypes inc_fun and eval_fun are similar to computeJacobian(). In case the function callback is defined in terms of taking an Eigen::VectorXd& into account rather than Eigen::Ref<Eigen::VectorXd> refer to overload computeJacobianAndHessian2()

Note
The Jacobian is also scaled by the multipliers if provided.
See also
computeJacobian computeHessian computeJacobianAndHessian2
Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[out]jacobianThe resulting Jacobian matrix (warning: jacobian must be preallocated as n x p matrix)
[out]hessianThe resulting Hessian matrix (warning: hessian must be preallocated as p x p matrix)
[in]multipliers(optional) Vector of multipliers for scaling individual Hessian terms [dim_f x 1].

Implements corbo::FiniteDifferencesInterface.

Definition at line 53 of file finite_differences.cpp.

◆ computeJacobianAndHessian2()

void corbo::ForwardDifferences::computeJacobianAndHessian2 ( std::function< void(int, const double &)>  inc_fun,
std::function< void(Eigen::VectorXd &)>  eval_fun,
Eigen::Ref< Eigen::MatrixXd >  jacobian,
Eigen::Ref< Eigen::MatrixXd >  hessian,
const double *  multipliers = nullptr 
)
overridevirtual

Compute Jacobian and Hessian of a desired function (overload which accepts a slightly different callback function)

Refer to the documentation of computeJacobianAndHessian(). This method takes type Eigen::VectorXd& into account for the function evaluation callback rather than Eigen::Ref<Eigen::VectorXd>.

Note
The Jacobian is also scaled by the multipliers if provided.
See also
computeJacobianAndHessian computeJacobian computeHessian
Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[out]jacobianThe resulting Jacobian matrix (warning: jacobian must be preallocated as n x p matrix)
[out]hessianThe resulting Hessian matrix (warning: hessian must be preallocated as p x p matrix)
[in]multipliers(optional) Vector of multipliers for scaling individual Hessian terms [dim_f x 1].

Implements corbo::FiniteDifferencesInterface.

Definition at line 60 of file finite_differences.cpp.

◆ getInstance()

FiniteDifferencesInterface::Ptr corbo::ForwardDifferences::getInstance ( ) const
inlineoverridevirtual

Return a newly allocated instances of the inherited class.

Implements corbo::FiniteDifferencesInterface.

Definition at line 53 of file finite_differences.h.

◆ hessian()

template<typename IncFun , typename EvalFun >
void corbo::ForwardDifferences::hessian ( IncFun  inc_fun,
EvalFun  eval_fun,
int  dim_f,
Eigen::Ref< Eigen::MatrixXd >  hessian,
const double *  multipliers = nullptr 
)
static

Compute Hessian of a desired function.

Refer to FiniteDifferencesInterface::computeHessian() for more details.

EvalFun should be of type void(Eigen::VectorXd& values) or similar and should return current function values. IncFun should be of type void(int idx, double value) and should increment component idx by value. Parameter dim_f defines the dimension of the function provided by eval_fun. In case dim_f > 1, the hessian is computed for each dimension and summed up. Optionally, individual hessians might be scaled by a multiplier which is common in solving nonlinear programs (e.g., Lagrangian). If provided, the multiplier vector should be of size [dim_f x 1].

Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[in]dim_fDimension of the function value vector (obtained from eval_fun)
[out]hessianThe resulting Hessian matrix (warning: hessian must be preallocated as p x p matrix)
[in]multipliers(optional) Vector of multipliers for scaling individual Hessian terms [dim_f x 1].

Definition at line 52 of file finite_differences.hpp.

◆ jacobian()

template<typename IncFun , typename EvalFun >
void corbo::ForwardDifferences::jacobian ( IncFun  inc_fun,
EvalFun  eval_fun,
Eigen::Ref< Eigen::MatrixXd >  jacobian 
)
static

Compute Jacobian of a desired function.

Refer to FiniteDifferencesInterface::computeJacobian() for more details.

EvalFun should be of type void(Eigen::VectorXd& values) or similar and should return current function values. IncFun should be of type void(int idx, double value) and should increment component idx by value.

Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[out]jacobianThe resulting Jacobian matrix (warning: jacobian must be preallocated as n x p matrix)

Definition at line 30 of file finite_differences.hpp.

◆ jacobianHessian()

template<typename IncFun , typename EvalFun >
void corbo::ForwardDifferences::jacobianHessian ( IncFun  inc_fun,
EvalFun  eval_fun,
Eigen::Ref< Eigen::MatrixXd >  jacobian,
Eigen::Ref< Eigen::MatrixXd >  hessian,
const double *  multipliers = nullptr 
)

Compute Jacobian and Hessian of a desired function.

This method is often faster than invoking jacobian and hessian separately.

Refer to FiniteDifferencesInterface::computeJacobianAndHessian() for more details.

EvalFun should be of type void(Eigen::VectorXd& values) or similar and should return current function values. IncFun should be of type void(int idx, double value) and should increment component idx by value. Parameter dim_f defines the dimension of the function provided by eval_fun. In case dim_f > 1, the hessian is computed for each dimension and summed up. Optionally, individual hessians might be scaled by a multiplier which is common in solving nonlinear programs (e.g., Lagrangian). If provided, the multiplier vector should be of size [dim_f x 1].

Parameters
[in]inc_funFunction callback to the increment operator function
[in]eval_funFunction callback to the function evaluation
[out]jacobianThe resulting Jacobian matrix (warning: jacobian must be preallocated as n x p matrix)
[out]hessianThe resulting Hessian matrix (warning: hessian must be preallocated as p x p matrix)
[in]multipliers(optional) Vector of multipliers for scaling individual Hessian terms [dim_f x 1].

Definition at line 106 of file finite_differences.hpp.

The documentation for this class was generated from the following files:

control_box_rst
Author(s): Christoph Rösmann
autogenerated on Mon Feb 28 2022 22:08:02