Drake
SemiExplicitEulerIntegrator< T > Class Template Referencefinal

A first-order, semi-explicit Euler integrator. More...

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

Inheritance diagram for SemiExplicitEulerIntegrator< T >:
Collaboration diagram for SemiExplicitEulerIntegrator< T >:

Public Member Functions

virtual ~SemiExplicitEulerIntegrator ()
 
 SemiExplicitEulerIntegrator (const System< T > &system, const T &max_step_size, Context< T > *context=nullptr)
 Constructs a fixed-step integrator for a given system using the given context for initial conditions. More...
 
int get_error_estimate_order () const override
 Gets the error estimate order (returns zero, since error estimation is not provided). More...
 
bool supports_error_estimation () const override
 Integrator does not support accuracy estimation. More...
 
- Public Member Functions inherited from IntegratorBase< T >
 IntegratorBase (const System< T > &system, Context< T > *context=nullptr)
 Maintains references to the system being integrated and the context used to specify the initial conditions for that system (if any). More...
 
virtual ~IntegratorBase ()=default
 Destructor. More...
 
void set_fixed_step_mode (bool flag)
 Sets an integrator with error control to fixed step mode. More...
 
bool get_fixed_step_mode () const
 Gets whether an integrator is running in fixed step mode. More...
 
void set_target_accuracy (double accuracy)
 Request that the integrator attempt to achieve a particular accuracy for the continuous portions of the simulation. More...
 
double get_target_accuracy () const
 Gets the target accuracy. More...
 
double get_accuracy_in_use () const
 Gets the accuracy in use by the integrator. More...
 
void set_maximum_step_size (const T &max_step_size)
 Sets the maximum step size that may be taken by this integrator. More...
 
const T & get_maximum_step_size () const
 Gets the maximum step size that may be taken by this integrator. More...
 
void Reset ()
 Resets the integrator to initial values, i.e., default construction values. More...
 
void Initialize ()
 An integrator must be initialized before being used. More...
 
void request_initial_step_size_target (const T &step_size)
 Request that the first attempted integration step have a particular size. More...
 
const T & get_initial_step_size_target () const
 Gets the target size of the first integration step. More...
 
StepResult IntegrateAtMost (const T &publish_dt, const T &update_dt, const T &boundary_dt)
 Integrates the system forward in time by a single step with step size subject to integration error tolerances (assuming that the integrator supports error estimation). More...
 
double get_stretch_factor () const
 Gets the stretch factor (> 1), which is multiplied by the maximum (typically user-designated) integration step size to obtain the amount that the integrator is able to stretch the maximum time step toward hitting an upcoming publish or update event in IntegrateAtMost(). More...
 
void IntegrateWithMultipleSteps (const T &dt)
 Stepping function for integrators operating outside of Simulator that advances the continuous state exactly by dt. More...
 
void IntegrateWithSingleFixedStep (const T &dt)
 Stepping function for integrators operating outside of Simulator that advances the continuous state exactly by dt and using a single fixed step. More...
 
const T & get_ideal_next_step_size () const
 Return the step size the integrator would like to take next, based primarily on the integrator's accuracy prediction. More...
 
const Context< T > & get_context () const
 Returns a const reference to the internally-maintained Context holding the most recent state in the trajectory. More...
 
Context< T > * get_mutable_context ()
 Returns a mutable pointer to the internally-maintained Context holding the most recent state in the trajectory. More...
 
void reset_context (Context< T > *context)
 Replace the pointer to the internally-maintained Context with a different one. More...
 
const System< T > & get_system () const
 Gets a constant reference to the system that is being integrated (and was provided to the constructor of the integrator). More...
 
bool is_initialized () const
 Indicates whether the integrator has been initialized. More...
 
const T & get_previous_integration_step_size () const
 Gets the size of the last (previous) integration step. More...
 
const ContinuousState< T > * get_error_estimate () const
 Gets the error estimate (used only for integrators that support error estimation). More...
 
 IntegratorBase (const IntegratorBase &)=delete
 
IntegratorBaseoperator= (const IntegratorBase &)=delete
 
 IntegratorBase (IntegratorBase &&)=delete
 
IntegratorBaseoperator= (IntegratorBase &&)=delete
 
void set_requested_minimum_step_size (const T &min_step_size)
 Sets the requested minimum step size h_min that may be taken by this integrator. More...
 
