rkstiff.if4

Constant-Step Fourth-Order Integrating Factor Integrator

Implements a fourth-order Integrating Factor (IF4) solver for stiff partial differential equations (PDEs) of the form:

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

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

After spatial discretization (e.g., using finite differences, Fourier spectral methods, or finite elements), this PDE system reduces to a stiff system of ordinary differential equations in time, which the IF4 scheme integrates efficiently.

This module provides two internal solver strategies:

  • _IF4Diagonal — optimized for diagonal (spectral) operators.

  • _IF4NonDiagonal — general matrix-based implementation.

The public class IF4 wraps both strategies and provides a consistent constant-step interface for time evolution.

Classes

IF4(lin_op, nl_func[, loglevel])

Fourth-order Integrating Factor (IF4) constant-step solver for PDEs.

_IF4Diagonal(lin_op, nl_func)

Internal strategy for IF4 with diagonal spatial operator.

_IF4NonDiagonal(lin_op, nl_func)

Internal strategy for IF4 with non-diagonal spatial operator.
class rkstiff.if4.IF4(lin_op, nl_func, loglevel='WARNING')[source]

Bases: BaseSolverCS

Fourth-order Integrating Factor (IF4) constant-step solver for PDEs.

Advances semi-discretized PDE systems of the form:

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

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

Parameters:

  • lin_op (np.ndarray) – Linear operator \(\mathcal{L}\) (matrix or diagonal array).

  • nl_func (Callable[[np.ndarray], np.ndarray]) – Nonlinear function \(\mathcal{N}(\mathbf{U})\).

  • loglevel (str or int, optional) – Logging verbosity level (default "WARNING").

Notes

The IF4 method applies the classical fourth-order Runge–Kutta scheme in the exponential integrating factor framework:

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

where \((b_i, c_i)\) are the coefficients of the RK4 tableau.

__init__(lin_op, nl_func, loglevel='WARNING')[source]

Initialize the IF4 solver and select diagonal or matrix strategy.

evolve(u, t0, tf, h, store_data=True, store_freq=1)

Integrate the system from \(t_0\) to \(t_f\) using fixed step size.

Repeatedly applies step() with constant \(h\) until the final time is reached.

Parameters:

  • u (np.ndarray) – Initial solution vector at \(t_0\).

  • t0 (float) – Initial time.

  • tf (float) – Final time (integration stops when t ≥ tf).

  • h (float) – Constant step size \(\Delta t\).

  • store_data (bool, default=True) – Whether to store intermediate results in t and u.

  • store_freq (int, default=1) – Frequency of storing data; every store_freq steps.

Returns:

Final solution vector at \(t_f\).

Return type:

np.ndarray

Raises:

ValueError – If h exceeds the total time span tf - t0.

Notes

  • The time grid is uniformly spaced with spacing \(h\).

  • Stored data can be accessed through t and u.

Example

>>> solver = ETD4(lin_op, nl_func)
>>> u_final = solver.evolve(u0, t0=0.0, tf=10.0, h=0.05)
>>> len(solver.t)
200
reset()

Reset solver state and clear stored time/solution data.

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 constant-step solvers.

Returns:

Always returns SolverType.CONSTANT_STEP.

Return type:

SolverType

Examples

>>> from rkstiff.if4 import IF4
>>> solver = IF4(lin_op, nl_func)
>>> solver.solver_type == SolverType.CONSTANT_STEP
True
step(u, h)

Perform a single constant-step propagation.

Parameters:

  • u (np.ndarray) – Current solution vector.

  • h (float) – Constant step size (must be non-negative).

Returns:

Updated solution after one full time step.

Return type:

np.ndarray

Notes

This method simply wraps _update_stages() and performs minimal validation and logging.