codi::Algorithms< T_Type, T_ActiveChecks > Struct Template Reference

Basic algorithms for tape evaluation in CoDiPack. More...

#include <algorithms.hpp>

Public Types
enum class	EvaluationType { Forward , Reverse }
	Evaluation modes for the derivative computation.
using	Gradient = typename Type::Gradient
	See LhsExpressionInterface.
using	GT = GradientTraits::TraitsImplementation< Gradient >
	Shortcut for traits of gradient.
using	Identifier = typename Type::Identifier
	See LhsExpressionInterface.
using	Position = typename Tape::Position
	See LhsExpressionInterface.
using	Real = typename Type::Real
	See LhsExpressionInterface.
using	Tape = typename Type::Tape
	See LhsExpressionInterface.
using	Type = T_Type
	See Algorithms.

Static Public Member Functions
template<typename Func , typename VecIn , typename VecOut , typename Hes , typename Jac = DummyJacobian>
static void	computeHessian (Func func, VecIn &input, VecOut &output, Hes &hes, Jac &jac=StaticDummy< DummyJacobian >::dummy)
	Compute the Hessian with multiple tape recordings and sweeps.
template<typename Func , typename VecIn , typename VecOut , typename Hes , typename Jac = DummyJacobian>
static void	computeHessianForward (Func func, VecIn &input, VecOut &output, Hes &hes, Jac &jac=StaticDummy< DummyJacobian >::dummy)
	Forward version of the Hessian computation with a function object.
template<typename Hes , typename Jac = DummyJacobian>
static void	computeHessianPrimalValueTape (Tape &tape, Position const &start, Position const &end, Identifier const *input, size_t const inputSize, Identifier const *output, size_t const outputSize, Hes &hes, Jac &jac=StaticDummy< DummyJacobian >::dummy)
	Compute the Hessian with multiple tape sweeps.
template<typename Hes , typename Jac = DummyJacobian>
static void	computeHessianPrimalValueTapeForward (Tape &tape, Position const &start, Position const &end, Identifier const *input, size_t const inputSize, Identifier const *output, size_t const outputSize, Hes &hes, Jac &jac=StaticDummy< DummyJacobian >::dummy)
	Forward version of the Hessian computation.
template<typename Hes , typename Jac = DummyJacobian>
static void	computeHessianPrimalValueTapeReverse (Tape &tape, Position const &start, Position const &end, Identifier const *input, size_t const inputSize, Identifier const *output, size_t const outputSize, Hes &hes, Jac &jac=StaticDummy< DummyJacobian >::dummy)
	Reverse version of the Hessian computation.
template<typename Func , typename VecIn , typename VecOut , typename Hes , typename Jac = DummyJacobian>
static void	computeHessianReverse (Func func, VecIn &input, VecOut &output, Hes &hes, Jac &jac=StaticDummy< DummyJacobian >::dummy)
	Reverse version of the Hessian computation with a function object.
template<typename Jac >
static void	computeJacobian (Position const &start, Position const &end, Identifier const *input, size_t const inputSize, Identifier const *output, size_t const outputSize, Jac &jac, AdjointsManagement adjointsManagement=AdjointsManagement::Automatic)
	Compute the Jacobian with multiple tape sweeps. This method uses the global tape for the Jacobian evaluation.
template<typename Jac , bool keepState = true>
static void	computeJacobian (Tape &tape, Position const &start, Position const &end, Identifier const *input, size_t const inputSize, Identifier const *output, size_t const outputSize, Jac &jac, AdjointsManagement adjointsManagement=AdjointsManagement::Automatic)
	Compute the Jacobian with multiple tape sweeps.
static EvaluationType	getEvaluationChoice (size_t const inputs, size_t const outputs)

Static Public Attributes
static bool constexpr	ActiveChecks = T_ActiveChecks
	See Algorithms.

Detailed Description

template<typename T_Type, bool T_ActiveChecks = true>
struct codi::Algorithms< T_Type, T_ActiveChecks >

Basic algorithms for tape evaluation in CoDiPack.

This class provides algorithms for:

• Jacobian assembly
• Hessian assembly

All algorithms try to make the best choice for the evaluation mode depending on the number of inputs and outputs, either forward or reverse. Which mode is selected can be queried in advance with the method Algorithms::getEvaluationChoice.