const T & get_requested_minimum_step_size () const
 Gets the requested minimum step size h_min for this integrator. More...
 
void set_throw_on_minimum_step_size_violation (bool throws)
 Sets whether the integrator should throw a std::runtime_error exception when the integrator's step size selection algorithm determines that it must take a step smaller than the minimum step size (for, e.g., purposes of error control). More...
 
bool get_throw_on_minimum_step_size_violation () const
 Reports the current setting of the throw_on_minimum_step_size_violation flag. More...
 
get_working_minimum_step_size () const
 Gets the current value of the working minimum step size h_work(t) for this integrator, which may vary with the current time t as stored in the integrator's context. More...
 
void ResetStatistics ()
 Forget accumulated statistics. More...
 
int64_t get_num_substep_failures () const
 Gets the number of failed sub-steps (implying one or more step size reductions was required to permit solving the necessary nonlinear system of equations). More...
 
int64_t get_num_step_shrinkages_from_substep_failures () const
 Gets the number of step size shrinkages due to sub-step failures (e.g., integrator convergence failures) since the last call to ResetStatistics() or Initialize(). More...
 
int64_t get_num_step_shrinkages_from_error_control () const
 Gets the number of step size shrinkages due to failure to meet targeted error tolerances, since the last call to ResetStatistics or Initialize(). More...
 
int64_t get_num_derivative_evaluations () const
 Returns the number of ODE function evaluations (calls to CalcTimeDerivatives()) since the last call to ResetStatistics() or Initialize(). More...
 
const T & get_actual_initial_step_size_taken () const
 The actual size of the successful first step. More...
 
const T & get_smallest_adapted_step_size_taken () const
 The size of the smallest step taken as the result of a controlled integration step adjustment since the last Initialize() or ResetStatistics() call. More...
 
const T & get_largest_step_size_taken () const
 The size of the largest step taken since the last Initialize() or ResetStatistics() call. More...
 
int64_t get_num_steps_taken () const
 The number of integration steps taken since the last Initialize() or ResetStatistics() call. More...
 
const Eigen::VectorXd & get_generalized_state_weight_vector () const
 Gets the weighting vector (equivalent to a diagonal matrix) applied to weighting both generalized coordinate and velocity state variable errors, as described in the group documentation. More...
 
Eigen::VectorBlock< Eigen::VectorXd > get_mutable_generalized_state_weight_vector ()
 Gets a mutable weighting vector (equivalent to a diagonal matrix) applied to weighting both generalized coordinate and velocity state variable errors, as described in the group documentation. More...
 
const Eigen::VectorXd & get_misc_state_weight_vector () const
 Gets the weighting vector (equivalent to a diagonal matrix) for weighting errors in miscellaneous continuous state variables z. More...
 
Eigen::VectorBlock< Eigen::VectorXd > get_mutable_misc_state_weight_vector ()
 Gets a mutable weighting vector (equivalent to a diagonal matrix) for weighting errors in miscellaneous continuous state variables z. More...
 

Additional Inherited Members

- Public Types inherited from IntegratorBase< T >
enum  StepResult {
  kReachedPublishTime = 1, kReachedZeroCrossing = 2, kReachedUpdateTime = 3, kTimeHasAdvanced = 4,
  kReachedBoundaryTime = 5, kReachedStepLimit = 6
}
 Status returned by StepOnceAtMost(). More...
 
- Protected Member Functions inherited from IntegratorBase< T >
virtual void DoResetStatistics ()
 Resets any statistics particular to a specific integrator. More...
 
void CalcTimeDerivatives (const Context< T > &context, ContinuousState< T > *dxdt)
 Evaluates the derivative function (and updates call statistics). More...
 
template<typename U >
void CalcTimeDerivatives (const System< U > &system, const Context< U > &context, ContinuousState< U > *dxdt)
 Evaluates the derivative function (and updates call statistics). More...
 
void set_accuracy_in_use (double accuracy)
 Sets the working ("in use") accuracy for this integrator. More...
 
bool StepOnceErrorControlledAtMost (const T &dt_max)
 Default code for advancing the continuous state of the system by a single step of dt_max (or smaller, depending on error control). More...
 
CalcStateChangeNorm (const ContinuousState< T > &dx_state) const
 Computes the infinity norm of a change in continuous state. More...
 
