Karana.Integrators

Karana.Integrators#

Collection of classes to represent mathematical object used in Karana Dynamics simulations.

Examples include unit quaternions, homogeneous transforms, and spatial vectors.

Submodules#

Karana.Integrators.Integrator_types

Attributes#

`ArkExplicitIntegratorOptions`
`ArkImplicitIntegratorOptions`
`CVodeIntegratorOptions`

Classes#

`ArkExplicitIntegrator`	The multistep ArkODE explicit integrator from the SUNDIALS suite
`ArkExplicitIntegratorVars`	The Vars for the ArkExplicitIntegrator class.
`ArkImplicitIntegrator`	The (implicit) Adaptive Runge-Kutta integrator from the SUNDIALS suite
`ArkImplicitIntegratorVars`	The Vars for the ArkImplicitIntegrator class.
`CVodeIntegrator`	The multistep CVode integrator from the SUNDIALS suite
`CVodeIntegratorVars`	The Vars for the CVodeIntegrator class.
`EulerIntegrator`	The fixed-step Euler one step integrator.
`Integrator`	Base class for numerical integrators
`IntegratorOptions`	A struct with integrator options. This struct can be
`IntegratorType`	Enum of integrator types.
`RK4Integrator`	Fixed-step Runge-Kutta 4th order integrator
`SundialsImplicitIntegrator`	Abstract base class for implicit Sundials integrators (CVode/ARKStep).
`SundialsImplicitIntegratorOptions`	Struct with options for this integrator
`SundialsImplicitIntegratorVars`	The Vars for the SundialsImplicitIntegrator class.
`SundialsIntegrator`	Abstract base class for Sundials-related integrators.
`SundialsIntegratorOptions`	Struct with options for this integrator
`SundialsIntegratorVars`	The Vars for the SundialsIntegrator class.

Functions#

`createIntegrator`(…)	Factory method for creating DAE Integrator instances
`strToIntegratorType`(→ IntegratorType)	Convert string to IntegratorType enum.

Package Contents#

class Karana.Integrators.ArkExplicitIntegrator#

Bases: SundialsIntegrator, Integrator

The multistep ArkODE explicit integrator from the SUNDIALS suite

getAdaptiveStepping() → bool#

Check whether this integrator is using adaptive step sizes.

Returns:: A boolean corresponding to the adaptive status.

getErrorContributions() → Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]]#

Get the error contribution for each state.

Returns:: A vector with the error contribution for each state.

getVars() → ArkExplicitIntegratorVars#

setAdaptiveStepping(use_adaptive_steps: bool) → None#

Set whether adaptive timestepping should be used (defaults to true).

This converts all methods to fixed-step, regular variants. Prefer RK4Integrator unless you need a higher- or lower-order integration rule.

Parameters:: use_adaptive_steps – Whether to use adaptive steps (the default) or lock the step size.

setFixedStepSize(fixed_step_size: SupportsFloat | SupportsIndex) → None#

Set a fixed step size in fixed-step mode; must also disable adaptive steps via setAdaptiveStepping().

Parameters:: fixed_step_size – Target step size to take; a smaller step may be taken only to hit the target time.

Karana.Integrators.ArkExplicitIntegratorOptions#

class Karana.Integrators.ArkExplicitIntegratorVars#

Bases: SundialsIntegratorVars

The Vars for the ArkExplicitIntegrator class.

class Karana.Integrators.ArkImplicitIntegrator#

Bases: SundialsImplicitIntegrator

The (implicit) Adaptive Runge-Kutta integrator from the SUNDIALS suite

getErrorContributions() → Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]]#

Get the error contribution for each state.

Returns:: A vector with the error contribution for each state.

getVars() → ArkImplicitIntegratorVars#

Karana.Integrators.ArkImplicitIntegratorOptions#

class Karana.Integrators.ArkImplicitIntegratorVars#

Bases: SundialsImplicitIntegratorVars

The Vars for the ArkImplicitIntegrator class.

class Karana.Integrators.CVodeIntegrator#

Bases: SundialsImplicitIntegrator

The multistep CVode integrator from the SUNDIALS suite

getErrorContributions() → Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]]#

Get the error contribution for each state.

Returns:: A vector with the error contribution for each state.

getVars() → CVodeIntegratorVars#

Karana.Integrators.CVodeIntegratorOptions#

class Karana.Integrators.CVodeIntegratorVars#

Bases: SundialsImplicitIntegratorVars

The Vars for the CVodeIntegrator class.

property last_order: Karana.Core.VarInt#: Integration method order used during last step

class Karana.Integrators.EulerIntegrator#

Bases: Integrator

The fixed-step Euler one step integrator.

