rxnfit.solver_backend module

Central ODE driver: SciPy solve_ivp with optional numbalsoda for LSODA.

Implements the integration policy described in docs/spec_docs/numbalsoda2.md.

Notes

  • Numbalsoda is considered only for method="LSODA", non-time-dependent rate laws, and a non-empty t_eval grid.

  • Import failures, unsupported RHS, or integrator errors trigger a one-time UserWarning (per reason) and fall back to RK45 via scipy.integrate.solve_ivp().

  • If time_dependent is true, LSODA requests are coerced to RK45 without calling numbalsoda.

class rxnfit.solver_backend.LsodaImplicitTEvalMode(*values)

Bases: Enum

Implicit t_eval construction mode for LSODA (names are part of the API).

Each member selects the grid recipe documented in numbalsoda2.md section 5.5.

COMPUTE_RSS = 2
EVAL_ODE_FIT = 4
INTEGRATE_DATASETS = 3
SOLVE_SYSTEM = 1
rxnfit.solver_backend.build_t_eval_when_none_for_lsoda(mode: LsodaImplicitTEvalMode, *, t_span=None, t_start=None, t_exp_col=None, t_exp=None, t_points=None) → ndarray

Build a sorted unique float64 time grid for LSODA when t_eval is omitted.

Parameters:

  • mode – Which recipe to apply (SOLVE_SYSTEM, COMPUTE_RSS, etc.).

  • t_span – Required for SOLVE_SYSTEM and INTEGRATE_DATASETS as (t0, t1).

  • t_start – Dataset start time for INTEGRATE_DATASETS.

  • t_exp_col – Experimental times for COMPUTE_RSS.

  • t_exp – Concatenated experimental times for INTEGRATE_DATASETS.

  • t_points – Observation times for EVAL_ODE_FIT.

Returns:

One-dimensional float64 array in non-decreasing order with duplicates removed.

Raises:

ValueError – If required keyword arguments for mode are missing or invalid.

rxnfit.solver_backend.solve_ode(system_rhs, t_span, y0, t_eval=None, method='RK45', rtol=1e-06, atol=None, time_dependent=False)

Integrate dy/dt = system_rhs(t, y) via SciPy or numbalsoda.

Non-LSODA methods delegate to scipy.integrate.solve_ivp(). For method="LSODA", see docs/spec_docs/numbalsoda2.md: effective t_span follows t_eval when rates are not time-dependent; callers must supply t_eval or build it with build_t_eval_when_none_for_lsoda().

Parameters:

  • system_rhs – Callable (t, y) returning dy/dt (SciPy convention).

  • t_span – Interval (t0, t1). For LSODA with t_eval supplied, the solver uses the min/max of t_eval internally (spec section 5.2).

  • y0 – Initial state vector.

  • t_eval – Times where the solution is sampled. Required for LSODA (non-empty unless falling back to RK45 for an empty grid).

  • method – solve_ivp method name, or "LSODA" to try numbalsoda.

  • rtol – Relative integration tolerance.

  • atol – Absolute tolerance; None selects library defaults.

  • time_dependent – If True, LSODA is coerced to RK45 (internal callers set this from the kinetic model).

Returns:

Object compatible with scipy.integrate.OdeResult (t, y, success, message, …).

Note

Direct callers must set time_dependent=True only when rates depend on time (callable dict branch or has_time_dependent_rates); otherwise behavior is undefined (see numbalsoda2.md section 14).