Class CVodeIntegrator

• Defined in File Integrator.h

Nested Relationships

Nested Types

• Struct CVodeIntegrator::IntegratorOptions

Inheritance Relationships

Base Type

• public Karana::Integrators::SundialsImplicitIntegrator (Class SundialsImplicitIntegrator)

Class Documentation

class CVodeIntegrator : public Karana::Integrators::SundialsImplicitIntegrator

The multistep CVode integrator from the SUNDIALS suite.

Public Functions

std::string getStallLogFile() const

Query the automatically generated stall-trace filename.

Returns:

Output basename, or empty while monitoring is disabled.

CVodeIntegrator(const IntegratorType &integrator_type, size_t num_states, size_t num_q_states, DerivativeFunction f, const IntegratorOptions *options = nullptr)

Constructor.

Parameters:

• num_states – The number of states to integrate.

• num_q_states – Number of leading Q states; zero means no partition is specified.

• f – The derivative function to calculate the derivative of the states.

• integrator_type – The type of cvode integrator to use.

• options – The integrator options.

virtual ~CVodeIntegrator()

virtual const kc::ks_ptr<Integrator::IntegratorOptions> getOptions() const override

Get the options associated with the integrator.

Returns:

The options associated with the integrator.

virtual km::Vec getErrorContributions() const override

Get the error contribution for each state.

Returns:

A vector with the error contribution for each state.

void setMaxOrder(int order)

Set the maximum multistep order; zero restores the method default. Lowering below active history restarts that history at the current state/time, preserving cumulative work counters. Invalid values leave options unchanged.

Parameters:

order – Zero, or 1..12 for Adams / 1..5 for BDF.

void setEtaFixedStepBounds(double lower, double upper)

Experimental: retain step size for proposed ratios strictly between the bounds.

See also

https://sundials.readthedocs.io/en/latest/cvode/Usage/index.html#c.CVodeSetEtaFixedStepBounds

Parameters:

• lower – Finite lower bound in [0, 1]; raising it permits more decreases.

• upper – Finite upper bound >= 1 and > lower; raising it suppresses more increases.

void setStabilityLimitDetection(bool enabled)

Experimental: toggle BDF stability-limit detection. May reset or reduce num_stab_lim_order_reductions.

See also

https://sundials.readthedocs.io/en/latest/cvode/Usage/index.html#c.CVodeSetStabLimDet

Parameters:

enabled – True only for BDF; false is supported for every CVODE preset.

virtual void setLinearSetupFrequency(long frequency) final

Set the number of integration steps between linear-solver setups.

Parameters:

frequency – Setup frequency; zero selects the SUNDIALS default.

virtual void setJacobianEvalFrequency(long frequency) final

Set the number of integration steps between Jacobian evaluations.

Parameters:

frequency – Evaluation frequency; zero selects the SUNDIALS default.

void setDetectStalls(bool enabled)

Turn stall monitoring and its HDF5 log on or off (default false).

Turning monitoring on creates a uniquely named cvode_stall_trace file in the current folder. The monitor reports when CVODE suddenly needs far more calculations, is forced to take unusually small time steps, or repeatedly retries steps. The file includes the measurements just before the slowdown and while CVODE returns to normal. Turning monitoring off finishes and closes the file but keeps the total number of stalls found.

Parameters:

enabled – True to start monitoring; false to stop it.

bool getDetectStalls() const

Query monitoring without a log file.

Returns:

Whether automatic stall monitoring and tracing are enabled.

long getStallCount() const

Read how many stalls have been found.

Returns:

Number of stalls found since the last full reset.

long getLastAdvanceSteps() const

Read the number of successful solver steps used most recently.

Returns:

Number of successful solver steps.

long getLastAdvanceRhsEvals() const

Read how many derivative calculations were used most recently.

Returns:

Number of derivative calculations.

long getLastAdvanceErrorTestFailures() const

Read how many attempted steps failed the error check most recently.

Returns:

Number of failed error checks.

km::Mat estimateDynamicsJacobian() const

Estimate the RHS Jacobian at the current state with finite differences.

Column j contains d(f)/d(x_j). The CVODE vector and solver history are not changed. Central differences use 1e-6 * max(1, abs(x_j)); one-sided differences are used when only one trial state is accepted. Uses Math::Jacobian with 2*nStates()+2 RHS calls for valid probes, plus one reflected evaluation per rejected probe. Columns rejected on both sides contain NaN. The base callback is reevaluated on exit, including after a probe exception, to restore state-dependent model caches. Arbitrary irreversible callback side effects cannot be undone; callbacks must support repeatable evaluation. No solver counters, solution vector, or multistep history are modified. Raw Jacobian entries have mixed physical units; callers should scale before ranking. Do not call during an active integration or from a derivative callback.

Throws:

std::runtime_error – If the base derivative is invalid or cannot be restored.

Returns:

An nStates() by nStates() numerical Jacobian.

Public Static Functions

static kc::ks_ptr<CVodeIntegrator> create(const IntegratorType &integrator_type, size_t num_states, size_t num_q_states, DerivativeFunction deriv_fn, const IntegratorOptions *options = nullptr)

Factory method for creating CVodeIntegrator instances.

Parameters:

• integrator_type – the type of integrator to create

