Drake
InitialValueProblem< T > Class Template Reference

A general initial value problem (or IVP) representation class, that allows evaluating the ๐ฑ(t; ๐ค) solution function to the given ODE d๐ฑ/dt = f(t, ๐ฑ; ๐ค), where f : t โจฏ ๐ฑ โ โโฟ, t โ โ, ๐ฑ โ โโฟ, ๐ค โ โแต, provided an initial condition ๐ฑ(tโ; ๐ค) = ๐ฑโ. More...

#include <drake/systems/analysis/initial_value_problem.h>

## Classes

struct  SpecifiedValues
A collection of values i.e. More...

## Public Types

using ODEFunction = std::function< VectorX< T >(const T &t, const VectorX< T > &x, const VectorX< T > &k)>
General ODE system d๐ฑ/dt = f(t, ๐ฑ; ๐ค) function type. More...

## Public Member Functions

InitialValueProblem (const ODEFunction &ode_function, const SpecifiedValues &default_values)
Constructs an IVP described by the given ode_function, using given default_values.t0 and default_values.x0 as initial conditions, and parameterized with default_values.k by default. More...

VectorX< TSolve (const T &tf, const SpecifiedValues &values={}) const
Solves the IVP for time tf, using the initial time tโ, initial state vector ๐ฑโ and parameter vector ๐ค present in values, falling back to the ones given on construction if not given. More...

std::unique_ptr< DenseOutput< T > > DenseSolve (const T &tf, const SpecifiedValues &values={}) const
Solves and yields an approximation of the IVP solution x(t; ๐ค) for the closed time interval between the initial time tโ and the given final time tf, using initial state ๐ฑโ and parameter vector ๐ค present in values (falling back to the ones given on construction if not given). More...

template<typename Integrator , typename... Args>
Integratorreset_integrator (Args &&... args)
Resets the internal integrator instance by in-place construction of the given integrator type. More...

const IntegratorBase< T > * get_integrator () const
Gets a pointer to the internal integrator instance. More...

IntegratorBase< T > * get_mutable_integrator ()
Gets a pointer to the internal mutable integrator instance. More...

Does not allow copy, move, or assignment
InitialValueProblem (const InitialValueProblem &)=delete

InitialValueProblemoperator= (const InitialValueProblem &)=delete

InitialValueProblem (InitialValueProblem &&)=delete

InitialValueProblemoperator= (InitialValueProblem &&)=delete

## Static Public Attributes

static const double kDefaultAccuracy = 1e-4
Default integration accuracy in the relative tolerance sense. More...

static const T kInitialStepSize = static_cast<T>(1e-4)
Default initial integration step size. More...

static const T kMaxStepSize = static_cast<T>(1e-1)
Default maximum integration step size. More...

## Detailed Description

### template<typename T> class drake::systems::InitialValueProblem< T >

A general initial value problem (or IVP) representation class, that allows evaluating the ๐ฑ(t; ๐ค) solution function to the given ODE d๐ฑ/dt = f(t, ๐ฑ; ๐ค), where f : t โจฏ ๐ฑ โ โโฟ, t โ โ, ๐ฑ โ โโฟ, ๐ค โ โแต, provided an initial condition ๐ฑ(tโ; ๐ค) = ๐ฑโ.

The parameter vector ๐ค allows for generic IVP definitions, which can later be solved for any instance of said vector.

By default, an explicit 3rd order RungeKutta integration scheme is used.

The implementation of this class performs basic computation caching, optimizing away repeated integration whenever the IVP is solved for increasing values of time t while both initial conditions and parameters are kept constant, e.g. if solved for tโ > tโ first, solving for tโ > tโ will only require integrating from tโ onward.

Additionally, IntegratorBase's dense output support can be leveraged to efficiently approximate the IVP solution within closed intervals of t. This is convenient when there's a need for a more dense sampling of the IVP solution than what would be available through either fixed or error-controlled step integration (for a given accuracy), or when the IVP is to be solved repeatedly for arbitrarily many t values within a given interval. See documentation of the internally held IntegratorBase subclass instance (either the default or a user-defined one, set via reset_integrator()) for further reference on the specific dense output technique in use.

For further insight into its use, consider the following examples:

• The momentum ๐ฉ of a particle of mass m that is traveling through a volume of a gas with dynamic viscosity ฮผ can be described by d๐ฉ/dt = -ฮผ * ๐ฉ/m. At time tโ, the particle carries an initial momentum ๐ฉโ. In this context, t is unused (the ODE is autonomous), ๐ฑ โ ๐ฉ, ๐ค โ [m, ฮผ], tโ = 0, ๐ฑโ โ ๐ฉโ, d๐ฑ/dt = f(t, ๐ฑ; ๐ค) = -kโ * ๐ฑ / kโ.
• The velocity ๐ฏ of the same particle in the same exact conditions as before, but when a time varying force ๐(t) is applied to it, can be be described by d๐ฏ/dt = (๐(t) - ฮผ * ๐ฏ) / m. In this context, ๐ฑ โ ๐ฏ, ๐ค โ [m, ฮผ], ๐ฑโ โ ๐ฏโ, d๐ฑ/dt = f(t, ๐ฑ; ๐ค) = (๐(t) - kโ * ๐ฑ) / kโ.
Template Parameters
 T The โ domain scalar type, which must be a valid Eigen scalar.
