CoDiPack  2.2.0
A Code Differentiation Package
SciComp TU Kaiserslautern
Loading...
Searching...
No Matches
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:

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_TypeAn ActiveReal type that has a tape which implements the ReverseTapeInterface
ActiveChecksIf 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: