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

Classes#

`ArkExplicitIntegrator`	The multistep ArkODE explicit integrator from the SUNDIALS suite
`ArkExplicitIntegratorOptions`	Struct with options for this integrator
`CVodeIntegrator`	The multistep CVode integrator from the SUNDIALS suite
`CVodeIntegratorOptions`	Struct with options for this integrator
`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
`SundialsIntegrator`	Abstract base class for Sundials-related integrators.
`SundialsIntegratorOptions`	Struct with options for this integrator

Functions#

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

class Karana.Integrators.ArkExplicitIntegratorOptions#

Bases: SundialsIntegratorOptions

Struct with options for this integrator

class Karana.Integrators.CVodeIntegrator#

Bases: SundialsIntegrator, Integrator

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.

class Karana.Integrators.CVodeIntegratorOptions#

Bases: SundialsIntegratorOptions

Struct with options for this integrator

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

static create(integrator_type: IntegratorType, nstates: SupportsInt | SupportsIndex, deriv_fn: collections.abc.Callable[[SupportsFloat | SupportsIndex | numpy.timedelta64, Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]], Annotated[numpy.typing.ArrayLike, numpy.float64, [m, 1]]], None], options: IntegratorOptions = None) → Integrator#

static create(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 a 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

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

Method to advance the system state to a specified time :param 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]]], None]#: 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.

__assign__(arg0: IntegratorOptions) → IntegratorOptions#

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]#

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.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.

setAtol(atol: SupportsFloat | SupportsIndex) → None#

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.

class Karana.Integrators.SundialsIntegratorOptions#

Bases: IntegratorOptions

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 atol: float#: The desired absolute tolerance used to control the integrator error

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

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

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

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.