API Reference

Public API

differentialequations — SciPy-backed differential equation solvers.

All public symbols are re-exported from differentialequations.core so callers can simply write:

from differentialequations import ivpag, bvpfd, OdeResult

This package is a self-contained set of ODE/BVP/DAE utilities inspired by the IMSL Fortran Numerical Library Differential Equations chapter, backed by scipy.integrate.

class differentialequations.OdeResult(t, y, success=True, message='', n_steps=0, n_eval=0)

Bases: object

Result of an ODE/BVP/DAE solve procedure.

Parameters:

  • t (ndarray)

  • y (ndarray)

  • success (bool)

  • message (str)

  • n_steps (int)

  • n_eval (int)

t

Time (or independent variable) points.

Type:

np.ndarray

y

Solution array of shape (n_eqs, len(t)).

Type:

np.ndarray

success

Whether the solve succeeded.

Type:

bool

message

Description of termination condition.

Type:

str

n_steps

Number of steps taken by the solver.

Type:

int

n_eval

Number of function evaluations.

Type:

int

differentialequations.ivpag(f, t_span, y0, method='RK45', rtol=1e-06, atol=1e-09)

Solve an initial value problem for a system of ODEs (IMSL IVPAG).

General-purpose IVP solver delegating to scipy.integrate.solve_ivp with a user-selectable method. Mirrors the IMSL IVPAG routine.

Parameters:

  • f (Callable) – Right-hand side of the ODE system. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector of shape (n,).

  • method (str) – Integration method name accepted by solve_ivp (e.g. 'RK45', 'BDF', 'Radau', 'LSODA', 'DOP853'). Defaults to 'RK45'.

  • rtol (float) – Relative tolerance. Defaults to 1e-6.

  • atol (float) – Absolute tolerance. Defaults to 1e-9.

Returns:

Solution object with t, y, success, and diagnostic counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid (t0 >= tf).

differentialequations.ivprk(f, t_span, y0, rtol=1e-06, atol=1e-09)

Solve an IVP using the Runge-Kutta RK4/5 method (IMSL IVPRK).

Delegates to scipy.integrate.solve_ivp with method='RK45'. Suitable for non-stiff systems.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • rtol (float) – Relative tolerance. Defaults to 1e-6.

  • atol (float) – Absolute tolerance. Defaults to 1e-9.

Returns:

Solution with t, y, success, and counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid.

differentialequations.ivpbs(f, t_span, y0, rtol=1e-06, atol=1e-09)

Solve an IVP using the Bulirsch-Stoer DOP853 method (IMSL IVPBS).

Delegates to scipy.integrate.solve_ivp with method='DOP853'. Higher-order method, suitable for smooth non-stiff problems requiring high accuracy.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • rtol (float) – Relative tolerance. Defaults to 1e-6.

  • atol (float) – Absolute tolerance. Defaults to 1e-9.

Returns:

Solution with t, y, success, and counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid.

differentialequations.ivpam(f, t_span, y0, rtol=1e-06, atol=1e-09)

Solve an IVP using an Adams method via LSODA (IMSL IVPAM).

Delegates to scipy.integrate.solve_ivp with method='LSODA'. Adams predictor-corrector, automatically switches to BDF for stiff regions.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • rtol (float) – Relative tolerance. Defaults to 1e-6.

  • atol (float) – Absolute tolerance. Defaults to 1e-9.

Returns:

Solution with t, y, success, and counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid.

differentialequations.ivpgb(f, t_span, y0, rtol=1e-06, atol=1e-09)

Solve an IVP using Gear’s backward differentiation formula (IMSL IVPGB).

Delegates to scipy.integrate.solve_ivp with method='BDF'. Suitable for stiff problems.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • rtol (float) – Relative tolerance. Defaults to 1e-6.

  • atol (float) – Absolute tolerance. Defaults to 1e-9.

Returns:

Solution with t, y, success, and counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid.

differentialequations.ode45(f, t_span, y0, rtol=1e-06, atol=1e-09)

