Description

Base class for implicit integrators.

Such integrators require solution of a nonlinear problem, solved using an iterative Newton process which requires the solution of a linear system at each iteration. A full Newton method uses a current matrix (based on the system Jacobian), updated and factorized at each iteration. Modified Newton methods use possibly out-of-date Jacobian information; the Jacobian can be evaluated at the beginning of the step only, kept constant for the duration of the entire simulation, or a Jacobian re-evaluation can be triggered automatically and adaptively, as necessary.

#include <ChTimestepperImplicit.h>

Inheritance diagram for chrono::ChTimestepperImplicit:

[legend]

Collaboration diagram for chrono::ChTimestepperImplicit:

[legend]

Public Types
enum	JacobianUpdate { JacobianUpdate::EVERY_ITERATION, JacobianUpdate::EVERY_STEP, JacobianUpdate::NEVER, JacobianUpdate::AUTOMATIC }
	Newton Jacobian update strategies. More...

Public Types inherited from chrono::ChTimestepper
enum	Type { EULER_EXPLICIT_I, EULER_EXPLICIT_II, EULER_SEMI_IMPLICIT, RUNGE_KUTTA, HEUN, LEAPFROG, EULER_IMPLICIT, EULER_IMPLICIT_LINEARIZED, EULER_IMPLICIT_PROJECTED, TRAPEZOIDAL, TRAPEZOIDAL_LINEARIZED, NEWMARK, HHT, CUSTOM }
	Methods for time integration.

Public Member Functions
void	SetMaxIters (int iters)
	Set the max number of Newton iterations.

void	SetRelTolerance (double rel_tol)
	Set the relative tolerance. More...

void	SetAbsTolerances (double abs_tolS, double abs_tolL)
	Set the absolute tolerances. More...

void	SetAbsTolerances (double abs_tol)
	Set the absolute tolerances. More...

void	SetJacobianUpdateMethod (JacobianUpdate method)
	Set the strategy for Jacobian update (default: EVERY_STEP).

double	GetMaxIters () const
	Get the max number of iterations using the Newton Raphson procedure.

JacobianUpdate	GetJacobianUpdateMethod () const
	Get the current Jacobian update startegy.

unsigned int	GetNumStepIterations () const
	Return the number of Newton iterations over the last step.

unsigned int	GetNumStepSetupCalls () const
	Return the number of calls to the solver's Setup function made during the last step.

unsigned int	GetNumStepSolveCalls () const
	Return the number of calls to the solver's Solve function made over the last step.

double	GetEstimatedConvergenceRate () const
	Get the last estimated convergence rate for the internal Newton solver. More...

unsigned int	GetNumIterations () const
	Return the cumulative number of Newton iterations.

unsigned int	GetNumSetupCalls () const
	Return the cummulative number of calls to the solver's Setup function.

unsigned int	GetNumSolveCalls () const
	Return the cumulative number of calls to the solver's Solve function.

void	AcceptTerminatedStep (bool accept)
	Accept step after a non-converged Newton solve (default: true). More...

unsigned int	GetNumTerminated () const
	Return the number of terminated Newton solves. More...

void	SetStepControl (bool enable)
	Turn on/off the internal step size control. More...

void	SetMinStepSize (double step)
	Set the minimum step size. More...

void	SetMaxItersSuccess (int iters)
	Set the maximum allowable number of iterations for counting a step towards a stepsize increase. More...

void	SetRequiredSuccessfulSteps (int num_steps)
	Set the minimum number of (internal) steps that use at most maxiters_success before considering a stepsize increase. More...

void	SetStepIncreaseFactor (double factor)
	Set the multiplicative factor for a stepsize increase (must be larger than 1). More...

void	SetStepDecreaseFactor (double factor)
	Set the multiplicative factor for a stepsize decrease (must be smaller than 1). More...

virtual void	Advance (double dt) override final
	Perform an integration step. More...

