Karana.Integrators ================== .. py:module:: Karana.Integrators .. autoapi-nested-parse:: Collection of classes to represent mathematical object used in Karana Dynamics simulations. Examples include unit quaternions, homogeneous transforms, and spatial vectors. Submodules ---------- .. toctree:: :maxdepth: 1 /generated/python_api/Karana/Integrators/Integrator_types/index Classes ------- .. autoapisummary:: Karana.Integrators.ArkExplicitIntegrator Karana.Integrators.ArkExplicitIntegratorOptions Karana.Integrators.CVodeIntegrator Karana.Integrators.CVodeIntegratorOptions Karana.Integrators.EulerIntegrator Karana.Integrators.Integrator Karana.Integrators.IntegratorOptions Karana.Integrators.IntegratorType Karana.Integrators.RK4Integrator Karana.Integrators.SundialsIntegrator Karana.Integrators.SundialsIntegratorOptions Functions --------- .. autoapisummary:: Karana.Integrators.strToIntegratorType Package Contents ---------------- .. py:class:: ArkExplicitIntegrator Bases: :py:obj:`SundialsIntegrator`, :py:obj:`Integrator` The multistep ArkODE explicit integrator from the SUNDIALS suite .. py:class:: ArkExplicitIntegratorOptions Bases: :py:obj:`SundialsIntegratorOptions` Struct with options for this integrator .. py:class:: CVodeIntegrator Bases: :py:obj:`SundialsIntegrator`, :py:obj:`Integrator` The multistep CVode integrator from the SUNDIALS suite .. py:method:: 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. .. py:class:: CVodeIntegratorOptions Bases: :py:obj:`SundialsIntegratorOptions` Struct with options for this integrator .. py:class:: EulerIntegrator Bases: :py:obj:`Integrator` The fixed-step Euler one step integrator. .. py:class:: Integrator Bases: :py:obj:`Karana.Core.BaseWithVars` Base class for numerical integrators .. py:method:: 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 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 :staticmethod: Factory method for creating a DAE Integrator instances :param integrator_type: the type of integrator to create :param nstates: the length of the states vector (continuous+algebraic) :param nalgebraic: the number of algebraic values :param residuals_fn: the residuals function :param options: options for the integrator :returns: a new DAE Integrator instance .. py:method:: 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 .. py:method:: 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 .. py:method:: getIntegratorType() -> IntegratorType Get the IntegratorType for this integrator. :returns: The IntegratorType for this integrator. .. py:method:: getOptions() -> IntegratorOptions Get the options associated with the integrator. :returns: The options associated with the integrator. .. py:method:: getTime() -> numpy.timedelta64 Return the current integrator time :returns: the integrator state time .. py:method:: getX() -> Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]] Return the current integrator state :returns: the integrator state vector .. py:method:: hardReset(nstates: SupportsInt | SupportsIndex) -> None Reset the state size :param nstates: the new state size .. py:method:: nStates() -> int Return the state size :returns: the integrator state size .. py:method:: setVerboseTracing(verbose: bool) -> None Tell the integrator to be very verbose; mostly used for debugging numerics in a brute-force approach. :param verbose: .. py:method:: 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 :param new_t: the new time :param new_x: the new state .. py:method:: 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. :param mat: the new Jacobian matrix .. py:class:: IntegratorOptions A struct with integrator options. This struct can be sub-classed by specialized classes to add custom options. .. py:method:: __assign__(arg0: IntegratorOptions) -> IntegratorOptions .. py:class:: IntegratorType(*args, **kwds) Bases: :py:obj:`enum.Enum` Enum of integrator types. .. py:attribute:: ARKEXPLICIT :type: ClassVar[IntegratorType] .. py:attribute:: ARKEXPLICIT_CASH :type: ClassVar[IntegratorType] .. py:attribute:: ARKEXPLICIT_DOPRI :type: ClassVar[IntegratorType] .. py:attribute:: ARKEXPLICIT_FEHLBERG78 :type: ClassVar[IntegratorType] .. py:attribute:: ARKEXPLICIT_HUEN_EULER :type: ClassVar[IntegratorType] .. py:attribute:: CVODE :type: ClassVar[IntegratorType] .. py:attribute:: CVODE_NEWTON :type: ClassVar[IntegratorType] .. py:attribute:: CVODE_STIFF :type: ClassVar[IntegratorType] .. py:attribute:: EULER :type: ClassVar[IntegratorType] .. py:attribute:: IDA :type: ClassVar[IntegratorType] .. py:attribute:: NO_OP :type: ClassVar[IntegratorType] .. py:attribute:: RK4 :type: ClassVar[IntegratorType] .. py:method:: to_yaml(representer, node) :classmethod: Class method used to represent IntegratorType in a yaml file. .. py:method:: from_yaml(_, node) -> Self :classmethod: Construct a IntegratorType from yaml file data. .. py:method:: to_json(o: IntegratorType) -> dict[str, Any] :staticmethod: Class method used to represent IntegratorType in a json file. .. py:method:: from_json(d: dict[str, Any]) -> Self :classmethod: Construct a IntegratorType from json file data. .. py:class:: RK4Integrator Bases: :py:obj:`Integrator` Fixed-step Runge-Kutta 4th order integrator .. py:class:: SundialsIntegrator Bases: :py:obj:`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. .. py:method:: setAtol(atol: SupportsFloat | SupportsIndex) -> None setAtol(atol: SupportsFloat | SupportsIndex) -> None Set the scalar absolute tolerance used for controlling error vs runtime. :param atol: The scalar atol to use for all state variables. .. py:method:: setRtol(rtol: SupportsFloat | SupportsIndex) -> None Set the relative tolerance used for controlling error vs runtime. :param rtol: The rtol to use for all state variables. .. py:class:: SundialsIntegratorOptions Bases: :py:obj:`IntegratorOptions` Struct with options for this integrator .. py:property:: anderson_damping :type: 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. .. py:property:: anderson_length :type: int Number of past iterates to consider with Anderson acceleration. .. py:property:: atol :type: float The desired absolute tolerance used to control the integrator error .. py:property:: max_nl_iters :type: int Maximum number of nonlinear iterations before we try a smaller step size .. py:property:: max_num_steps :type: int The maximum number of steps the solver can take before throwing a too much work error. .. py:property:: min_step_size :type: float Minimum acceptable step size before we error out. Defaults to 1ns .. py:property:: rtol :type: float The desired relative tolerance used to control the integrator error .. py:property:: use_jacobian :type: bool set to true to have the integrator use Jacobians (experimental) .. py:function:: strToIntegratorType(arg0: str) -> IntegratorType Convert string to IntegratorType enum. :param str: The name of the integrator type. :returns: The IntegratorType associated with the string.