rkstiff.solver

Base solver infrastructure for all rkstiff PDE solvers

Base solver infrastructure for exponential time-differencing (ETD) and related stiff integrators.

This module defines the BaseSolver abstract base class, which provides common initialization, logging, and validation logic for all solver subclasses (e.g., rkstiff.etd4.ETD4, rkstiff.etd5.ETD5).

It standardizes handling of the linear operator \(\mathcal{L}\), the nonlinear function \(\mathcal{N}(\mathbf{U})\), and logging verbosity across all stiff PDE solvers.

Classes

BaseSolver(lin_op, nl_func[, loglevel])

Abstract base class for all stiff solvers.

class rkstiff.solver.BaseSolver(lin_op, nl_func, loglevel='WARNING')[source]

Bases: ABC

Abstract base class for all stiff solvers.

Provides shared functionality for initializing linear and nonlinear components, configuring logging, and managing solution state.

Subclasses (such as ETD4 or ETD5) implement specific numerical time-stepping schemes by defining the abstract methods reset() and _reset().

Parameters:

lin_op (np.ndarray) –
Linear operator \(\mathcal{L}\) defining the stiff part of the system. Can be either:
- 1D array — representing a diagonal operator
- 2D square array — representing a full linear operator matrix
nl_func (Callable[[np.ndarray], np.ndarray]) – Nonlinear function \(\mathcal{N}(\mathbf{U})\) returning the nonlinear contribution for a given solution vector.
loglevel (str or int, optional) – Logging level. Accepts either a string ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL') or the corresponding integer constant from logging. Default is 'WARNING'.

lin_op

Linear operator associated with the stiff system.

Type:: np.ndarray

nl_func

Nonlinear function \(\mathcal{N}(\mathbf{U})\).

Type:: Callable[[np.ndarray], np.ndarray]

logger

Logger instance configured for the solver.

Type:: logging.Logger

t

Time points generated during the last call to evolve().

Type:: list of float

u

Solution vectors corresponding to time points in t.

Type:: list of np.ndarray

_diag

Indicates whether the linear operator is diagonal (True) or full matrix (False).

Type:: bool

Raises:: ValueError – If lin_op is not 1D or a 2D square matrix.

Notes

This base class is not meant to be instantiated directly. Derived solvers should inherit from BaseSolver and implement both reset() and _reset() to define problem-specific initialization and internal state clearing.

Tip

The base class automatically detects whether lin_op is diagonal, allowing subclasses to optimize accordingly.

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

Initialize a base solver instance.

Sets up internal attributes, validates the shape of the linear operator, and configures logging behavior.

Parameters:

lin_op (np.ndarray) – Linear operator. Must be 1D (diagonal) or a 2D square matrix.
nl_func (Callable[[np.ndarray], np.ndarray]) – Nonlinear function mapping the solution vector to its nonlinear component.
loglevel (str or int, optional) – Logging verbosity level. Default is 'WARNING'.

Raises:

ValueError – If lin_op is not 1D or not a square 2D matrix.

abstract property solver_type: SolverType

Return the type of this solver.

Returns:: Either CONSTANT_STEP or ADAPTIVE_STEP.
Return type:: SolverType

Notes

This is an abstract property that must be overridden in subclasses BaseSolverCS and BaseSolverAS.

Examples

>>> from rkstiff.if4 import IF4
>>> solver = IF4(lin_op, nl_func)
>>> solver.solver_type
<SolverType.CONSTANT_STEP: 1>

set_loglevel(loglevel)[source]

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)

abstractmethod reset()[source]

Reset the solver to its initial state.

Clears stored time and solution arrays, restoring the solver to its post-initialization condition. Typically invoked before restarting a simulation or integrating a new problem.

Return type:: None

Notes

Subclasses should call super().reset() if extending this method, and implement _reset() to clear any solver-specific caches.