virtual void	ArchiveOut (ChArchiveOut &archive)
	Method to allow serialization of transient data to archives.

virtual void	ArchiveIn (ChArchiveIn &archive)
	Method to allow de-serialization of transient data from archives.

Public Member Functions inherited from chrono::ChTimestepper
virtual Type	GetType () const =0
	Return type of the integration method. More...

virtual ChIntegrable *	GetIntegrable () const =0
	Return the associated integrable object.

virtual ChVectorDynamic &	GetLagrangeMultipliers ()
	Access the Lagrange multipliers, if any.

virtual double	GetTime () const
	Get the current time.

virtual void	SetTime (double mt)
	Set the current time.

void	SetVerbose (bool verb)
	Turn on/off logging of messages.

Static Public Member Functions
static std::string	GetJacobianUpdateMethodAsString (JacobianUpdate jacobian_update)
	Return Jacobian update method as a string.

Static Public Member Functions inherited from chrono::ChTimestepper
static std::string	GetTypeAsString (Type type)
	Return the integrator type as a string.

Protected Member Functions
virtual void	OnAdvance (double dt)
	Implementation of integrator-specific time advance. More...

virtual void	InitializeStep ()
	Initialize integrator at beginning of a new step. More...

virtual void	PrepareStep ()
	Prepare integrator for attempting a new step. More...

virtual void	Increment ()
	Calculate new state increment for a Newton iteration. More...

virtual void	ResetStep ()
	Reset step data for re-attempting step (with new Jacobian or reduced step size). More...

virtual void	AcceptStep ()
	Accept attempted step (if Newton converged or was terminated). More...

virtual void	FinalizeStep ()
	Finalize step and update solution at end of step. More...

bool	CheckConvergence (int iteration)
	Check convergence of Newton process.

void	CalcErrorWeights (const ChVectorDynamic<> &x, double rtol, double atol, ChVectorDynamic<> &ewt)
	Calculate error weights based on the given state and tolerances.

Protected Member Functions inherited from chrono::ChTimestepper
	ChTimestepper (ChIntegrable *intgr=nullptr)

Protected Attributes
JacobianUpdate	jacobian_update_method
	Jacobian update strategy.

bool	call_setup
	should the solver's Setup function be called?

bool	call_analyze
	should the solver's Setup analyze phase be called?

bool	jacobian_is_current
	was the Jacobian evaluated at current Newton iteration?

unsigned int	max_iters
	maximum number of iterations

double	reltol
	relative tolerance

double	abstolS
	absolute tolerance (states)

double	abstolL
	absolute tolerance (Lagrange multipliers)

unsigned int	num_step_iters
	number of iterations during last step

unsigned int	num_step_setups
	number of calls to the solver Setup() function during last step

unsigned int	num_step_solves
	number of calls to the solver Solve() function during last step

unsigned int	num_iters
	current cumulative number of Newton iterations

unsigned int	num_setups
	current cumulative number of Setup() calls

unsigned int	num_solves
	current cummulative number of Solve() calls

unsigned int	num_terminated
	number of terminated NEwton iterations

double	convergence_rate
	estimated Newton rate of convergence

ChStateDelta	Ds
	state update

ChVectorDynamic	Dl
	Lagrange multiplier update.

ChVectorDynamic	R
	residual of nonlinear system (dynamics portion)

ChVectorDynamic	Qc
	residual of nonlinear system (constraints portion)

std::array< double, 3 >	Ds_nrm_hist
	last 3 update norms

std::array< double, 3 >	Dl_nrm_hist
	last 3 update norms

ChVectorDynamic	ewtS
	vector of error weights (states)

ChVectorDynamic	ewtL
	vector of error weights (Lagrange multipliers)

bool	accept_terminated
	accept or reject steps after a non-converged Newton solve

bool	step_control
	step size control enabled?

