rkstiff.if34

Adaptive-Step Fourth Order (Third Order Embedding) Integrating Factor Integrator

Adaptive Integrating Factor 4(3) solver.

Implements the IF(3,4) exponential Runge–Kutta scheme with an embedded third-order method for local error estimation and adaptive step control. It solves stiff semi-linear systems of the form

\[\frac{\partial \mathbf{U}}{\partial t} = \mathcal{L}\mathbf{U} + \mathcal{N}(\mathbf{U}),\]

where \(\mathcal{L}\) is the linear (stiff) operator and \(\mathcal{N}\) the nonlinear term.

The IF(3,4) method integrates this system in the exponential form

\[\mathbf{U}_{n+1} = e^{h\mathcal{L}}\mathbf{U}_n + h \sum_{i=1}^{s} b_i \, e^{(1-c_i)h\mathcal{L}} \, \mathcal{N}(\mathbf{U}_i),\]

where the intermediate stages \(\mathbf{U}_i\) are computed using exponential operators and the nonlinear evaluations.

The embedded third-order estimate is used to compute adaptive step sizes according to local error tolerances.

References

P. Whalen, M. Brio, and J. V. Moloney, Exponential time-differencing with embedded Runge-Kutta adaptive step control, J. Comput. Phys. 280, 579-601 (2015).

Classes

`IF34`(lin_op, nl_func[, config, diagonalize, ...])	Adaptive Integrating-Factor 4(3) solver.
`_If34Diagonal`(lin_op, nl_func[, logger])	IF(3,4) diagonal strategy.
`_If34Diagonalized`(lin_op, nl_func[, logger])	IF(3,4) strategy for diagonalizable linear systems.
`_If34NonDiagonal`(lin_op, nl_func)	IF(3,4) strategy for full (non-diagonalizable) linear operators.

class rkstiff.if34.IF34(lin_op, nl_func, config=SolverConfig(), diagonalize=False, loglevel='WARNING')[source]

Bases: BaseSolverAS

Adaptive Integrating-Factor 4(3) solver.

Fourth-order integrating factor Runge–Kutta scheme with an embedded third-order pair for local error control.

Parameters:

lin_op (np.ndarray) – Linear operator \(\mathcal{L}\).
nl_func (Callable[[np.ndarray], np.ndarray]) – Nonlinear function \(\mathcal{N}(\mathbf{U})\).
config (SolverConfig, optional) – Adaptive step configuration.
diagonalize (bool, default=False) – Attempt eigenvalue diagonalization if linear operator is 2D.
loglevel (str or int, default='WARNING') – Logging verbosity.

Notes

Implements FSAL (First Same As Last) reuse for efficiency.
Coefficients are recomputed only when step size changes.
Supports diagonal, diagonalizable, and full-matrix systems.

__init__(lin_op, nl_func, config=SolverConfig(), diagonalize=False, loglevel='WARNING')[source]

Initialize the IF(3,4) adaptive solver.

MAX_LOOPS = 50: Maximum retry attempts per adaptive step

MAX_S = 4.0: Maximum allowed step size increase factor

MIN_S = 0.25: Minimum allowed step size reduction factor

exception MaxLoopsExceeded

Bases: SolverError

Raised when too many attempts are made to find a valid adaptive step.

exception MinimumStepReached

Bases: SolverError

Raised when the adaptive step size falls below the minimum allowed value.

exception SolverError

Bases: RuntimeError

Base exception for solver-related runtime errors.

evolve(u, t0, tf, h_init=None, store_data=True, store_freq=1)

Integrate the system from \(t_0\) to \(t_f\) using adaptive time steps.

Repeatedly applies step() to propagate the solution forward while dynamically adjusting the time step size based on local error estimates.

Parameters:

u (np.ndarray) – Initial solution vector at \(t_0\).
t0 (float) – Initial time.
tf (float) – Final time.
h_init (float, optional) – Initial step size. Defaults to (tf - t0) / 100 if not provided.
store_data (bool, default=True) – Whether to store intermediate results in t and u.
store_freq (int, default=1) – Frequency of data storage; store every store_freq accepted steps.

Returns:

Final solution at \(t = t_f\).

Return type:

np.ndarray

Notes

The evolution proceeds until \(t \geq t_f\), automatically adjusting step sizes as needed.
Stored data is accessible via t and u.

Example

>>> solver = ETD35(lin_op, nl_func)
>>> u_final = solver.evolve(u0, t0=0.0, tf=10.0)
>>> solver.t[-1], np.linalg.norm(solver.u[-1])
(10.0, 0.0134)

reset()

Reset solver and clear adaptive-step state.

Return type:: None

set_loglevel(loglevel)

Adjust the solver’s logging verbosity at runtime.

Parameters:: loglevel (str or int) – New logging level. Accepts standard string levels or numeric constants from logging.
Return type:: None

Examples

>>> solver.set_loglevel("INFO")
>>> solver.set_loglevel(logging.DEBUG)

property solver_type: SolverType

Return the solver type for adaptive-step solvers.

Returns:: Always returns SolverType.ADAPTIVE_STEP.
Return type:: SolverType

Examples

>>> from rkstiff.etd35 import ETD35
>>> solver = ETD35(lin_op, nl_func)
>>> solver.solver_type == SolverType.ADAPTIVE_STEP
True

step(u, h_suggest)

Perform one adaptive integration step.

Attempts to advance the solution by time h_suggest and adjusts the step size automatically based on local error estimates.

Parameters:

u (np.ndarray) – Current state vector.
h_suggest (float) – Suggested time step size.

Return type:

Tuple[ndarray, float, float]

Returns:

unew (np.ndarray) – Updated solution vector after one accepted step.
h (float) – Actual step size used.
h_suggest (float) – Suggested step size for the next iteration.

Raises:

MaxLoopsExceeded – If too many attempts are made to find an acceptable step size.
MinimumStepReached – If the step size drops below the configured minimum minh.

Notes

The algorithm follows this pattern:

Try the proposed step.
Estimate local error and compute scaling factor s.
If s < 1 → reject step and reduce h.
If s ≥ 1 → accept step and update h_suggest for next step.

Warning

Very small or divergent s values may indicate instability or excessively tight tolerances.