Expand description
Numerical ordinary differential equation solvers with a compact Rust API.
The crate provides in-place first-order ODE problems, solver options,
callbacks (including vector event conditions and exact preset-time effects),
retained dense output, and
ordered ensemble execution. Concrete
algorithms are grouped by family below solvers; core problem, solution,
and driver types remain at the crate root.
§Quickstart
use differential_equations::solvers::explicit::Tsit5;
use differential_equations::{OdeProblem, SaveMode, SolveOptions, solve};
let problem = OdeProblem::new(
|derivative: &mut [f64], state: &[f64], rate: &f64, _time: f64| {
derivative[0] = rate * state[0];
},
[1.0],
(0.0, 1.0),
-2.0,
);
let options = SolveOptions::new()
.with_tolerances(1.0e-9, 1.0e-9)
.with_save(SaveMode::Endpoints);
let solution = solve(&problem, Tsit5, &options)?;
assert!(solution.last_state()[0] < 0.14);§API organization
OdeProblemdescribes a first-order initial-value problem and optional Jacobian or callback behavior.OdeProblem::with_preset_time_callbackschedules effects at exact integration times without duplicating them inSolveOptions::time_stops, whileCallbackSaveselects whether the callback’s left limit, affected state, both, or neither are retained.CallbackSetcomposes callback policies before attaching them to a first-order or split problem and provides initialization/finalization hooks around successful integration. Vector continuous callbacks group several root functions; they are separate from ndarray state shape.callbacks::DomainGuardrejects out-of-domain candidate states before callback effects or trajectory saving.callbacks::PositiveDomaincheaply restricts upcoming steps and clamps accepted states to preserve componentwise non-negativity.callbacks::ManifoldProjectionenforces implicit conservation laws with rectangular residuals and typed nonlinear failure.callbacks::GeneralDomaincouples that projection engine with predictive step control for a user-defined domain residual.CallbackAction::ContinueWithStepSizeoverrides the next proposed step; Rust interior-mutability types such asstd::cell::Celllet sequential callback effects update parameters without imposing mutable problem ownership on every solve.callbackscontains reusable integration-time policies. Its periodic and iterative schedulers use constant memory;callbacks::IterativeCallbackchooses each next event from the state after the previous effect.callbacks::TerminateSteadyStatestops when the problem’s derivatives satisfy independent componentwise tolerances. Its function-calling policy marks read-only observations explicitly, and its step-size limiter applies dynamic stability bounds without interfering with smaller adaptive steps.SolveOptionscontrols tolerances, step sizes, exact time stops, saved output, and dense output retention;solveruns anOdeAlgorithm.solvers::explicitis a good starting point for non-stiff problems,solvers::rosenbrockcontains linearly implicit stiff methods, andsolvers::automaticcontains in-flight non-stiff/stiff composites with configurable hysteresis and observable branch statistics.tableauexposes the extension surface for defining explicit Runge–Kutta and Runge–Kutta–Nyström methods from compile-time-validated JSON resources, plus typed data for specialized solver families.OdeProblem::buildernames the initial state, time span, parameters, and ndarray evaluation style.OdeProblem::from_arrayremains the compact constructor for scalar, vector, and matrix states while numerical kernels retain contiguous flat workspaces.OdeProblem::from_array_out_of_placeaccepts functions returning arrays;OdeFunctionunifies them with in-place closures and propagates errors.solvers::second_order::SecondOrderOdeProblemprovides matching ndarray constructors while keeping velocity and position partitions separate.solve_ensembleandsolve_batchpreserve input order. The defaultparallelfeature also enables their Rayon-backed variants.
§Features
The public Cargo feature surface is intentionally small:
parallelis enabled by default and adds Rayon-backed independent solves.serdeadds validated, versioned serialization of solutions and portable dense segments. It is independent of parallel execution.allocation-metricsenables repository benchmark instrumentation and is not needed by ordinary users.
Disabling default features selects sequential ensemble execution. State
shape is part of the core API, not a feature: ndarray scalar, vector, and
matrix adapters remain available with default-features = false. There are
no vector, matrix, or ndarray feature flags.
§Errors and panics
Public solve functions return SolveError for invalid dimensions,
non-finite inputs, unsupported option/algorithm combinations, and numerical
failure. Problem right-hand sides, Jacobians, and callbacks are user code;
a panic in one of them is not caught by the solver. In-place right-hand
sides and Jacobians must fill their complete output buffers, and callback
effects must preserve the problem’s state dimension.
§Further reading
The packaged repository documentation includes the solver-selection and scope guide in the README and the compile-time tableau resource guide. Contributors can use the performance regression guide to compare stable benchmark IDs locally.
Re-exports§
pub use gauss_jackson::GaussJackson8;pub use gauss_jackson::GaussJacksonConfig;pub use gauss_jackson::GaussJacksonError;pub use gauss_jackson::GaussJacksonStatistics;pub use gauss_jackson::GaussJacksonStep;pub use scoped_problem::ScopedOdeProblem;pub use scoped_problem::ScopedSecondOrderProblem;pub use ndarray;
Modules§
- callbacks
- Reusable callback policies built on
crate::CallbackSet. - gauss_
jackson - Fixed-step eighth-order Gauss–Jackson integration of
q'' = a(t, q, v). - scoped_
problem - Borrowed and thread-eligible problem storage for reusable solvers.
- solvers
- Numerical algorithms organized by solver family.
- state_
layout - Explicit matrix-to-state layout adapters.
- stepping
- Reusable, output-free numerical stepping with explicit commit/reject lifecycle.
- tableau
- Lazily parsed, resource-backed solver tableaus.
- tolerances
- Component and block error control for reusable solver attempts.
Structs§
- Callback
Set - An ordered collection of callbacks that can be attached to an ODE problem.
- Case
Outcome - The indexed result of one independent case.
- Dense
Segment Data - Version-one polynomial representation for interchange.
- LieGroup
Problem - A homogeneous-space or matrix Lie-group problem driven by a dense Lie algebra generator.
- Linear
Operator Problem - A vector problem driven by a dense, possibly state- and time-dependent
linear operator:
u' = A(u, p, t) u. - Mutable
Function - Sequential adapter for a mutable, fallible in-place right-hand side.
- OdeProblem
- An initial-value ordinary differential equation problem.
- OdeProblem
Builder - A type-state builder for an ndarray-backed
OdeProblem. - Portable
Dense Segment - Validated immutable polynomial segment, safe to move or share across threads.
- Semilinear
OdeProblem - A semilinear initial-value problem
u' = A u + g(u, p, t). - Solution
- A saved ODE trajectory.
- Solution
Data - Versioned trajectory interchange including logical state shape and dense output. Work statistics describe the original integration and are preserved.
- Solve
Options - Common options for adaptive ODE solvers.
- Solver
Stats - Work performed by an ODE solver.
- Split
OdeProblem - A split/IMEX ODE representation retaining explicit and implicit components.
Enums§
- Automatic
Pair Incompatibility - Explains why two components cannot be used as an automatic solver pair.
- Callback
Action - The action requested after an ODE callback runs.
- Callback
Save - Selects which states a callback forces into the saved trajectory.
- Configuration
Error - Invalid data supplied while constructing a problem or algorithm.
- Event
Crossing - Describes whether and how one vector callback condition crossed zero.
- Event
Direction - Selects which zero crossings trigger a continuous callback.
- Execution
Policy - Selects how independent cases are executed.
- Interpolation
Error - A dense-output query or retained interpolation segment is invalid.
- Interpolation
Quality - Quality available for an interpolation query.
- Save
Mode - Controls which accepted states are retained in a
Solution. - Solution
Construction Error - Invalid saved trajectory data supplied when constructing a
Solution. - Solve
Error - A failure to configure or complete an ODE solve.
Constants§
- DEFAULT_
EVENT_ TOLERANCE - Default requested absolute tolerance for continuous-event localization.
Traits§
- OdeAlgorithm
- An ODE integration algorithm.
- OdeFunction
- A statically dispatched, fallible ODE right-hand side.
Functions§
- solve
- Solves an ODE problem with a selected algorithm.
- solve_
batch - Runs independent fallible cases as an ordered batch.
- solve_
batch_ parallel - Runs independent fallible cases on Rayon’s global thread pool.
- solve_
batch_ sequential - Runs independent fallible cases sequentially without thread-safety bounds.
- solve_
ensemble - Solves an ensemble of independently constructed ODE problems.
- solve_
ensemble_ parallel - Solves an ODE ensemble on Rayon’s global thread pool.
- solve_
ensemble_ sequential - Solves an ODE ensemble sequentially without requiring transferable problems.