unsigned int	maxiters_success
	maximum number of NR iterations to declare a step successful

unsigned int	req_successful_steps
	required number of successive successful steps for a stepsize increase

double	step_increase_factor
	factor used in increasing stepsize (>1)

double	step_decrease_factor
	factor used in decreasing stepsize (<1)

double	h_min
	minimum allowable stepsize

double	h
	internal stepsize

unsigned int	num_successful_steps
	number of successful steps

Protected Attributes inherited from chrono::ChTimestepper
bool	verbose

double	T

ChVectorDynamic	L

bool	Qc_do_clamp

double	Qc_clamping

Member Enumeration Documentation

◆ JacobianUpdate

enum chrono::ChTimestepperImplicit::JacobianUpdate

strong

Newton Jacobian update strategies.

Enumerator
EVERY_ITERATION	Full Newton: Jacobian updated at every iteration.
EVERY_STEP	Jacobian updated at every step.
NEVER	Jacobian never updated.
AUTOMATIC	Automatic Jacobian update.

Member Function Documentation

◆ AcceptStep()

virtual void chrono::ChTimestepperImplicit::AcceptStep ( )

inlineprotectedvirtual

Accept attempted step (if Newton converged or was terminated).

Used only if no override of OnAdvance is provided.

◆ AcceptTerminatedStep()

void chrono::ChTimestepperImplicit::AcceptTerminatedStep ( bool accept )

inline

Accept step after a non-converged Newton solve (default: true).

If 'true', the solution at the end of a step is accepted as-is, even if the Newton nonlinear solve did not converge (even with an up-to-date Jacobian). If 'false', an exception is thrown if the Newton iterations do not converge after the allowed maximum number of iterations.

◆ Advance()

void chrono::ChTimestepperImplicit::Advance ( double dt )

finaloverridevirtual

Perform an integration step.

This base class manages the Newton iteration counters and defers the integrator implementation to OnAdvance.

Implements chrono::ChTimestepper.

◆ FinalizeStep()

virtual void chrono::ChTimestepperImplicit::FinalizeStep ( )

inlineprotectedvirtual

Finalize step and update solution at end of step.

Used only if no override of OnAdvance is provided.

◆ GetEstimatedConvergenceRate()

double chrono::ChTimestepperImplicit::GetEstimatedConvergenceRate ( ) const

inline

Get the last estimated convergence rate for the internal Newton solver.

Note that an estimate can only be calculated after the 3rd iteration. For the first 2 iterations, the convergence rate estimate is set to 1.

◆ GetNumTerminated()

unsigned int chrono::ChTimestepperImplicit::GetNumTerminated ( ) const

inline

Return the number of terminated Newton solves.

These are Newton solves that were terminated after the maximum number of iterations, without achieving convergence. The Jacobian is either up-to-date or cannot be re-evaluated (because the Jacobian update strategy is set to JacobianUpdate::NEVER) and step size cannot be reduced (because step-size control is disabled). The nonlinear system solution is accepted as-is.

◆ Increment()

virtual void chrono::ChTimestepperImplicit::Increment ( )

inlineprotectedvirtual

Calculate new state increment for a Newton iteration.

Used only if no override of OnAdvance is provided.

◆ InitializeStep()

virtual void chrono::ChTimestepperImplicit::InitializeStep ( )

inlineprotectedvirtual

Initialize integrator at beginning of a new step.

Used only if no override of OnAdvance is provided.

◆ OnAdvance()

void chrono::ChTimestepperImplicit::OnAdvance ( double dt )

protectedvirtual

Implementation of integrator-specific time advance.

This base class implementation provides support for an adaptive time-step, error-controlled integrator. A derived class using these features, must implement the functions . Otherwise, it must override OnAdvance.

Reimplemented in chrono::ChTimestepperNewmark, chrono::ChTimestepperTrapezoidalLinearized, chrono::ChTimestepperTrapezoidal, chrono::ChTimestepperEulerImplicitProjected, chrono::ChTimestepperEulerImplicitLinearized, and chrono::ChTimestepperEulerImplicit.