• num_states – the length of the states vector

• num_q_states – Number of leading Q states; zero means no partition is specified.

• deriv_fn – the derivative function

• options – options for the integrator

Returns:

a new CVode Integrator instance

Protected Functions

bool _usingBDF() const

Identify the multistep family selected by the preset.

Returns:

True for BDF presets, false for Adams presets.

void _validateMethodOptions() const

Validate all CVODE controls before allocating native solver memory.

virtual void _rolloverCachedStats() override

Preserve completed native stability reductions across soft resets.

virtual void _initialize() final

Initialize the implementation-specific data structures.

void _bindCounterGetters()

Bind cached counters to CVODE optional-output getters.

virtual void _resetStats() override

Clear CVODE and quasi-Newton counters after a hard reset.

virtual void _freeMemory() final

Free implementation-specific SUNDIALS memory.

virtual void _applyTolerances() final

Copy tolerances from internal options into implementation data structures.

virtual void _reInit() final

Reinitialize internal implementation state for a soft reset.

virtual void _advanceTo(double t_end) final

Advances implementation to a target time; called by parent class.

Parameters:

t_end –

virtual void _bindSolvers() final

Bind internal nonlinear (and possibly linear) solvers to the implementation solver.

virtual Karana::Core::ks_ptr<Karana::Core::BaseVars> _getVars() const final

Create the vars for this object.

Returns:

The vars for this object.

void _resetQuasiNewtonCache()

Invalidate the quasi-Newton history after solver reinitialization.

StallDetector::StallDiagnostics _readStallDiagnostics() const

Read Vars-backed totals, including history preserved across soft resets.

Returns:

A copy of the stall diagnostics container

Protected Attributes

void *_cvode_mem = nullptr

Memory used by the cvode integrator.

kc::ks_ptr<CVodeIntegrator::IntegratorOptions> _opts

CVode-specific integrator options.

CachedCounter<long int> _num_stab_lim_order_reductions

Native stability reductions accumulated before previous reinitializations.

km::Mat _quasi_matrix

Current dense quasi-Newton matrix.

km::Vec _quasi_previous_state

State at the previous Jacobian callback.

int _quasi_age = 0

Number of partial-update callbacks since the last full refresh.

long int _num_quasi_rhs_evals = 0

Extra physical RHS evaluations performed by the quasi-Newton callback.

long int _num_quasi_full_refreshes = 0

Complete finite-difference quasi-Newton refreshes.

long int _num_quasi_partial_refreshes = 0

Motion-ranked partial quasi-Newton refreshes.

long int _num_quasi_probes = 0

Fixed-time quasi-Newton secant probes.

long int _num_quasi_refreshed_columns = 0

Finite-difference columns refreshed by quasi-Newton.

std::unique_ptr<StallDetector> _stall_detector

Optional detector; absent on the default-disabled path.

Protected Static Functions

static int _proj_fn(sunrealtype t, N_Vector ycur, N_Vector corr, sunrealtype eps_proj, N_Vector err, void *user_data)

Function to projects the state back onto a constraint manifold.

Parameters:

• t – The time to use when calculating the derivative.

• ycur – The current integrator state.

• corr – A correction vector c that gets populated such that (ycur + c) lives on the constraint manifold.

• eps_proj – Tolerance for projection routine to use internally.

• err – Data used to by the derivative function.

• user_data – Data used to by the derivative function.

Returns:

An error code indicating if the call was successful or not.

static int _ode_quasi_jacobian(sunrealtype t, N_Vector y, N_Vector fy, SUNMatrix matrix, void *user_data, N_Vector tmp1, N_Vector tmp2, N_Vector tmp3)

Construct the motion-ranked quasi-Newton dense Jacobian for CVODE.

Parameters:

• t – Current linearization time.

• y – Current state.

• fy – RHS at the current state.

• matrix – Destination dense matrix.

• user_data – Owning CVodeIntegrator.

• tmp1 – CVODE scratch vector.

• tmp2 – CVODE scratch vector.

• tmp3 – CVODE scratch vector.

Returns:

Zero on success and a positive value for a recoverable failure.

struct IntegratorOptions : public Karana::Integrators::SundialsImplicitIntegrator::IntegratorOptions

CVODE multistep controls shared by its Adams and BDF presets.

Public Members

int max_order = 0

Maximum integration order; 0 uses the default (Adams 12, BDF 5).

See also

https://sundials.readthedocs.io/en/latest/cvode/Usage/index.html#c.CVodeSetMaxOrd

double eta_min_fx = 0.0

Experimental: lower bound of the step-size ratio deadband after successful integration steps.

See also

https://sundials.readthedocs.io/en/latest/cvode/Usage/index.html#c.CVodeSetEtaFixedStepBounds

double eta_max_fx = 1.5

Experimental: upper bound of the step-size ratio deadband after successful integration steps.

See also

https://sundials.readthedocs.io/en/latest/cvode/Usage/index.html#c.CVodeSetEtaFixedStepBounds

bool stability_limit_detection = false

Experimental: reduce BDF order when a stability limit is detected (BDF only). Toggling may reset or reduce num_stab_lim_order_reductions.

See also

https://sundials.readthedocs.io/en/latest/cvode/Usage/index.html#c.CVodeSetStabLimDet