Drake
Drake C++ Documentation
AntiderivativeFunction< T > Class Template Reference

Detailed Description

template<typename T>
class drake::systems::AntiderivativeFunction< T >

A thin wrapper of the ScalarInitialValueProblem class that, in concert with Drake's ODE initial value problem solvers ("integrators"), provide the ability to perform quadrature on an arbitrary scalar integrable function.

That is, it allows the evaluation of an antiderivative function F(u; 𝐤), such that F(u; 𝐤) = ∫ᵥᵘ f(x; 𝐤) dx where f : ℝ → ℝ , u ∈ ℝ, v ∈ ℝ, 𝐤 ∈ ℝᵐ. The parameter vector 𝐤 allows for generic function definitions, which can later be evaluated for any instance of said vector. Also, note that 𝐤 can be understood as an m-tuple or as an element of ℝᵐ, the vector space, depending on how it is used by the integrable function.

See ScalarInitialValueProblem class documentation for information on caching support and dense output usage for improved efficiency in antiderivative function F evaluation.

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

  • Solving the elliptic integral of the first kind E(φ; ξ) = ∫ᵠ √(1 - ξ² sin² θ)⁻¹ dθ becomes straightforward by defining f(x; 𝐤) ≜ √(1 - k₀² sin² x)⁻¹ with 𝐤 ≜ [ξ] and evaluating F(u; 𝐤) at u = φ.
  • As the bearings in a rotating machine age over time, these are more likely to fail. Let γ be a random variable describing the time to first bearing failure, described by a family of probability density functions gᵧ(y; l) parameterized by bearing load l. In this context, the probability of a bearing under load to fail during the first N months becomes P(0 < γ ≤ N mo.; l) = Gᵧ(N mo.; l) - Gᵧ(0; l), where Gᵧ(y; l) is the family of cumulative density functions, parameterized by bearing load l, and G'ᵧ(y; l) = gᵧ(y; l). Therefore, defining f(x; 𝐤) ≜ gᵧ(x; k₀) with 𝐤 ≜ [l] and evaluating F(u; 𝐤) at u = N yields the result.
Template Parameters
TThe scalar type, which must be one of the default nonsymbolic scalars.

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

Public Types

using IntegrableFunction = std::function< T(const T &x, const VectorX< T > &k)>
 Scalar integrable function f(x; 𝐤) type. More...
 

Public Member Functions

 AntiderivativeFunction (const IntegrableFunction &integrable_function, const Eigen::Ref< const VectorX< T >> &k=Vector0< T >{})
 Constructs the antiderivative function of the given integrable_function, parameterized with k. More...
 
Evaluate (const T &v, const T &u) const
 Evaluates the definite integral F(u; 𝐤) = ∫ᵥᵘ f(x; 𝐤) dx from the lower integration bound v to u using the parameter vector 𝐤 specified in the constructor (see definition in class documentation). More...
 
std::unique_ptr< ScalarDenseOutput< T > > MakeDenseEvalFunction (const T &v, const T &w) const
 Evaluates and yields an approximation of the definite integral F(u; 𝐤) = ∫ᵥᵘ f(x; 𝐤) dx for v ≤ u ≤ w, i.e. More...
 
template<typename Integrator , typename... Args>
Integratorreset_integrator (Args &&... args)
 Resets the internal integrator instance. 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
 AntiderivativeFunction (const AntiderivativeFunction &)=delete
 
AntiderivativeFunctionoperator= (const AntiderivativeFunction &)=delete
 
 AntiderivativeFunction (AntiderivativeFunction &&)=delete
 
AntiderivativeFunctionoperator= (AntiderivativeFunction &&)=delete
 

Member Typedef Documentation

◆ IntegrableFunction

using IntegrableFunction = std::function<T(const T& x, const VectorX<T>& k)>

Scalar integrable function f(x; 𝐤) type.

Parameters
xThe variable of integration x ∈ ℝ .
kThe parameter vector 𝐤 ∈ ℝᵐ.
Returns
The function value f(x; k).

Constructor & Destructor Documentation

◆ AntiderivativeFunction() [1/3]

◆ AntiderivativeFunction() [2/3]

◆ AntiderivativeFunction() [3/3]

AntiderivativeFunction ( const IntegrableFunction integrable_function,
const Eigen::Ref< const VectorX< T >> &  k = Vector0< T >{} 
)

Constructs the antiderivative function of the given integrable_function, parameterized with k.

Parameters
integrable_functionThe function f(x; 𝐤) to be integrated.
𝐤∈ ℝᵐ is the vector of parameters. The default is the empty vector (indicating no parameters).

Member Function Documentation

◆ Evaluate()

T Evaluate ( const T &  v,
const T &  u 
) const

Evaluates the definite integral F(u; 𝐤) = ∫ᵥᵘ f(x; 𝐤) dx from the lower integration bound v to u using the parameter vector 𝐤 specified in the constructor (see definition in class documentation).

Parameters
vThe lower integration bound.
uThe upper integration bound.
Returns
The value of the definite integral.
Exceptions
std::exceptionif v > u.

◆ 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.

◆ MakeDenseEvalFunction()

std::unique_ptr<ScalarDenseOutput<T> > MakeDenseEvalFunction ( const T &  v,
const T &  w 
) const

Evaluates and yields an approximation of the definite integral F(u; 𝐤) = ∫ᵥᵘ f(x; 𝐤) dx for v ≤ u ≤ w, i.e.

the closed interval that goes from the lower integration bound v to the uppermost integration bound w, using the parameter vector 𝐤 specified in the constructor (see definition in class documentation).

To this end, the wrapped IntegratorBase instance solves the integral from v to w (i.e. advances the state x of its differential form x'(t) = f(x; 𝐤) from v to w), creating a scalar dense output over that [v, w] interval along the way.

Parameters
vThe lower integration bound.
wThe uppermost integration bound. Usually, v < w as an empty dense output would result if v = w.
Returns
A dense approximation to F(u; 𝐤) (that is, a function), defined for v ≤ u ≤ w.
Note
The larger the given w value is, the larger the approximated interval will be. See documentation of the specific dense output technique used by the internally held IntegratorBase subclass instance for more details.
Exceptions
std::exceptionif v > w.

◆ operator=() [1/2]

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

◆ operator=() [2/2]

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

◆ reset_integrator()

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

Resets the internal integrator instance.

A usage example is shown below.

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

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