See Mathematical naming conventions for the naming conventions.

Hessians have to implement the HessianInterface and Jacobians have to implement the JacobianInterface.

Template Parameters

T_Type	An ActiveReal type that has a tape which implements the ReverseTapeInterface
ActiveChecks	If activity checks for the seeding of gradient data should be performed. [Default: true]

Member Function Documentation

computeHessian()

template<typename T_Type , bool T_ActiveChecks = true>

template<typename Func , typename VecIn , typename VecOut , typename Hes , typename Jac = DummyJacobian>

static void codi::Algorithms< T_Type, T_ActiveChecks >::computeHessian ( Func  func, VecIn &  input, VecOut &  output, Hes &  hes, Jac &  jac = StaticDummy<DummyJacobian>::dummy  )

inlinestatic

Compute the Hessian with multiple tape recordings and sweeps.

The algorithm will repeatedly evaluated the function func and record the evaluation on the global tape. It expects that the tape is empty. The tape needs to be able to compute second order derivatives via a nested first order forward type.

After the return, the algorithm ensures that the tape is empty.

It has to hold start < end.

Parameters

[in] func The function for the recording of the tape. It needs to be a function object that will accept the call: func(input, output)
[in,out] hes Has to implement HessianInterface.
[in,out] jac Optional: Jacobian values are also extracted. Has to implement JacobianInterface.

computeHessianForward()

template<typename T_Type , bool T_ActiveChecks = true>

template<typename Func , typename VecIn , typename VecOut , typename Hes , typename Jac = DummyJacobian>

static void codi::Algorithms< T_Type, T_ActiveChecks >::computeHessianForward ( Func  func, VecIn &  input, VecOut &  output, Hes &  hes, Jac &  jac = StaticDummy<DummyJacobian>::dummy  )

inlinestatic

Forward version of the Hessian computation with a function object.

One input variable is seeded with gradient information and then a tape is recorded. Afterwards a second input variable is seeded with gradient information and the tape is evaluated multiple times in the forward mode. Before each recording the global tape is reset.

The algorithm will record n tapes and exploits symmetry for the forward evaluation which will result in n * (n + 1) / 2 forward tape evaluations. Vector gradient values for the first and second order derivatives will reduce the tape evaluations accordingly.

The algorithm will repeatedly evaluated the function func and record the evaluation on the global tape. It expects that the tape is empty. The tape needs to be able to compute second order derivatives via a nested first order forward type.

After the return, the algorithm ensures that the tape is empty.

It has to hold start < end.

Parameters

[in] func The function for the recording of the tape. It needs to be a function object that will accept the call: func(input, output)
[in,out] hes Has to implement HessianInterface.
[in,out] jac Optional: Jacobian values are also extracted. Has to implement JacobianInterface.

computeHessianPrimalValueTape()

template<typename T_Type , bool T_ActiveChecks = true>

template<typename Hes , typename Jac = DummyJacobian>

static void codi::Algorithms< T_Type, T_ActiveChecks >::computeHessianPrimalValueTape ( Tape &  tape, Position const &  start, Position const &  end, Identifier const *  input, size_t const  inputSize, Identifier const *  output, size_t const  outputSize, Hes &  hes, Jac &  jac = StaticDummy<DummyJacobian>::dummy  )

inlinestatic

Compute the Hessian with multiple tape sweeps.

This algorithm is only available if the tape implements the PrimalEvaluationTapeInterface. It performs repeated primal evaluations to change the original seeding of the tape. It also requires that the tape can compute second order derivatives via a nested first order forward type.

The algorithm expects that no gradients have been seeded with nonzero values. It also expects that the current tape state was just recorded, that is, the primal values in the tape represent the output values of f. At return, it is ensured that all gradients have zero values.

It has to hold start < end.

Parameters

[in,out] hes Has to implement HessianInterface.
[in,out] jac Optional: Jacobian values are also extracted. Has to implement JacobianInterface.

computeHessianPrimalValueTapeForward()

template<typename T_Type , bool T_ActiveChecks = true>

template<typename Hes , typename Jac = DummyJacobian>