Solve an IVP with explicit Runge-Kutta RK45 (MATLAB-style ode45 alias).

Explicit alias for ivprk(). Delegates to scipy.integrate.solve_ivp with method='RK45'.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • rtol (float) – Relative tolerance. Defaults to 1e-6.

  • atol (float) – Absolute tolerance. Defaults to 1e-9.

Returns:

Solution with t, y, success, and counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid.

differentialequations.ode_stiff(f, t_span, y0, rtol=1e-06, atol=1e-09)

Solve a stiff IVP using the Radau implicit Runge-Kutta method.

Delegates to scipy.integrate.solve_ivp with method='Radau'. The Radau IIA method is L-stable and well-suited for very stiff problems.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • rtol (float) – Relative tolerance. Defaults to 1e-6.

  • atol (float) – Absolute tolerance. Defaults to 1e-9.

Returns:

Solution with t, y, success, and counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid.

differentialequations.bvpfd(f, bc, x, y_guess, tol=0.001)

Solve a two-point boundary value problem by finite differences (IMSL BVPFD).

Delegates to scipy.integrate.solve_bvp. The ODE function signature uses f(x, y) (not f(t, y)) following the BVP convention.

Parameters:

  • f (Callable) – ODE system. Signature f(x, y) -> array where x is scalar and y is (n,) vector. For solve_bvp, x may be a (N,) array for vectorised evaluation.

  • bc (Callable) – Boundary condition residuals. Signature bc(ya, yb) -> array of shape (n,).

  • x (np.ndarray) – Initial mesh of shape (N,) spanning [a, b].

  • y_guess (np.ndarray) – Initial guess of shape (n, N).

  • tol (float) – Tolerance for the BVP solver. Defaults to 1e-3.

Returns:

Solution with t (mesh x), y (solution on mesh), and status.

Return type:

OdeResult

Raises:

  • TypeError – If f or bc is not callable.

  • ValueError – If x mesh is not increasing.

differentialequations.bvpms(f, bc, x, y_guess, tol=0.001)

Solve a scalar two-point BVP by single shooting (IMSL BVPMS).

Implements a shooting method for scalar second-order BVPs reduced to a first-order system [y, y']. Uses ivprk() for IVP integration and scipy.optimize.brentq (or fallback to fsolve) to find the initial slope that satisfies the right-hand boundary condition.

Limitations: only works for systems where the boundary condition can be expressed as finding a single unknown initial value (scalar shooting).

Parameters:

  • f (Callable) – ODE right-hand side. Signature f(x, y) -> array.

  • bc (Callable) – Boundary residuals. Signature bc(ya, yb) -> array.

  • x (np.ndarray) – Mesh of shape (N,). Only the endpoints x[0] and x[-1] are used for the IVP integration.

  • y_guess (np.ndarray) – Initial guess array of shape (n, N). The value at x[0] (y_guess[:, 0]) is used as the fixed left boundary values. The first component of y_guess[:, -1] is used to bracket the shooting parameter.

  • tol (float) – Tolerance passed to the root-finder. Defaults to 1e-3.

Returns:

Solution with t (mesh x), y, and diagnostic info.

Return type:

OdeResult

Raises:

  • TypeError – If f or bc is not callable.

  • ValueError – If x has fewer than 2 points.

differentialequations.daspg(f, t_span, y0, yprime0, rtol=1e-06, atol=1e-09)

Solve a DAE system using a stiff IVP approximation (IMSL DASPG).

Approximates a differential-algebraic equation (DAE) of the form M(t) * y' = f(t, y) by treating it as a stiff IVP and delegating to ode_stiff() (Radau). The yprime0 parameter is accepted for API compatibility but the initial derivative is computed from the ODE.

Parameters:

  • f (Callable) – DAE/ODE right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • yprime0 (list | np.ndarray) – Initial time derivative (used as hint for consistent initialisation; currently informational).

  • rtol (float) – Relative tolerance. Defaults to 1e-6.

  • atol (float) – Absolute tolerance. Defaults to 1e-9.

Returns:

Solution with t, y, success, and counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid.

differentialequations.ivp_with_events(f, t_span, y0, events, method='RK45')

Solve an IVP with event detection (zero-crossing detection).

Delegates to scipy.integrate.solve_ivp with the events argument. Each event function e(t, y) triggers when it crosses zero.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • events (list[Callable]) – List of event functions. Each has signature event(t, y) -> float. Set event.terminal = True to stop integration at that event.

  • method (str) – Integration method. Defaults to 'RK45'.

Returns:

Solution with t, y, success, and counters.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable or events is not a list.

  • ValueError – If t_span is invalid.

differentialequations.ivp_dense(f, t_span, y0, t_eval, method='RK45')

Solve an IVP with dense (user-specified) output points.

Delegates to scipy.integrate.solve_ivp with t_eval to obtain solution values at exactly the requested time points.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf).

  • y0 (list | np.ndarray) – Initial state vector.

  • t_eval (np.ndarray) – Array of times at which to store the solution, must lie within t_span.

  • method (str) – Integration method. Defaults to 'RK45'.