std::pair< bool, T > CalcAdjustedStepSize (const T &err, bool dt_was_artificially_limited, const T &current_step_size) const
 Calculates adjusted integrator step sizes toward keeping state variables within error bounds on the next integration step. More...
 
virtual void DoInitialize ()
 Derived classes can override this method to perform special initialization. More...
 
virtual void DoReset ()
 Derived classes can override this method to perform routines when Reset() is called. More...
 
ContinuousState< T > * get_mutable_error_estimate ()
 Gets an error estimate of the state variables recorded by the last call to StepOnceFixedSize(). More...
 
void set_actual_initial_step_size_taken (const T &dt)
 
void set_smallest_adapted_step_size_taken (const T &dt)
 Sets the size of the smallest-step-taken statistic as the result of a controlled integration step adjustment. More...
 
void set_largest_step_size_taken (const T &dt)
 
void set_ideal_next_step_size (const T &dt)
 

Detailed Description

template<class T>
class drake::systems::SemiExplicitEulerIntegrator< T >

A first-order, semi-explicit Euler integrator.

State is updated in the following manner:

v(t₀+h) = v(t₀) + dv/dt(t₀) * h
dq/dt  = N * v(t₀+h)
q(t₀+h) = q(t₀) + dq/dt * h

where v are the generalized velocity variables and q are generalized coordinates. h is the integration step size, and N is a matrix (dependent upon q(t₀)) that maps velocities to time derivatives of generalized coordinates. For rigid body systems in 2D, for example, N will generally be an identity matrix. For a single rigid body in 3D, N and its pseudo-inverse (N is generally non-square but always left invertible) are frequently used to transform between time derivatives of Euler parameters (unit quaternions) and angular velocities (and vice versa), [Nikravesh 1988].

Note that these equations imply that the velocity variables are updated first and that these new velocities are then used to update the generalized coordinates (compare to ExplicitEulerIntegrator, where the generalized coordinates are updated using the previous velocity variables).

When a mechanical system is Hamiltonian (informally meaning that the system is not subject to velocity-dependent forces), the semi-explicit Euler integrator is a symplectic (energy conserving) integrator. Symplectic integrators advertise energetically consistent behavior with large step sizes compared to non-symplectic integrators. Multi-body systems are not Hamiltonian, even in the absence of externally applied velocity-dependent forces, due to the presence of both Coriolis and gyroscopic forces. This integrator thus does not generally conserve energy for such systems.

Association between time stepping and the semi-explicit Euler integrator:

Though many time stepping approaches use the formulations above, these equations do not represent a "time stepping scheme". The semi-explicit Euler integration equations can be applied from one point in state space to another, assuming smoothness in between, just like any other integrator using the following process: (1) a simulator integrates to discontinuities, (2) the state of the ODE/DAE is re-initialized, and (3) integration continues.

In contrast, time stepping schemes enforce all constraints at a single time in the integration process: though a billiard break may consist of tens of collisions occurring sequentially over a millisecond of time, a time stepping method will treat all of these collisions as occurring simultaneously.

  • [Nikravesh 1988] P. Nikravesh. Computer-Aided Analysis of Mechanical Systems. Prentice Hall. New Jersey, 1988.
  • [Stewart 2000] D. Stewart. Rigid-body Dynamics with Friction and Impact. SIAM Review, 42:1, 2000.

Constructor & Destructor Documentation

virtual ~SemiExplicitEulerIntegrator ( )
inlinevirtual
SemiExplicitEulerIntegrator ( const System< T > &  system,
const T &  max_step_size,
Context< T > *  context = nullptr 
)
inline

Constructs a fixed-step integrator for a given system using the given context for initial conditions.

Parameters
systemA reference to the system to be simulated.
max_step_sizeThe maximum (fixed) step size; the integrator will not take larger step sizes than this.
contextPointer to the context (nullptr is ok, but the caller must set a non-null context before Initialize()-ing the integrator).
See also
Initialize()

Here is the call graph for this function:

Member Function Documentation

int get_error_estimate_order ( ) const
inlineoverridevirtual

Gets the error estimate order (returns zero, since error estimation is not provided).

Implements IntegratorBase< T >.

bool supports_error_estimation ( ) const
inlineoverridevirtual

Integrator does not support accuracy estimation.

Implements IntegratorBase< T >.

Here is the call graph for this function:


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