Note
Instantiated templates for the following scalar types T are provided:
• double

## ◆ ODEFunction

 using ODEFunction = std::function ( const T& t, const VectorX& x, const VectorX& k)>

General ODE system d๐ฑ/dt = f(t, ๐ฑ; ๐ค) function type.

Parameters
 t The independent scalar variable t โ โ. x The dependent vector variable ๐ฑ โ โโฟ. k The vector of parameters ๐ค โ โแต.
Returns
The derivative vector d๐ฑ/dt โ โโฟ.

## ◆ InitialValueProblem() [1/3]

 InitialValueProblem ( const InitialValueProblem< T > & )
delete

## ◆ InitialValueProblem() [2/3]

 InitialValueProblem ( InitialValueProblem< T > && )
delete

## ◆ InitialValueProblem() [3/3]

 InitialValueProblem ( const ODEFunction & ode_function, const SpecifiedValues & default_values )

Constructs an IVP described by the given ode_function, using given default_values.t0 and default_values.x0 as initial conditions, and parameterized with default_values.k by default.

Parameters
 ode_function The ODE function f(t, ๐ฑ; ๐ค) that describes the state evolution over time. default_values The values specified by default for this IVP, i.e. default initial time tโ โ โ and state vector ๐ฑโ โ โโฟ, and default parameter vector ๐ค โ โแต.
Precondition
An initial time default_values.t0 is given.
An initial state vector default_values.x0 is given.
A parameter vector default_values.k is given.
Exceptions
 std::logic_error if preconditions are not met.

## ◆ DenseSolve()

 std::unique_ptr< DenseOutput< T > > DenseSolve ( const T & tf, const SpecifiedValues & values = {} ) const

Solves and yields an approximation of the IVP solution x(t; ๐ค) for the closed time interval between the initial time tโ and the given final time tf, using initial state ๐ฑโ and parameter vector ๐ค present in values (falling back to the ones given on construction if not given).

To this end, the wrapped IntegratorBase instance solves this IVP, advancing time and state from tโ and ๐ฑโ = ๐ฑ(tโ) to tf and ๐ฑ(tf), creating a dense output over that [tโ, tf] interval along the way.

Parameters
 tf The IVP will be solved up to this time. Usually, tโ < tf as an empty dense output would result if tโ = tf. values IVP initial conditions and parameters.
Returns
A dense approximation to ๐ฑ(t; ๐ค) with ๐ฑ(tโ; ๐ค) = ๐ฑโ, defined for tโ โค t โค tf.
Note
The larger the given tf value is, the larger the approximated interval will be. See documentation of the specific dense output technique in use for reference on performance impact as this interval grows.
Precondition
Given tf must be larger than or equal to the specified initial time tโ (either given or default).
If given, the dimension of the initial state vector values.x0 must match that of the default initial state vector in the default specified values given on construction.
If given, the dimension of the parameter vector values.k must match that of the parameter vector in the default specified values given on construction.
Exceptions
 std::logic_error if any of the preconditions is not met.

## ◆ get_integrator()

 const IntegratorBase* get_integrator ( ) const
inline

Gets a pointer to the internal integrator instance.

## ◆ get_mutable_integrator()

 IntegratorBase* get_mutable_integrator ( )
inline

Gets a pointer to the internal mutable integrator instance.

## ◆ operator=() [1/2]

 InitialValueProblem& operator= ( const InitialValueProblem< T > & )
delete

## ◆ operator=() [2/2]

 InitialValueProblem& operator= ( InitialValueProblem< T > && )
delete

## ◆ reset_integrator()

 Integrator* reset_integrator ( Args &&... args )
inline

Resets the internal integrator instance by in-place construction of the given integrator type.

A usage example is shown below.

ivp.reset_integrator<RungeKutta2Integrator<T>>(max_step);
Parameters
 args The integrator type-specific arguments.
Returns
The new integrator instance.
Template Parameters
 Integrator The integrator type, which must be an IntegratorBase subclass. Args The integrator specific argument types.
Warning
This operation invalidates pointers returned by InitialValueProblem::get_integrator() and InitialValueProblem::get_mutable_integrator().

## ◆ Solve()

 VectorX< T > Solve ( const T & tf, const SpecifiedValues & values = {} ) const

Solves the IVP for time tf, using the initial time tโ, initial state vector ๐ฑโ and parameter vector ๐ค present in values, falling back to the ones given on construction if not given.

Parameters
 tf The IVP will be solved for this time. values IVP initial conditions and parameters.
Returns
The IVP solution ๐ฑ(tf; ๐ค) for ๐ฑ(tโ; ๐ค) = ๐ฑโ.
Precondition
Given tf must be larger than or equal to the specified initial time tโ (either given or default).
If given, the dimension of the initial state vector values.x0 must match that of the default initial state vector in the default specified values given on construction.
If given, the dimension of the parameter vector values.k must match that of the parameter vector in the default specified values given on construction.
Exceptions
 std::logic_error if preconditions are not met.

## ◆ kDefaultAccuracy

 const double kDefaultAccuracy = 1e-4
static

Default integration accuracy in the relative tolerance sense.

## ◆ kInitialStepSize

 const T kInitialStepSize = static_cast(1e-4)
static

Default initial integration step size.

## ◆ kMaxStepSize

 const T kMaxStepSize = static_cast(1e-1)
static

Default maximum integration step size.

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