Template Class ImplicitTrapezoidal

Nested Relationships

Nested Types

Class Documentation

template<class ScalarT, typename IdxT>
class ImplicitTrapezoidal

Fixed-step implicit trapezoidal integrator for index-one ODEs and DAEs.

Nonlinear systems are solved with Newton’s method and an Armijo backtracking line search.

Public Functions

ImplicitTrapezoidal(GridKit::Model::Evaluator<ScalarT, IdxT> *model, GridKit::LinearAlgebra::LinearSolver<ScalarT, IdxT> &linear_solver, GridKit::LinearAlgebra::VectorHandler<ScalarT, IdxT> &vector_handler, const ErrorNorm<ScalarT, IdxT> *error_norm, GridKit::memory::MemorySpace memspace = GridKit::memory::HOST)

Construct an implicit trapezoidal integrator.

The supplied model, linear solver, vector handler, and error norm must remain valid for the lifetime of the integrator.

Parameters:

  • model – [inout] Model defining \(F(t,y,\dot{y})=0\).

  • linear_solver – [inout] Solver used for Newton systems.

  • vector_handler – [inout] Vector operations used by the integrator.

  • error_norm – [in] Norm used to test Newton corrections for convergence.

  • memspace – [in] Memory space in which vectors are stored and operated on.

int allocate()

Allocate the integrator’s internal vectors.

Returns:

Zero on success and a nonzero error code on failure.

int initializeSimulation(RealT t0)

Initialize integration from the state currently exposed by the model.

The model’s y() and yp() vectors provide \(y_0\) and \(\dot{y}_0\), respectively. This call also configures the linear solver for the model’s analytic CSR Jacobian and resets all statistics and cached-factorization state.

Parameters:

t0 – [in] Initial simulation time.

Returns:

Zero on success and a nonzero error code on failure.

int integrate(const std::vector<RealT> &output_times, Parameters parameters = {}, std::optional<std::function<void(RealT)>> output_callback = {}, std::optional<std::function<void(const StepInfo&)>> step_callback = {})

Integrate through a sequence of requested output times.

Internal steps always use Parameters::step_size_. Output times between accepted steps are reported using linear interpolation without changing the accepted internal state. During an output callback, the model exposes the state, derivative, and time associated with that output.

Parameters:

  • output_times – [in] Times at which output is requested, in increasing order.

  • parameters – [in] Fixed-step and nonlinear-solver parameters.

  • output_callback – [in] Optional callback invoked at every output time.

  • step_callback – [in] Optional callback invoked after every accepted internal step.

Returns:

Zero on success and a nonzero error code on failure.

int timeStep(RealT t0, RealT dt, const Parameters &parameters = {})

Advance the solution by one fixed step.

Newton’s method starts from the predictor \(y_{n+1}^{(0)}=y_n+dt\,\dot{y}_n\). If the nonlinear solve fails, the last accepted model state and time are restored and the cached Jacobian factorization is invalidated.

Parameters:

  • t0 – [in] Current accepted simulation time.

  • dt – [in] Step size to take.

  • parameters – [in] Nonlinear-solver parameters.

Returns:

Zero on success and a nonzero error code on failure.

inline const Stats &getStats() const

Return running solver statistics.

inline RealT getCurrentTime() const

Return the time of the current accepted internal state.

struct Parameters

Parameters controlling fixed stepping and the nonlinear solve.

Public Members

RealT step_size_ = 1.0 / 240.0

Fixed internal step size.

size_t max_steps_ = 10000

Maximum number of accepted internal steps.

size_t max_newton_iterations_ = 16

Maximum number of linear solves allowed in one nonlinear step.

RealT armijo_constant_ = 1e-4

Sufficient-decrease constant used by the Armijo line search.

RealT backtrack_factor_ = 0.5

Factor by which the line-search step length is reduced.

RealT minimum_step_length_ = 1e-8

Smallest line-search step length that may be attempted.

RealT stagnation_ratio_ = 0.9

Residual-merit reduction ratio above which a Newton iteration is stagnant.

size_t max_stagnant_iterations_ = 2

Consecutive stagnant iterations that trigger a Jacobian refresh.

size_t max_jacobian_refreshes_ = 1

Maximum Jacobian refreshes permitted during one nonlinear step.

struct StepInfo

Information about one accepted internal step.

Public Members

RealT sim_time_ = {}

Simulation time at the end of the step.

RealT step_size_ = {}

Step size used for the step.

size_t step_no_ = {}

Accepted step number, starting at one.

size_t newton_iterations_ = {}

Number of Newton linear solves performed during the step.

size_t backtracks_ = {}

Number of rejected line-search trial points during the step.

struct Stats

Running solver statistics since the last initializeSimulation() call.

Public Members

size_t num_steps_ = 0

Number of accepted internal steps.

size_t num_newton_iterations_ = 0

Number of Newton linear solves.

size_t num_residual_evaluations_ = 0

Number of model residual evaluations.

size_t num_jacobian_evaluations_ = 0

Number of model Jacobian evaluations.

size_t num_jacobian_reuses_ = 0

Number of steps that reused a factorization from an earlier step.

size_t num_jacobian_refreshes_ = 0

Number of within-step Jacobian refreshes caused by poor convergence.

size_t num_linear_solves_ = 0

Number of solves with a factored Newton matrix.

size_t num_backtracks_ = 0

Number of rejected line-search trial points.

size_t num_convergence_failures_ = 0

Number of internal steps that failed to converge.