otf.time_integration

Public solver implementations and convenience exports for time integration.

This package exposes a small set of concrete time-integration algorithms used by otf including single-step, multistep, multistage methods and a scipy.integrate.solve_ivp adapter. Import the classes below for common integration workflows.

Modules:

Name	Description
`base`	Abstract base classes to simulate `System`s forward in time.
`linear_nonlinear`	Linear–nonlinear time-integration schemes.
`solver`	Explicit and wrapped ODE solvers for time integration.

Classes:

Name	Description
`AB2AM2`	Adams–Bashforth 2 predictor with Adams–Moulton 2 corrector (AB2-AM2).
`AB2BD2`	Adams–Bashforth 2 predictor combined with a BDF/Backward-Differentiation
`ETD1`	First-order exponential time-differencing (ETD1) single-step solver.
`ETD2`	Second-order exponential time-differencing multistep solver (ETD2).
`ForwardEuler`	Forward Euler solver.
`FourStepAdamsBashforth`	Four-step Adams–Bashforth explicit multistep integrator.
`RK4`	4th-order Runge–Kutta solver.
`SolveIvp`	`scipy.integrate.solve_ivp` wrapper matching the solver interface.
`TwoStepAdamsBashforth`	Two-step explicit Adams–Bashforth multistep integrator.

AB2AM2

AB2AM2(
    system: BaseSystem,
    pre_multistep_solver: BaseSolver | None = None,
)

Bases: MultistepSolver

Adams–Bashforth 2 predictor with Adams–Moulton 2 corrector (AB2-AM2).

A two-step predictor/corrector hybrid that treats the linear part implicitly (AM2 corrector) and the nonlinear part explicitly (AB2 predictor).

Source code in src/otf/time_integration/base.py

def __init__(
    self, system: BaseSystem, pre_multistep_solver: BaseSolver | None = None
):
    """Initialize a multistep solver.

    Parameters
    ----------
    system
        The system to integrate.
    pre_multistep_solver
        An instantiated `BaseSolver` used to generate initial history steps
        until enough values are available to run the multistep method. If
        `None`, callers must supply the necessary initial history when
        invoking `solve`/`solve_true`.
    """
    super().__init__(system)

    self._step_true, self._step_assimilated = self._step_factory()

    self._pre_multistep_solver = pre_multistep_solver

AB2BD2

AB2BD2(
    system: BaseSystem,
    pre_multistep_solver: BaseSolver | None = None,
)

Bases: MultistepSolver

Adams–Bashforth 2 predictor combined with a BDF/Backward-Differentiation style second-order corrector (AB2-BD2).

A two-step hybrid that uses an explicit AB2 prediction and a stabilized second-order corrector for stiff linear components.

Source code in src/otf/time_integration/base.py

def __init__(
    self, system: BaseSystem, pre_multistep_solver: BaseSolver | None = None
):
    """Initialize a multistep solver.

    Parameters
    ----------
    system
        The system to integrate.
    pre_multistep_solver
        An instantiated `BaseSolver` used to generate initial history steps
        until enough values are available to run the multistep method. If
        `None`, callers must supply the necessary initial history when
        invoking `solve`/`solve_true`.
    """
    super().__init__(system)

    self._step_true, self._step_assimilated = self._step_factory()

    self._pre_multistep_solver = pre_multistep_solver

ETD1

ETD1(system: BaseSystem)

Bases: SinglestepSolver

First-order exponential time-differencing (ETD1) single-step solver.

Uses an analytic integration of the linear part and a first-order update for the nonlinear contribution. Suitable for problems where the linear operator can be diagonalized/represented elementwise.

Source code in src/otf/time_integration/base.py

def __init__(self, system: BaseSystem):
    """Create a single-step solver for `system`.

    Parameters
    ----------
    system
        The system to integrate. For `solve_true`, `system` should be a
        `System_ModelKnown` instance (checked by `solve_true`).
    """

    super().__init__(system)

    self._step_true, self._step_assimilated = self._step_factory()

ETD2

ETD2(
    system: BaseSystem,
    pre_multistep_solver: BaseSolver | None = None,
)

Bases: MultistepSolver

Second-order exponential time-differencing multistep solver (ETD2).

A two-step ETD method that combines exact linear evolution with a second-order treatment of nonlinear terms.

Source code in src/otf/time_integration/base.py

def __init__(
    self, system: BaseSystem, pre_multistep_solver: BaseSolver | None = None
):
    """Initialize a multistep solver.

    Parameters
    ----------
    system
        The system to integrate.
    pre_multistep_solver
        An instantiated `BaseSolver` used to generate initial history steps
        until enough values are available to run the multistep method. If
        `None`, callers must supply the necessary initial history when
        invoking `solve`/`solve_true`.
    """
    super().__init__(system)

    self._step_true, self._step_assimilated = self._step_factory()

    self._pre_multistep_solver = pre_multistep_solver

ForwardEuler

ForwardEuler(system: BaseSystem)

Bases: SinglestepSolver

Forward Euler solver.