static void codi::Algorithms< T_Type, T_ActiveChecks >::computeHessianPrimalValueTapeForward ( Tape &  tape, Position const &  start, Position const &  end, Identifier const *  input, size_t const  inputSize, Identifier const *  output, size_t const  outputSize, Hes &  hes, Jac &  jac = StaticDummy<DummyJacobian>::dummy  )

inlinestatic

Forward version of the Hessian computation.

Two input variables are seeded with gradient information and then a forward evaluation is performed. Before each evaluation, the primal values of the tape are reverted to the start position.

The algorithm exploits symmetry and will perform n * (n + 1) / 2 forward tape evaluation. Vector gradient values for the first and second order derivatives will reduce the tape evaluations accordingly.

This algorithm is only available if the tape implements the PrimalEvaluationTapeInterface. It performs repeated primal evaluations to change the original seeding of the tape. It also requires that the tape can compute second order derivatives via a nested first order forward type.

The algorithm expects that no gradients have been seeded with nonzero values. It also expects that the current tape state was just recorded, that is, the primal values in the tape represent the output values of f. At return, it is ensured that all gradients have zero values.

It has to hold start < end.

Parameters

[in,out] hes Has to implement HessianInterface.
[in,out] jac Optional: Jacobian values are also extracted. Has to implement JacobianInterface.

computeHessianPrimalValueTapeReverse()

template<typename T_Type , bool T_ActiveChecks = true>

template<typename Hes , typename Jac = DummyJacobian>

static void codi::Algorithms< T_Type, T_ActiveChecks >::computeHessianPrimalValueTapeReverse ( Tape &  tape, Position const &  start, Position const &  end, Identifier const *  input, size_t const  inputSize, Identifier const *  output, size_t const  outputSize, Hes &  hes, Jac &  jac = StaticDummy<DummyJacobian>::dummy  )

inlinestatic

Reverse version of the Hessian computation.

One input variable is seeded with gradient information and then a forward evaluation is performed. Afterwards, one output variable is seeded with gradient information and then a reverse evaluation is performed.

The algorithm cannot exploit symmetry and will perform n forward evaluation and n * m reverse evaluations. Vector gradient values for the first and second order derivatives will reduce the tape evaluations accordingly.

This algorithm is only available if the tape implements the PrimalEvaluationTapeInterface. It performs repeated primal evaluations to change the original seeding of the tape. It also requires that the tape can compute second order derivatives via a nested first order forward type.

The algorithm expects that no gradients have been seeded with nonzero values. It also expects that the current tape state was just recorded, that is, the primal values in the tape represent the output values of f. At return, it is ensured that all gradients have zero values.

It has to hold start < end.

Parameters

[in,out] hes Has to implement HessianInterface.
[in,out] jac Optional: Jacobian values are also extracted. Has to implement JacobianInterface.

computeHessianReverse()

template<typename T_Type , bool T_ActiveChecks = true>

template<typename Func , typename VecIn , typename VecOut , typename Hes , typename Jac = DummyJacobian>

static void codi::Algorithms< T_Type, T_ActiveChecks >::computeHessianReverse ( Func  func, VecIn &  input, VecOut &  output, Hes &  hes, Jac &  jac = StaticDummy<DummyJacobian>::dummy  )

inlinestatic

Reverse version of the Hessian computation with a function object.

One input variable is seeded with gradient information and then a tape is recorded. Afterwards an output variable is seeded with gradient information and the tape is evaluated once in the reverse mode. Before each recording, the global tape is reset.

The algorithm will record n tapes and perform m * n reverse tape evaluations. Vector gradient values for the first and second order derivatives will reduce the tape evaluations accordingly.

The algorithm will repeatedly evaluated the function func and record the evaluation on the global tape. It expects that the tape is empty. The tape needs to be able to compute second order derivatives via a nested first order forward type.

After the return, the algorithm ensures that the tape is empty.

It has to hold start < end.

Parameters

[in] func The function for the recording of the tape. It needs to be a function object that will accept the call: func(input, output)
[in,out] hes Has to implement HessianInterface.
[in,out] jac Optional: Jacobian values are also extracted. Has to implement JacobianInterface.

computeJacobian() [1/2]

template<typename T_Type , bool T_ActiveChecks = true>

template<typename Jac >