class Karana.Integrators.Integrator#

Bases: Karana.Core.BaseWithVars

Base class for numerical integrators

advanceTo(to_t: SupportsFloat | SupportsIndex | numpy.timedelta64) → numpy.timedelta64#

Method to advance the system state to a specified time

Parameters:: to_t – the desired end time
Returns:: the actual end time

derivFunction() → collections.abc.Callable[[SupportsFloat | SupportsIndex | numpy.timedelta64, Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]], Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]]], bool]#

Return the derivative function

Returns:: the derivative function

getIntegratorType() → IntegratorType#

Get the IntegratorType for this integrator.

Returns:: The IntegratorType for this integrator.

getOptions() → IntegratorOptions#

Get the options associated with the integrator.

Returns:: The options associated with the integrator.

getTime() → numpy.timedelta64#

Return the current integrator time

Returns:: the integrator state time

getX() → Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]]#

Return the current integrator state

Returns:: the integrator state vector

hardReset(nstates: SupportsInt | SupportsIndex) → None#

Reset the state size

Parameters:: nstates – the new state size

nStates() → int#

Return the state size

Returns:: the integrator state size

setVerboseTracing(verbose: bool) → None#

Tell the integrator to be very verbose; mostly used for debugging numerics in a brute-force approach.

Parameters:: verbose

softReset(new_t: SupportsFloat | SupportsIndex | numpy.timedelta64, new_x: Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]]) → None#

Reset the cached time and state and to the new values going forward

Parameters:

new_t – the new time
new_x – the new state

updateJacobian(arg0: Annotated[numpy.typing.ArrayLike, numpy.float64, [m, n]]) → None#

Update the stored Jacobian matrix with the provided one

This is currently an experimental feature - and not all integrators support the use of Jacobians.

Parameters:: mat – the new Jacobian matrix

class Karana.Integrators.IntegratorOptions#: A struct with integrator options. This struct can be

sub-classed by specialized classes to add custom options.

class Karana.Integrators.IntegratorType(*args, **kwds)#

Bases: enum.Enum

Enum of integrator types.

ARKEXPLICIT: ClassVar[IntegratorType]#

ARKEXPLICIT_CASH: ClassVar[IntegratorType]#

ARKEXPLICIT_DOPRI: ClassVar[IntegratorType]#

ARKEXPLICIT_FEHLBERG78: ClassVar[IntegratorType]#

ARKEXPLICIT_HUEN_EULER: ClassVar[IntegratorType]#

ARKIMPLICIT: ClassVar[IntegratorType]#

ARKIMPLICIT_DIRK23: ClassVar[IntegratorType]#

ARKIMPLICIT_ESDIRK45: ClassVar[IntegratorType]#

ARKIMPLICIT_SDIRK12: ClassVar[IntegratorType]#

ARKIMPLICIT_SDIRK34: ClassVar[IntegratorType]#

CVODE: ClassVar[IntegratorType]#

CVODE_NEWTON: ClassVar[IntegratorType]#

CVODE_STIFF: ClassVar[IntegratorType]#

EULER: ClassVar[IntegratorType]#

IDA: ClassVar[IntegratorType]#

NO_OP: ClassVar[IntegratorType]#

RK4: ClassVar[IntegratorType]#

classmethod to_yaml(representer, node)#: Class method used to represent IntegratorType in a yaml file.

classmethod from_yaml(_, node) → Self#: Construct a IntegratorType from yaml file data.

static to_json(o: IntegratorType) → dict[str, Any]#: Class method used to represent IntegratorType in a json file.

classmethod from_json(d: dict[str, Any]) → Self#: Construct a IntegratorType from json file data.

class Karana.Integrators.RK4Integrator#

Bases: Integrator

Fixed-step Runge-Kutta 4th order integrator

class Karana.Integrators.SundialsImplicitIntegrator#

Bases: SundialsIntegrator

Abstract base class for implicit Sundials integrators (CVode/ARKStep).

This class manages linear and nonlinear solvers specifically, and adds options and vars relating to implicit integration.

getOptions() → SundialsImplicitIntegratorOptions#

Get the options associated with the integrator.

Returns:: The options associated with the integrator.

setAndersonDamping(damping: SupportsFloat | SupportsIndex) → None#

Set the Anderson damping factor to use for nonlinear solves; must be in (0, 1] and smaller means stronger damping.

Parameters:: damping – Damping factor; pass a value of 1 for no damping.

setAndersonLength(length: SupportsInt | SupportsIndex) → None#

Set the subspace size to use for Anderson acceleration.

Parameters:: length – Damping factor; pass a value of 0 for no damping.

setMaxNLIters(iters: SupportsInt | SupportsIndex) → None#