See documentation of SinglestepSolver.

Source code in src/otf/time_integration/base.py

def __init__(self, system: BaseSystem):
    """Create a single-step solver for `system`.

    Parameters
    ----------
    system
        The system to integrate. For `solve_true`, `system` should be a
        `System_ModelKnown` instance (checked by `solve_true`).
    """

    super().__init__(system)

    self._step_true, self._step_assimilated = self._step_factory()

FourStepAdamsBashforth

FourStepAdamsBashforth(
    system: BaseSystem,
    pre_multistep_solver: BaseSolver | None = None,
)

Bases: MultistepSolver

Four-step Adams–Bashforth explicit multistep integrator.

Requires a pre_multistep_solver to generate the first three steps when beginning integration, or callers must supply the initial history of four states. pre_multistep_solver may be passed as None in which case the caller is responsible for providing the required initial history when invoking solve/solve_true.

Initialize the four-step Adams–Bashforth solver.

Parameters:

Name	Type	Description	Default
`system`	`BaseSystem`	The system to integrate.	required
`pre_multistep_solver`	`BaseSolver \| None`	Optional solver used to produce initial steps until four history values are available. If `None`, callers must provide the four initial states when starting integration.	`None`

Source code in src/otf/time_integration/solver.py

def __init__(
    self, system: BaseSystem, pre_multistep_solver: BaseSolver | None = None
):
    """Initialize the four-step Adams–Bashforth solver.

    Parameters
    ----------
    system
        The system to integrate.
    pre_multistep_solver
        Optional solver used to produce initial steps until four history
        values are available. If `None`, callers must provide the four
        initial states when starting integration.
    """

    super().__init__(system, pre_multistep_solver)

RK4

RK4(system: System_ModelKnown)

Bases: MultistageSolver

4th-order Runge–Kutta solver.

See documentation of base_solver.SinglestepSolver.

See https://en.wikipedia.org/wiki/Runge%E2%80%93Kutta_methods

Source code in src/otf/time_integration/base.py

def __init__(self, system: System_ModelKnown):
    """Create a multistage solver bound to `system`.

    Parameters
    ----------
    system
        A `System_ModelKnown` instance providing `f_true` and related model
        methods required by multistage integrators.
    """

    assert isinstance(system, System_ModelKnown), (
        "`system` must be of type `System_ModelKnown`"
    )

    super().__init__(system)

    self._step_true, self._step = self._step_factory()

SolveIvp

SolveIvp(system: BaseSystem, options: dict = dict())

Bases: MultistageSolver

scipy.integrate.solve_ivp wrapper matching the solver interface.

This adapter lets users employ SciPy's solve_ivp while keeping the same external solve/solve_true signatures used across other solvers in this package. Note that integration is performed in NumPy/SciPy (not JAX).

Initialize the SolveIvp adapter.

Parameters:

Name	Type	Description	Default
`system`	`BaseSystem`	An instance of `BaseSystem` to simulate forward in time.	required
`options`	`dict`	Optional keyword arguments that are passed directly to `scipy.integrate.solve_ivp`.	`dict()`

Notes

Integration is performed by SciPy (NumPy), not JAX. The options dictionary may be modified after initialization.

Source code in src/otf/time_integration/solver.py

def __init__(self, system: BaseSystem, options: dict = dict()):
    """Initialize the SolveIvp adapter.

    Parameters
    ----------
    system
        An instance of `BaseSystem` to simulate forward in time.
    options
        Optional keyword arguments that are passed directly to
        `scipy.integrate.solve_ivp`.

    Notes
    -----
    Integration is performed by SciPy (NumPy), not JAX. The `options`
    dictionary may be modified after initialization.
    """

    self._system = system
    self.options = options

TwoStepAdamsBashforth

TwoStepAdamsBashforth(
    system: BaseSystem,
    pre_multistep_solver: BaseSolver | None = None,
)

Bases: MultistepSolver

Two-step explicit Adams–Bashforth multistep integrator.

This class implements the classical two-step Adams–Bashforth method for explicit integration of the nonlinear terms. A pre_multistep_solver may be provided to generate initial steps when starting the integration. If pre_multistep_solver is None, callers must supply the required two initial history states when invoking solve/solve_true.

Initialize the two-step Adams–Bashforth solver.

Parameters:

Name	Type	Description	Default
`system`	`BaseSystem`	The system to integrate.	required
`pre_multistep_solver`	`BaseSolver \| None`	Optional solver used to produce initial steps until two history values are available. If `None`, callers must provide the two initial states when starting integration.	`None`

Source code in src/otf/time_integration/solver.py

def __init__(
    self, system: BaseSystem, pre_multistep_solver: BaseSolver | None = None
):
    """Initialize the two-step Adams–Bashforth solver.

    Parameters
    ----------
    system
        The system to integrate.
    pre_multistep_solver
        Optional solver used to produce initial steps until two history
        values are available. If `None`, callers must provide the two
        initial states when starting integration.
    """

    super().__init__(system, pre_multistep_solver)