◆ PrepareStep()

virtual void chrono::ChTimestepperImplicit::PrepareStep ( )

inlineprotectedvirtual

Prepare integrator for attempting a new step.

Used only if no override of OnAdvance is provided.

◆ ResetStep()

virtual void chrono::ChTimestepperImplicit::ResetStep ( )

inlineprotectedvirtual

Reset step data for re-attempting step (with new Jacobian or reduced step size).

Used only if no override of OnAdvance is provided.

◆ SetAbsTolerances() [1/2]

void chrono::ChTimestepperImplicit::SetAbsTolerances ( double abs_tol )

inline

Set the absolute tolerances.

These tolerances are used in the Newton convergence test (optionally used by derived integrator classes). This version sets equal absolute tolerances for states and Lagrange multipliers.

◆ SetAbsTolerances() [2/2]

void chrono::ChTimestepperImplicit::SetAbsTolerances	(	double	abs_tolS,
		double	abs_tolL
	)

inline

Set the absolute tolerances.

These tolerances are used in the Newton convergence test (optionally used by derived integrator classes). This version sets separate absolute tolerances for states and Lagrange multipliers.

◆ SetMaxItersSuccess()

void chrono::ChTimestepperImplicit::SetMaxItersSuccess ( int iters )

inline

Set the maximum allowable number of iterations for counting a step towards a stepsize increase.

Default: 3.

◆ SetMinStepSize()

void chrono::ChTimestepperImplicit::SetMinStepSize ( double step )

inline

Set the minimum step size.

An exception is thrown if the internal step size decreases below this limit. Default: 1e-10.

◆ SetRelTolerance()

void chrono::ChTimestepperImplicit::SetRelTolerance ( double rel_tol )

inline

Set the relative tolerance.

This tolerance is used in the Newton convergence test (optionally used by derived integrator classes).

◆ SetRequiredSuccessfulSteps()

void chrono::ChTimestepperImplicit::SetRequiredSuccessfulSteps ( int num_steps )

inline

Set the minimum number of (internal) steps that use at most maxiters_success before considering a stepsize increase.

Default: 5.

◆ SetStepControl()

void chrono::ChTimestepperImplicit::SetStepControl ( bool enable )

inline

Turn on/off the internal step size control.

Default: true.

◆ SetStepDecreaseFactor()

void chrono::ChTimestepperImplicit::SetStepDecreaseFactor ( double factor )

inline

Set the multiplicative factor for a stepsize decrease (must be smaller than 1).

Default: 0.5.

◆ SetStepIncreaseFactor()

void chrono::ChTimestepperImplicit::SetStepIncreaseFactor ( double factor )

inline

Set the multiplicative factor for a stepsize increase (must be larger than 1).

Default: 2.

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

/builds/uwsbel/chrono/src/chrono/timestepper/ChTimestepperImplicit.h
/builds/uwsbel/chrono/src/chrono/timestepper/ChTimestepperImplicit.cpp

Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Member Enumeration Documentation

◆ JacobianUpdate

Member Function Documentation

◆ AcceptStep()

◆ AcceptTerminatedStep()

◆ Advance()

◆ FinalizeStep()

◆ GetEstimatedConvergenceRate()

◆ GetNumTerminated()

◆ Increment()

◆ InitializeStep()

◆ OnAdvance()

◆ PrepareStep()

◆ ResetStep()

◆ SetAbsTolerances() [1/2]

◆ SetAbsTolerances() [2/2]

◆ SetMaxItersSuccess()

◆ SetMinStepSize()

◆ SetRelTolerance()

◆ SetRequiredSuccessfulSteps()

◆ SetStepControl()

◆ SetStepDecreaseFactor()

◆ SetStepIncreaseFactor()