InitialValueProblem< T > Class Template Reference

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 scalar type, which must be one of the default nonsymbolic scalars.

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

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 Eigen::Ref< const VectorX< T >> &x0, const Eigen::Ref< const VectorX< T >> &k=Vector0< T >{})
	Constructs an IVP described by the given ode_function, using x0 as initial conditions, and parameterized with k. More...
VectorX< T >	Solve (const T &t0, const T &tf) const
	Solves the IVP from the initial time t0 up to time tf, using the initial state vector 𝐱₀ and parameter vector 𝐤 provided in the constructor. More...
std::unique_ptr< DenseOutput< T > >	DenseSolve (const T &t0, const T &tf) const
	Solves and yields an approximation of the IVP solution x(t; 𝐤) for the closed time interval between the given initial time t0 and the given final time tf, using initial state 𝐱₀ and parameter vector 𝐤 provided in the constructor. More...
template<typename Integrator , typename... Args>
Integrator *	reset_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 reference to the internal integrator instance. More...
IntegratorBase< T > &	get_mutable_integrator ()
	Gets a mutable reference to the internal integrator instance. More...
Does not allow copy, move, or assignment
	InitialValueProblem (const InitialValueProblem &)=delete
InitialValueProblem &	operator= (const InitialValueProblem &)=delete
	InitialValueProblem (InitialValueProblem &&)=delete
InitialValueProblem &	operator= (InitialValueProblem &&)=delete

Static Public Attributes
static const double	kDefaultAccuracy
	Default integration accuracy in the relative tolerance sense. More...
static const double	kInitialStepSize
	Default initial integration step size. More...
static const double	kMaxStepSize
	Default maximum integration step size. More...

Member Typedef Documentation

OdeFunction

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.

Parameters

t	The independent scalar variable t ∈ ℝ.
x	The dependent vector variable 𝐱 ∈ ℝⁿ.
k	The vector of parameters 𝐤 ∈ ℝᵐ.

Returns

The derivative vector d𝐱/dt ∈ ℝⁿ.

Constructor & Destructor Documentation

InitialValueProblem() [1/3]

InitialValueProblem ( const InitialValueProblem< T > &  )

delete

InitialValueProblem() [2/3]

InitialValueProblem ( InitialValueProblem< T > &&  )

delete

InitialValueProblem() [3/3]

InitialValueProblem	(	const OdeFunction &	ode_function,
		const Eigen::Ref< const VectorX< T >> &	x0,
		const Eigen::Ref< const VectorX< T >> &	k = Vector0< T >{}
	)

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

Parameters

ode_function	The ODE function f(t, 𝐱; 𝐤) that describes the state evolution over time.
x0	The initial state vector 𝐱₀ ∈ ℝⁿ.
k	The parameter vector 𝐤 ∈ ℝᵐ. By default m=0 (no parameters).

Member Function Documentation

DenseSolve()

std::unique_ptr<DenseOutput<T> > DenseSolve	(	const T &	t0,
		const T &	tf
	)		const

Solves and yields an approximation of the IVP solution x(t; 𝐤) for the closed time interval between the given initial time t0 and the given final time tf, using initial state 𝐱₀ and parameter vector 𝐤 provided in the constructor.

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, which must be ≥ t₀. Usually, t₀ < tf as an empty dense output would result if t₀ = tf.

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.

Exceptions

std::exception

if t0 > tf.

get_integrator()

const IntegratorBase<T>& get_integrator

(

)

const

Gets a reference to the internal integrator instance.

get_mutable_integrator()

IntegratorBase<T>& get_mutable_integrator

(

)

Gets a mutable reference to the internal 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

)

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 &	t0,
		const T &	tf
	)		const

Solves the IVP from the initial time t0 up to time tf, using the initial state vector 𝐱₀ and parameter vector 𝐤 provided in the constructor.

Exceptions

std::exception

if t0 > tf.

Member Data Documentation

kDefaultAccuracy

const double kDefaultAccuracy

static

Default integration accuracy in the relative tolerance sense.

kInitialStepSize

const double kInitialStepSize

static

Default initial integration step size.

kMaxStepSize

const double kMaxStepSize

static

Default maximum integration step size.

---

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

• drake/systems/analysis/initial_value_problem.h