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 Attributes ---------- .. autoapisummary:: Karana.Integrators.ArkExplicitIntegratorOptions Karana.Integrators.ArkImplicitIntegratorOptions Karana.Integrators.CVodeIntegratorOptions Classes ------- .. autoapisummary:: Karana.Integrators.ArkExplicitIntegrator Karana.Integrators.ArkExplicitIntegratorVars Karana.Integrators.ArkImplicitIntegrator Karana.Integrators.ArkImplicitIntegratorVars Karana.Integrators.CVodeIntegrator Karana.Integrators.CVodeIntegratorVars Karana.Integrators.EulerIntegrator Karana.Integrators.Integrator Karana.Integrators.IntegratorOptions Karana.Integrators.IntegratorType Karana.Integrators.RK4Integrator Karana.Integrators.SundialsImplicitIntegrator Karana.Integrators.SundialsImplicitIntegratorOptions Karana.Integrators.SundialsImplicitIntegratorVars Karana.Integrators.SundialsIntegrator Karana.Integrators.SundialsIntegratorOptions Karana.Integrators.SundialsIntegratorVars Functions --------- .. autoapisummary:: Karana.Integrators.createIntegrator 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:method:: getAdaptiveStepping() -> bool Check whether this integrator is using adaptive step sizes. :returns: A boolean corresponding to the adaptive status. .. 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:method:: getVars() -> ArkExplicitIntegratorVars .. py:method:: 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. :param use_adaptive_steps: Whether to use adaptive steps (the default) or lock the step size. .. py:method:: setFixedStepSize(fixed_step_size: SupportsFloat | SupportsIndex) -> None Set a fixed step size in fixed-step mode; must also disable adaptive steps via setAdaptiveStepping(). :param fixed_step_size: Target step size to take; a smaller step may be taken only to hit the target time. .. py:data:: ArkExplicitIntegratorOptions .. py:class:: ArkExplicitIntegratorVars Bases: :py:obj:`SundialsIntegratorVars` The Vars for the ArkExplicitIntegrator class. .. py:class:: ArkImplicitIntegrator Bases: :py:obj:`SundialsImplicitIntegrator` The (implicit) Adaptive Runge-Kutta 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:method:: getVars() -> ArkImplicitIntegratorVars .. py:data:: ArkImplicitIntegratorOptions .. py:class:: ArkImplicitIntegratorVars Bases: :py:obj:`SundialsImplicitIntegratorVars` The Vars for the ArkImplicitIntegrator class. .. py:class:: CVodeIntegrator Bases: :py:obj:`SundialsImplicitIntegrator` 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:method:: getVars() -> CVodeIntegratorVars .. py:data:: CVodeIntegratorOptions .. py:class:: CVodeIntegratorVars Bases: :py:obj:`SundialsImplicitIntegratorVars` The Vars for the CVodeIntegrator class. .. py:property:: last_order :type: Karana.Core.VarInt Integration method order used during last step .. 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:: 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]]], bool] 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: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:: ARKIMPLICIT :type: ClassVar[IntegratorType] .. py:attribute:: ARKIMPLICIT_DIRK23 :type: ClassVar[IntegratorType] .. py:attribute:: ARKIMPLICIT_ESDIRK45 :type: ClassVar[IntegratorType] .. py:attribute:: ARKIMPLICIT_SDIRK12 :type: ClassVar[IntegratorType] .. py:attribute:: ARKIMPLICIT_SDIRK34 :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:: SundialsImplicitIntegrator Bases: :py:obj:`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. .. py:method:: getOptions() -> SundialsImplicitIntegratorOptions Get the options associated with the integrator. :returns: The options associated with the integrator. .. py:method:: 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. :param damping: Damping factor; pass a value of 1 for no damping. .. py:method:: setAndersonLength(length: SupportsInt | SupportsIndex) -> None Set the subspace size to use for Anderson acceleration. :param length: Damping factor; pass a value of 0 for no damping. .. py:method:: setMaxNLIters(iters: SupportsInt | SupportsIndex) -> None Set the maximum nonlinear iterations. :param iters: Max iters to take before trying a smaller timestep. .. py:class:: SundialsImplicitIntegratorOptions Bases: :py:obj:`SundialsIntegratorOptions` 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:: max_nl_iters :type: int Maximum number of nonlinear iterations before we try a smaller step size .. py:property:: use_jacobian :type: bool set to true to have the integrator use Jacobians (experimental) .. py:class:: SundialsImplicitIntegratorVars Bases: :py:obj:`SundialsIntegratorVars` The Vars for the SundialsImplicitIntegrator class. .. py:property:: num_jac_evals :type: Karana.Core.VarLong Number of calls made to the CVLS Jacobian approximation function .. py:property:: num_lin_iters :type: Karana.Core.VarLong Number of linear iterations .. py:property:: num_lin_rhs_evals :type: Karana.Core.VarLong Number of RHS/derivative calls used to estimate jacobians .. py:property:: num_nonlin_iters :type: Karana.Core.VarLong Number of nonlinear iterations .. py:property:: num_step_solve_fails :type: Karana.Core.VarLong Number of rejected timesteps due to nonlinear solve failure .. 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:: getOptions() -> SundialsIntegratorOptions Get the options associated with the integrator. :returns: The options associated with the integrator. .. py:method:: 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:method:: 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. :param atol_vec: The optional vector atol to use; must have same length as state vector or be null. .. py:class:: SundialsIntegratorOptions Bases: :py:obj:`IntegratorOptions` Struct with options for this integrator .. py:property:: atol :type: float The desired absolute tolerance used to control the integrator error .. py:property:: atol_vec :type: 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. .. 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:class:: SundialsIntegratorVars The Vars for the SundialsIntegrator class. .. py:property:: curr_step :type: Karana.Core.VarDouble Current step size to try on next advance call .. py:property:: last_step :type: Karana.Core.VarDouble Last successful step size .. py:property:: num_err_test_fails :type: Karana.Core.VarLong Cumulative number of error test failures due to too large of step size .. py:property:: num_rhs_evals :type: Karana.Core.VarLong Cumulative number of RHS calls taken by the solver .. py:property:: num_steps :type: Karana.Core.VarLong Cumulative number of internal steps taken by the solver .. py:function:: createIntegrator(integrator_type: IntegratorType, nstates: SupportsInt | SupportsIndex, deriv_fn: collections.abc.Callable, options: IntegratorOptions = None) -> Integrator 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 :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: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.