Returns:

Solution evaluated at t_eval points.

Return type:

OdeResult

Raises:

  • TypeError – If f is not callable.

  • ValueError – If t_span is invalid or t_eval is empty.

differentialequations.phase_portrait(f, t_span, y0_list, t_eval=None)

Solve multiple IVPs to generate phase portrait trajectories.

Iterates over a list of initial conditions and solves each IVP with ivprk(), collecting all trajectories.

Parameters:

  • f (Callable) – Right-hand side. Signature f(t, y) -> array.

  • t_span (tuple) – Integration interval (t0, tf) applied to all ICs.

  • y0_list (list[list | np.ndarray]) – List of initial condition vectors.

  • t_eval (np.ndarray | None) – Optional evaluation points. Defaults to None (adaptive).

Returns:

List of OdeResult objects, one per initial condition.

Return type:

list[OdeResult]

Raises:

  • TypeError – If f is not callable or y0_list is not a list.

  • ValueError – If t_span is invalid or y0_list is empty.

differentialequations.stability_check(f, y_eq, t=0.0)

Compute eigenvalues of the numerical Jacobian at an equilibrium point.

Evaluates the Jacobian of f at the equilibrium y_eq using forward finite differences, then computes its eigenvalues. A negative real part indicates stability.

Parameters:

  • f (Callable) – ODE right-hand side. Signature f(t, y) -> array.

  • y_eq (list | np.ndarray) – Equilibrium point y* where f(t, y*) ≈ 0.

  • t (float) – Time at which to evaluate the Jacobian. Defaults to 0.0.

Returns:

Complex eigenvalues of the Jacobian at y_eq.

Return type:

np.ndarray

Raises:

  • TypeError – If f is not callable.

  • ValueError – If y_eq is empty or f does not return an array.

differentialequations.ivp_jacobian(f, t, y)

Compute a numerical Jacobian of f at (t, y) using forward differences.

Uses forward finite differences with step size proportional to machine epsilon to approximate the Jacobian matrix J[i,j] = df_i/dy_j.

Parameters:

  • f (Callable) – ODE right-hand side. Signature f(t, y) -> array.

  • t (float) – Time at which to evaluate the Jacobian.

  • y (list | np.ndarray) – State vector at which to evaluate the Jacobian.

Returns:

Jacobian matrix of shape (n, n) where n = len(y).

Return type:

np.ndarray

Raises:

  • TypeError – If f is not callable.

  • ValueError – If y is empty.

differentialequations.launch_documentation(opener=<function open>, package_dir=None)

Launch package documentation in a web browser.

The launcher opens local HTML documentation only.

Parameters:

  • opener (Callable[[str], bool]) – Browser opener function. Defaults to webbrowser.open.

  • package_dir (Path | None) – Optional package directory override used for tests. Defaults to the directory of this module.

Returns:

The file://... URI opened.

Return type:

str

Raises:

FileNotFoundError – If no local documentation index can be located.