sundials_rs/lib.rs
1#![doc = include_str!("../GUIDE.md")]
2//! Safe, idiomatic Rust bindings to the [SUNDIALS](https://computing.llnl.gov/projects/sundials)
3//! solver library.
4//!
5//! # Solvers
6//!
7//! | Module | Underlying library | What it solves |
8//! |---|---|---|
9//! | [`cvode`] | CVODE | Explicit ODE IVP: `y' = f(t, y)` |
10//! | [`cvodes`] | CVODES | CVODE + forward/adjoint sensitivity |
11//! | [`ida`] | IDA | Implicit DAE IVP: `F(t, y, y') = 0` |
12//! | [`idas`] | IDAS | IDA + forward sensitivity |
13//!
14//! All four solvers use SUNDIALS's variable-order BDF (or Adams for CVODE)
15//! method with an adaptive step-size controller — well-suited for stiff and
16//! mildly stiff problems.
17//!
18//! # Choosing a solver
19//!
20//! - **Explicit ODE** `y' = f(t, y)` → [`cvode`] (no sensitivities) or [`cvodes`]
21//! - **DAE / implicit ODE** `F(t, y, y') = 0` → [`ida`] (no sensitivities) or [`idas`]
22//! - **Need `∂y/∂p`** (parameter gradients, UQ) → [`cvodes`] or [`idas`]
23//!
24//! # Quick start — CVODE BDF
25//! ```no_run
26//! use sundials_rs::cvode::{CvodeBuilder, Method};
27//!
28//! // dy/dt = -y, y(0) = 1.0 (exact: exp(-t))
29//! let y0 = vec![1.0_f64];
30//! let mut solver = CvodeBuilder::new(Method::BDF, &y0)
31//! .rtol(1e-8)
32//! .atol(1e-10)
33//! .build(|_t, y, ydot| { ydot[0] = -y[0]; Ok(()) })
34//! .unwrap();
35//!
36//! let (t, y) = solver.step(1.0).unwrap();
37//! println!("y({t:.3}) = {:.8} (exact {:.8})", y[0], (-t).exp());
38//! ```
39//!
40//! # Quick start — IDA (implicit ODE / DAE)
41//! ```no_run
42//! use sundials_rs::ida::IdaBuilder;
43//!
44//! // Same ODE in residual form: F = y' + y = 0
45//! let y0 = vec![1.0_f64];
46//! let yp0 = vec![-1.0_f64]; // consistent: y'(0) = -y(0)
47//! let mut solver = IdaBuilder::new(&y0, &yp0)
48//! .rtol(1e-8)
49//! .atol(1e-10)
50//! .build(|_t, y, yp, res| { res[0] = yp[0] + y[0]; Ok(()) })
51//! .unwrap();
52//!
53//! let (t, y, _yp) = solver.step(1.0).unwrap();
54//! println!("y({t:.3}) = {:.8} (exact {:.8})", y[0], (-t).exp());
55//! ```
56
57pub mod context;
58pub mod error;
59pub mod nvector;
60pub mod matrix;
61pub mod linear_solver;
62pub mod cvode;
63pub mod cvodes;
64pub mod ida;
65pub mod idas;
66
67pub use error::SundialsError;