static void codi::Algorithms< T_Type, T_ActiveChecks >::computeJacobian ( Position const &  start, Position const &  end, Identifier const *  input, size_t const  inputSize, Identifier const *  output, size_t const  outputSize, Jac &  jac, AdjointsManagement  adjointsManagement = AdjointsManagement::Automatic  )

inlinestatic

Compute the Jacobian with multiple tape sweeps.
This method uses the global tape for the Jacobian evaluation.

The following prerequisites must be met.

• It must hold start < end.
• The gradient for every identifier used in the tape section [start, end] is seeded with zero.
• Every input to the tape section [start, end] that is a computational dependency of the specified outputs is contained in the specified inputs.

The function has the following behavior.

• After return, the gradient for every input identifier, output identifier and all identifiers used in the tape section [start, end] on a left hand side are zero.
• If an output identifier is specified multiple times
  • and the forward mode is used, every row of the Jacobian corresponding to that output identifier except for the last one is zero.
  • and the reverse mode is used, every row of the Jacobian corresponding to that output identifier is identical.
• If an input identifier is specified multiple times
  • and the forward mode is used, every column of the Jacobian corresponding to that input identifier is identical.
  • and the reverse mode is used, every column of the Jacobian corresponding to that input identifier except for the first one is zero.

The following usage is recommended.

• There should be no duplicate identifiers among the specified inputs.
• There should be no duplicate identifiers among the specified outputs.

The following usage is allowed.

• The specified input identifiers and output identifiers need not be disjoint.

The algorithm conforms with the mechanism for mutual exclusion of adjoint vector usage and adjoint vector reallocation and can therefore be applied in multithreaded taping.

In the case of manual adjoints management, the caller is responsible for ensuring sufficient adjoint vector size and for declaring usage of the adjoints, see codi::AdjointsManagement for details.

Parameters

[in,out] jac Has to implement JacobianInterface.

computeJacobian() [2/2]

template<typename T_Type , bool T_ActiveChecks = true>

template<typename Jac , bool keepState = true>

static void codi::Algorithms< T_Type, T_ActiveChecks >::computeJacobian ( Tape &  tape, Position const &  start, Position const &  end, Identifier const *  input, size_t const  inputSize, Identifier const *  output, size_t const  outputSize, Jac &  jac, AdjointsManagement  adjointsManagement = AdjointsManagement::Automatic  )

inlinestatic

Compute the Jacobian with multiple tape sweeps.

The following prerequisites must be met.

• It must hold start < end.
• The gradient for every identifier used in the tape section [start, end] is seeded with zero.
• Every input to the tape section [start, end] that is a computational dependency of the specified outputs is contained in the specified inputs.

The function has the following behavior.

• After return, the gradient for every input identifier, output identifier and all identifiers used in the tape section [start, end] on a left hand side are zero.
• If an output identifier is specified multiple times
  • and the forward mode is used, every row of the Jacobian corresponding to that output identifier except for the last one is zero.
  • and the reverse mode is used, every row of the Jacobian corresponding to that output identifier is identical.
• If an input identifier is specified multiple times
  • and the forward mode is used, every column of the Jacobian corresponding to that input identifier is identical.
  • and the reverse mode is used, every column of the Jacobian corresponding to that input identifier except for the first one is zero.

The following usage is recommended.

• There should be no duplicate identifiers among the specified inputs.
• There should be no duplicate identifiers among the specified outputs.

The following usage is allowed.

• The specified input identifiers and output identifiers need not be disjoint.

The algorithm conforms with the mechanism for mutual exclusion of adjoint vector usage and adjoint vector reallocation and can therefore be applied in multithreaded taping.

In the case of manual adjoints management, the caller is responsible for ensuring sufficient adjoint vector size and for declaring usage of the adjoints, see codi::AdjointsManagement for details.

Parameters

[in,out] jac Has to implement JacobianInterface.

getEvaluationChoice()

template<typename T_Type , bool T_ActiveChecks = true>

static EvaluationType codi::Algorithms< T_Type, T_ActiveChecks >::getEvaluationChoice ( size_t const  inputs, size_t const  outputs  )

inlinestatic

Returns the preferred evaluation mode depending on the number of inputs and outputs. If the number of inputs is smaller than the number of outputs, a forward evaluation will be chosen. Otherwise, a reverse evaluation is preferred.

---

The documentation for this struct was generated from the following file:

• include/codi/tools/algorithms.hpp