Skip to main content

Crate cauchy_ode

Crate cauchy_ode 

Source
Expand description

§cauchy-ode

Write equations naturally in Rust, with symbolic Jacobians and adaptive stiff solvers. cauchy-ode solves initial value problems for ordinary differential equations using England, Lawson, and Rosenbrock methods implemented in Fortran.

Start with Solver for a single solve, or construct an OdeSystem to reuse parsed equations and declare their structure. MathExpr provides standalone expression evaluation and symbolic differentiation.

§Installation and native dependencies

Add the crate to your application:

[dependencies]
cauchy-ode = "0.1"

The Rust import name is cauchy_ode. Building and running require a native Fortran toolchain and numerical libraries:

PlatformNative requirements
LinuxGNU Fortran, a C linker, ar, and BLAS/LAPACK development libraries
macOSGNU Fortran and a C toolchain; Accelerate is supplied by macOS
Windows x86_64 MSVCIntel Fortran (ifx), oneMKL, and Visual Studio C++ build tools

See the build guide for installation commands and runtime setup. Hosted documentation skips native compilation; that does not remove these requirements for applications.

§Solve a scalar equation

Solve x' = t + sqrt(x) with x(1) = 1 up to t = 2:

use cauchy_ode::Solver;
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let solution = Solver::default().solve("t+sqrt(x)", 1.0, 1.0, 2.0)?;
    let final_x = solution.states.last().unwrap()[0];
    assert!((final_x - 4.0).abs() < 1e-6);
    Ok(())
}

Solver::solve accepts t and either x or x0 for the scalar state. Solver::solve_system uses t and zero-based state names x0, x1, …:

use cauchy_ode::Solver;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let solution = Solver::default().solve_system(
        &["x1", "-x0"],
        0.0,
        &[1.0, 0.0],
        std::f64::consts::TAU,
    )?;
    assert!((solution.states.last().unwrap()[0] - 1.0).abs() < 1e-6);
    Ok(())
}

§Named variables, parameters, and stiff systems

Construct a system explicitly to choose variable names and bind parameters. For example, this equation has the exact solution x(t) = cos(t) but a fast decaying mode with rate 1000:

use cauchy_ode::{Method, OdeSystem, Solver};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let system = OdeSystem::general_with_parameters(
        "t", &["x"], &["-rate*(x-cos(t))-sin(t)"], &[("rate", 1000.0)],
    )?;
    let solver = Solver {
        method: Method::Rosenbrock,
        tolerance: 1e-10,
        ..Solver::default()
    };
    let solution = solver.solve_problem(&system, 0.0, &[1.0], 1.0)?;
    assert!((solution.states.last().unwrap()[0] - 1.0_f64.cos()).abs() < 1e-6);
    Ok(())
}

OdeSystem uses exactly the names you declare, with no implicit aliases. Parameter bindings are finite constants substituted before symbolic differentiation. The solver prepares the Jacobian and partial time derivative automatically when the selected method requires them.

§System types and methods

TypeEquationConstructorCompatible methods
1: Generalx' = f(t,x)OdeSystem::generalEngland, Lawson, Rosenbrock
2: Autonomousx' = f(x)OdeSystem::autonomousEngland, Lawson, Rosenbrock, RosenbrockAutonomous
3: Linearx' = A(t)x + phi(t)OdeSystem::linearEngland, Lawson, Rosenbrock, LawsonLinear
4: Constant linear partx' = Bx + u(t,x)OdeSystem::splitEngland, Lawson, Rosenbrock, LawsonSplit

Each constructor also has a _with_parameters variant. new and new_with_parameters remain compatibility aliases for the general constructors. Matrix entries use column-major order: column * dimension + row. Linear forcing depends only on time; the split matrix is constant.

England is the default explicit method. Rosenbrock is a useful starting point for nonlinear stiff systems; the specialized Lawson variants take advantage of linear or split structure. Compatibility does not guarantee efficiency on every problem. See Method::supports and the stiff-system limitations.

§Expressions

The math_expr module contains the complete syntax reference, including all operators and functions. Use explicit multiplication (2*x), ^ for powers, and parentheses for grouping. log(x) is the natural logarithm. Trigonometric functions use radians. There are no built-in pi or e constants; bind them as parameters when needed.

iif(check, negative, otherwise) evaluates its second argument when the check is negative, and its third argument otherwise. Piecewise differentiation does not guarantee smoothness at a switching point or provide event detection.

§Results, accuracy, and errors

Solution stores the initial point and every accepted adaptive step, including the requested endpoint. states[k] corresponds to times[k]. recommended_steps[k] is the signed recommended next step (the initial step at index zero); actual accepted steps are differences between adjacent times. An end time earlier than the start time integrates backward.

Solver exposes initial_step, min_step, max_step, tolerance, relative_threshold, and max_steps. Step-size settings are positive magnitudes. Tolerance controls an estimated local error, not accumulated global error. The relative/absolute criterion uses the maximum state amplitude and the relative_threshold setting. The last step may be shorter than min_step.

Solves return SolverError for invalid inputs, incompatible methods, parse or evaluation failures, non-finite required values, and integration failures. Standalone MathExpr::evaluate can return NaN or infinity for domain errors; solver callbacks check required values for finiteness.

§Examples and license

The example guide includes a console demo, seven interactive attractor viewers, and comparisons against exact solutions for all four system types. Clone the repository to run these examples with cargo run --release --example <name>.

Distributed under the Boost Software License, Version 1.0.

Re-exports§

pub use math_expr::MathExpr;
pub use ode_system::OdeSystem;
pub use ode_system::SystemKind;
pub use solver::Method;
pub use solver::Solution;
pub use solver::Solver;
pub use solver::SolverError;

Modules§

fortran
math_expr
MathExpr expression reference
ode_system
Parsed ODEs, independent of the algorithm used to integrate them.
solver
Adaptive integration with the Fortran England, Lawson and Rosenbrock solvers.