Set the maximum nonlinear iterations.

Parameters:: iters – Max iters to take before trying a smaller timestep.

class Karana.Integrators.SundialsImplicitIntegratorOptions#

Bases: SundialsIntegratorOptions

Struct with options for this integrator

property anderson_damping: float#

Anderson damping in (0, 1] used for implicit integrators with fixed- point solves.

This is used to potentially speed up internal iterations by reusing past iterates (within the same time step). A value of 1 indicates no damping, and smaller values imply a “stronger” damping.

property anderson_length: int#: Number of past iterates to consider with Anderson acceleration.

property max_nl_iters: int#: Maximum number of nonlinear iterations before we try a smaller step size

property use_jacobian: bool#: set to true to have the integrator use Jacobians (experimental)

class Karana.Integrators.SundialsImplicitIntegratorVars#

Bases: SundialsIntegratorVars

The Vars for the SundialsImplicitIntegrator class.

property num_jac_evals: Karana.Core.VarLong#: Number of calls made to the CVLS Jacobian approximation function

property num_lin_iters: Karana.Core.VarLong#: Number of linear iterations

property num_lin_rhs_evals: Karana.Core.VarLong#: Number of RHS/derivative calls used to estimate jacobians

property num_nonlin_iters: Karana.Core.VarLong#: Number of nonlinear iterations

property num_step_solve_fails: Karana.Core.VarLong#: Number of rejected timesteps due to nonlinear solve failure

class Karana.Integrators.SundialsIntegrator#

Bases: Integrator

Abstract base class for Sundials-related integrators.

This class helps manage shared memory, options, and vars. It defines several pure virtual methods for the subclass to override and satisfies all virtual functions of an Integrator.

getOptions() → SundialsIntegratorOptions#

Get the options associated with the integrator.

Returns:: The options associated with the integrator.

setAtol(atol: SupportsFloat | SupportsIndex) → None#

Set the scalar absolute tolerance used for controlling error vs runtime.

Parameters:: atol – The scalar atol to use for all state variables.

setRtol(rtol: SupportsFloat | SupportsIndex) → None#

Set the relative tolerance used for controlling error vs runtime.

Parameters:: rtol – The rtol to use for all state variables.

setVectorAtol(atol_vec: Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]] | None) → None#

Set the vector absolute tolerance used for controlling error vs runtime, or a null value to fall back to scalar atol.

Parameters:: atol_vec – The optional vector atol to use; must have same length as state vector or be null.

class Karana.Integrators.SundialsIntegratorOptions#

Bases: IntegratorOptions

Struct with options for this integrator

property atol: float#: The desired absolute tolerance used to control the integrator error

property atol_vec: Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]] | None#: The desired absolute tolerance vector used to control the integrator error. This can be used rather than a scalar tolerance to set different values for different states.

property max_num_steps: int#: The maximum number of steps the solver can take before throwing a too much work error.

property min_step_size: float#: Minimum acceptable step size before we error out. Defaults to 1ns

property rtol: float#: The desired relative tolerance used to control the integrator error

class Karana.Integrators.SundialsIntegratorVars#

The Vars for the SundialsIntegrator class.

property curr_step: Karana.Core.VarDouble#: Current step size to try on next advance call

property last_step: Karana.Core.VarDouble#: Last successful step size

property num_err_test_fails: Karana.Core.VarLong#: Cumulative number of error test failures due to too large of step size

property num_rhs_evals: Karana.Core.VarLong#: Cumulative number of RHS calls taken by the solver

property num_steps: Karana.Core.VarLong#: Cumulative number of internal steps taken by the solver

Karana.Integrators.createIntegrator(integrator_type: IntegratorType, nstates: SupportsInt | SupportsIndex, deriv_fn: collections.abc.Callable, options: IntegratorOptions = None) → Integrator#

Karana.Integrators.createIntegrator(integrator_type: IntegratorType, nstates: SupportsInt | SupportsIndex, nalgebraic: SupportsInt | SupportsIndex, residuals_fn: collections.abc.Callable[[SupportsFloat | SupportsIndex | numpy.timedelta64, Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]], Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]], Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]]], None], options: IntegratorOptions = None) → Integrator

Factory method for creating DAE Integrator instances

Parameters:

integrator_type – the type of integrator to create
nstates – the length of the states vector (continuous+algebraic)
nalgebraic – the number of algebraic values
residuals_fn – the residuals function
options – options for the integrator

Returns:

a new DAE Integrator instance

Karana.Integrators.strToIntegratorType(arg0: str) → IntegratorType#

Convert string to IntegratorType enum.

Parameters:: str – The name of the integrator type.
Returns:: The IntegratorType associated with the string.