diffsol_c/

lib.rs

//! # diffsol-c
//!
//! diffsol-c is a companion crate to [diffsol](https://crates.io/crates/diffsol) that
//! provides two higher-level APIs on top of the core `diffsol` library:
//!
//! 1. A **dynamic dispatch** API that wraps the generic solver in runtime-dispatched types,
//!    allowing you to select the matrix backend, scalar type, linear solver, ODE solver method,
//!    and JIT backend at runtime rather than at compile time.
//! 2. A **C FFI** API that exposes the dynamic dispatch API via `extern "C"` functions,
//!    enabling integration with C, Wasm, Matlab and other languages
//!    with a C-compatible interface.
//!
//! ## Dynamic Dispatch API
//!
//! The core of the dynamic dispatch API is the [OdeWrapper] struct. It wraps the internal
//! solver state in an `Arc<Mutex<...>>` so that it can be shared across threads and across
//! FFI boundaries. Unlike the core `diffsol` crate — which requires you to specify the matrix
//! type, code generation backend, ODE equation type, linear solver, and solver method all as
//! generic parameters — `OdeWrapper` erases these type parameters behind trait objects so you
//! can choose them at runtime.
//!
//! To create an `OdeWrapper`, use [OdeWrapper::new_callbacks] if you have the equations as
//! C callbacks (see [ode_callbacks]), or one of the feature-gated DiffSL constructors:
//! - `new_jit` if you have DiffSL code to JIT-compile (requires the
//!   `diffsl-cranelift` or `diffsl-llvm` feature).
//! - `new_external` if you have pre-compiled DiffSL symbols (requires the
//!   `external` feature).
//! - `new_external_dynamic` if you have a shared library with pre-compiled
//!   DiffSL symbols (requires the `diffsl-external-dynamic` feature).
//!
//! Once created, the `OdeWrapper` provides methods to configure solver tolerances and options
//! (e.g. [OdeWrapper::set_rtol], [OdeWrapper::set_atol], [OdeWrapper::set_t0],
//! [OdeWrapper::set_h0]), query equation metadata (e.g. [OdeWrapper::get_nstates],
//! [OdeWrapper::get_nparams], [OdeWrapper::get_nout]), and access separate option handles
//! via [OdeWrapper::get_options] (returning an [OdeSolverOptions]) and
//! [OdeWrapper::get_ic_options] (returning an [InitialConditionSolverOptions]).
//!
//! Solving is done via the following methods:
//! - [OdeWrapper::solve] — adaptive-time integration to a final time.
//! - [OdeWrapper::solve_dense] — integration to a specified set of time points.
//! - [OdeWrapper::solve_fwd_sens] — forward sensitivity analysis.
//! - [OdeWrapper::solve_continuous_adjoint] — continuous adjoint sensitivity analysis.
//! - [OdeWrapper::solve_adjoint_fwd] / [OdeWrapper::solve_adjoint_bkwd] — discrete adjoint
//!   sensitivity analysis (forward + backward pass).
//! - [OdeWrapper::solve_vjp_fwd] / [OdeWrapper::solve_vjp_bkwd] — reverse-mode
//!   differentiation of the solver steps (forward + backward pass).
//!
//! Each solve method returns a [SolutionWrapper], from which you can extract the solution
//! values via [SolutionWrapper::get_ys], [SolutionWrapper::get_ts], and
//! [SolutionWrapper::get_sens]. These methods return [Tensor] objects, which own the
//! Rust-allocated data, and which the host language can read without copying. The inputs, for
//! example `params` and `t_eval`, are [TensorView] objects, which borrow the data of the caller.
//!
//! The adoint solve methods involve an [AdjointCheckpointWrapper] that stores forward-pass
//! checkpoint data required for the backward pass. The VJP solve methods use a
//! [VjpCheckpointWrapper] in the same way.
//!
//! ### Runtime configuration types
//!
//! The dynamic dispatch API uses the following enums to configure the solver at runtime:
//! - [OdeSolverType] — the ODE solver method ([OdeSolverType::Bdf],
//!   [OdeSolverType::Esdirk34], [OdeSolverType::TrBdf2], [OdeSolverType::Tsit45]).
//! - [MatrixType] — the matrix backend ([MatrixType::NalgebraDense],
//!   [MatrixType::FaerDense], [MatrixType::FaerSparse]).
//! - [ScalarType] — the floating-point type ([ScalarType::F32], [ScalarType::F64]).
//! - [LinearSolverType] — the linear solver for implicit methods
//!   ([LinearSolverType::Default], [LinearSolverType::Lu], [LinearSolverType::Klu]).
//! - [JitBackendType] — the JIT backend for compiling DiffSL code
//!   (`Cranelift` or `Llvm` depending on enabled features).
//!
//! ### Error handling
//!
//! All operations that can fail in the dynamic dispatch API return
//! `Result<_, [DiffsolRtError]>`, a runtime error type wrapping the core
//! [DiffsolError](diffsol::error::DiffsolError).
//!
//! ## C FFI API
//!
//! The C FFI API is exposed via `extern "C"` functions across several modules suffixed `_c`.
//! These functions wrap the dynamic dispatch API using raw pointers and integer error codes
//! so that they can be called from C or any language with C interop. The public `_c` modules
//! are:
//! - [ode_c] — create, configure, solve, and destroy [OdeWrapper] handles.
//! - [ode_callbacks_c] — create an [OdeWrapper] from equations given as C callbacks.
//! - `ode_diffsl_c` — create an [OdeWrapper] from DiffSL equations (JIT or external symbols).
//! - [solution_wrapper_c] — extract solution data and destroy [SolutionWrapper] handles.
//! - [vjp_checkpoint_c] — destroy [VjpCheckpointWrapper] handles.
//! - [ode_options_c] — get/set solver convergence and performance options.
//! - [initial_condition_options_c] — get/set initial condition solver options.
//! - [matrix_type_c], [scalar_type_c], [linear_solver_type_c],
//!   [ode_solver_type_c], [jit_c] — query and convert enum values.
//! - [tensor_c] — inspect and free [Tensor] data.
//! - [error_c] — retrieve and clear thread-local error messages.
//! - [string_c] — allocate and free Rust-owned strings from C.
//!
//! A build of this crate makes a dynamic library (`libdiffsol_c.so`, `.dylib` or `.dll`) and
//! the C header `target/<profile>/include/diffsol.h`. A static library is made on request, with
//! `cargo rustc -p diffsol-c --lib --crate-type staticlib`.
//! The build script makes the header with cbindgen, and the header agrees with the features of
//! the build. The README and the examples in `examples/diffsol-c-logistic/c` of the workspace
//! show how to compile and link a C program.
//!
//! All C FFI functions follow a common pattern:
//! - Return `i32` (0 = success, negative = error).
//! - Store error details in a thread-local variable retrievable via functions in [error_c].
//! - Use raw pointers for ownership transfer (caller allocates/frees via dedicated functions).
//!
//! See [c_api_utils] for the internal macros and helper functions used by the C FFI layer.
//!
//! ## Feature flags
//!
//! The crate requires at least one of the following features to be enabled:
//! - `diffsl-cranelift` — enable the Cranelift JIT backend for DiffSL code.
//! - `diffsl-llvm` — enable the LLVM JIT backend for DiffSL code (requires an LLVM
//!   installation; use a version-specific feature like `diffsl-llvm21`).
//! - `external` — enable statically linked pre-compiled DiffSL symbols.
//! - `external-dynamic` — enable dynamically loaded pre-compiled DiffSL symbols.
//!
//! Additional features:
//! - `suitesparse` — enable the KLU sparse linear solver.
//! - `sundials` — enable SUNDIALS support (via the core `diffsol` crate).
//! - `cuda` — enable CUDA GPU support (via the core `diffsol` crate). Deprecated.
//!
//! ## Utility functions
//!
//! The [utils] module provides a few standalone functions:
//! - [utils::version] — returns the crate version.
//! - [utils::is_klu_available] — checks whether KLU was compiled in.

// Configure dlmalloc as the global allocator for WASM targets
// dlmalloc is a maintained alternative to the unmaintained wee_alloc
#[cfg(target_arch = "wasm32")]
use dlmalloc::GlobalDlmalloc;

#[cfg(not(any(
    feature = "external",
    feature = "external-dynamic",
    feature = "diffsl-cranelift",
    feature = "diffsl-llvm"
)))]
compile_error!(
    "diffsol-c requires one of `external`, `external-dynamic`, `diffsl-cranelift`, or `diffsl-llvm`."
);

#[cfg(target_arch = "wasm32")]
#[global_allocator]
static ALLOCATOR: GlobalDlmalloc = GlobalDlmalloc;

#[cfg(all(feature = "diffsl-llvm15", feature = "diffsl-llvm16"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm15", feature = "diffsl-llvm17"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm15", feature = "diffsl-llvm18"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm15", feature = "diffsl-llvm19"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm15", feature = "diffsl-llvm20"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm15", feature = "diffsl-llvm21"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm16", feature = "diffsl-llvm17"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm16", feature = "diffsl-llvm18"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm16", feature = "diffsl-llvm19"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm16", feature = "diffsl-llvm20"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm16", feature = "diffsl-llvm21"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm17", feature = "diffsl-llvm18"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm17", feature = "diffsl-llvm19"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm17", feature = "diffsl-llvm20"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm17", feature = "diffsl-llvm21"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm18", feature = "diffsl-llvm19"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm18", feature = "diffsl-llvm20"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm18", feature = "diffsl-llvm21"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm19", feature = "diffsl-llvm20"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm19", feature = "diffsl-llvm21"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");
#[cfg(all(feature = "diffsl-llvm20", feature = "diffsl-llvm21"))]
compile_error!("diffsol-c cannot enable more than one `diffsl-llvm*` feature.");

/// Adjoint checkpoint wrapper for storing and retrieving forward-pass checkpoint data.
///
/// This module provides [AdjointCheckpointWrapper], a thread-safe wrapper around the
/// internal `AdjointCheckpoint` trait object. It is created during the forward pass of a
/// discrete adjoint solve (via [OdeWrapper::solve_adjoint_fwd])
/// and consumed during the backward pass (via [OdeWrapper::solve_adjoint_bkwd]).
///
/// The internal `AdjointCheckpoint` trait erases the concrete matrix, codegen, and solver tag
/// types, allowing the checkpoint to be shared between the forward and backward solvers which
/// may use different ODE solver methods (e.g. BDF forward, ESDIRK backward).
///
/// The `AdjointCheckpointData<M, Eqn, Tag>` struct stores the concrete [CheckpointingPath](diffsol::CheckpointingPath)
/// plus the forward solver metadata (method, linear solver, parameters).
pub mod adjoint_checkpoint;
/// Macros and helper functions for the C FFI layer.
///
/// This module provides the internal infrastructure used by the `*_c` modules to implement
/// `extern "C"` functions. It defines:
/// - Return code constants: `DIFFSOL_OK` (0), `DIFFSOL_ERR` (-1), `DIFFSOL_BAD_ARG` (-2).
/// - Conversion traits `CMapTo<Out>` / `CMapFrom<In>` for mapping between Rust and C types.
/// - Helper functions for common patterns: `map_get`, `map_set`, `invalid_arg_at`, `error_at`,
///   `null_err_at`, `valid_f64_ptr`.
/// - Convenience macros: `c_invalid_arg!`, `c_error!`, `c_null_err!`, `c_getter_simple!`,
///   `c_setter_simple!`.
///
/// This module is not intended for external use; it exists to share boilerplate across the
/// `_c` modules.
pub mod c_api_utils;
/// Runtime error type for the dynamic dispatch API.
///
/// This module defines [DiffsolRtError], a newtype wrapper around
/// [DiffsolError](diffsol::error::DiffsolError). It implements
/// `Display`, `std::error::Error`, and `From<DiffsolError>`. All operations in the
/// dynamic dispatch API that can fail return `Result<_, DiffsolRtError>`.
pub mod error;
/// C FFI error handling.
///
/// This module provides thread-local error storage and `extern "C"` functions for retrieving
/// and clearing error information from C code:
/// - `diffsol_error_code` — returns `DIFFSOL_OK`, `DIFFSOL_ERR`, or `DIFFSOL_BAD_ARG`.
/// - `diffsol_last_error_message` — returns a pointer to the last error message.
/// - `diffsol_last_error_file` / `diffsol_last_error_line` — return the source location of the last error.
/// - `diffsol_clear_last_error` — clears the thread-local error state.
#[path = "error_c.rs"]
pub mod error_c;
/// Options for the initial condition solver used before integration.
///
/// This module defines [InitialConditionSolverOptions], a handle obtained via
/// [OdeWrapper::get_ic_options]. It provides
/// getters and setters for configuring the nonlinear root-finding solver that computes
/// the initial state of the ODE system:
/// - Line search settings: [InitialConditionSolverOptions::get_use_linesearch],
///   [InitialConditionSolverOptions::get_max_linesearch_iterations].
/// - Newton iteration limits: [InitialConditionSolverOptions::get_max_newton_iterations],
///   [InitialConditionSolverOptions::get_max_linear_solver_setups].
/// - Step control: [InitialConditionSolverOptions::get_step_reduction_factor],
///   [InitialConditionSolverOptions::get_armijo_constant].
///
/// Also includes [InitialConditionSolverOptionsSnapshot], a serializable snapshot used
/// for serde round-tripping of solver configuration.
pub mod initial_condition_options;
/// C FFI functions for getting and setting [InitialConditionSolverOptions].
///
/// Provides `extern "C"` getter/setter functions for each option field exposed by
/// `InitialConditionSolverOptions`, using `i32` for boolean values and `f64`/`usize`
/// for numeric fields.
#[path = "initial_condition_options_c.rs"]
pub mod initial_condition_options_c;
/// JIT backend type for compiling DiffSL code at runtime.
///
/// This module defines [JitBackendType], an enum representing the available JIT
/// compilation backends for DiffSL code:
/// - `Cranelift` — available when the `diffsl-cranelift` feature is enabled.
/// - `Llvm` — available when the `diffsl-llvm` feature is enabled.
///
/// The function [default_enabled_jit_backend] returns the preferred backend based on which
/// features are compiled in (LLVM is preferred over Cranelift if both are available).
pub mod jit;
/// C FFI functions for querying [JitBackendType] enum values.
///
/// Provides `extern "C"` functions to enumerate available JIT backends, check whether a
/// backend value is valid, and get the name string of a backend.
#[path = "jit_c.rs"]
pub mod jit_c;
/// Linear solver type for implicit ODE solvers.
///
/// This module defines [LinearSolverType], an enum specifying which linear solver to use
/// inside implicit ODE methods (BDF, ESDIRK, TR-BDF2):
/// - [LinearSolverType::Default] — the solver's default choice (typically LU).
/// - [LinearSolverType::Lu] — LU decomposition (dense or sparse as appropriate).
/// - [LinearSolverType::Klu] — KLU sparse linear solver (requires `suitesparse` feature).
pub mod linear_solver_type;
/// C FFI functions for querying and converting [LinearSolverType] enum values.
///
/// Provides `extern "C"` functions to map between `i32` values and the `LinearSolverType`
/// enum variants, and to get the name of a linear solver type as a C string.
#[path = "linear_solver_type_c.rs"]
pub mod linear_solver_type_c;
/// Matrix backend type for the ODE solver.
///
/// This module defines [MatrixType], an enum specifying the matrix/linear algebra backend:
/// - [MatrixType::NalgebraDense] — dense matrix using the [nalgebra](https://nalgebra.org) crate.
/// - [MatrixType::FaerDense] — dense matrix using the [faer](https://github.com/sarah-ek/faer-rs) crate.
/// - [MatrixType::FaerSparse] — sparse matrix using the [faer](https://github.com/sarah-ek/faer-rs) crate.
pub mod matrix_type;
/// C FFI functions for querying and converting [MatrixType] enum values.
///
/// Provides `extern "C"` functions to map between `i32` values and the `MatrixType` enum
/// variants, and to get the name of a matrix type as a C string.
#[path = "matrix_type_c.rs"]
pub mod matrix_type_c;
/// Dynamic dispatch ODE wrapper — the primary entry point for the dynamic dispatch API.
///
/// This module defines [OdeWrapper], a thread-safe handle around an internal ODE solver.
/// `OdeWrapper` erases the generic type parameters of the core `diffsol` solver (matrix type,
/// codegen backend, linear solver, solver method) so that they can be chosen at runtime rather
/// than compile time. The internal state is stored behind an `Arc<Mutex<...>>` for safe sharing
/// across threads.
///
/// # Constructors
/// - `new_jit` — JIT-compile DiffSL code (requires `diffsl-cranelift` or `diffsl-llvm`).
/// - `new_external` — use statically linked pre-compiled DiffSL symbols (requires `external`).
/// - `new_external_dynamic` — load pre-compiled DiffSL symbols from a shared library
///   (requires `diffsl-external-dynamic`).
///
/// # Configuration
/// Tolerances: [OdeWrapper::set_rtol], [OdeWrapper::set_atol], [OdeWrapper::set_t0],
/// [OdeWrapper::set_h0], [OdeWrapper::set_integrate_out].
/// Sensitivity tolerances: [OdeWrapper::set_sens_rtol], [OdeWrapper::set_sens_atol],
/// [OdeWrapper::set_out_rtol], [OdeWrapper::set_out_atol],
/// [OdeWrapper::set_param_rtol], [OdeWrapper::set_param_atol].
/// Solver selection: [OdeWrapper::set_ode_solver], [OdeWrapper::set_linear_solver].
///
/// # Solving
/// - [OdeWrapper::solve] — adaptive-time integration.
/// - [OdeWrapper::solve_dense] — integration to specified time points.
/// - [OdeWrapper::solve_fwd_sens] — forward sensitivity analysis.
/// - [OdeWrapper::solve_continuous_adjoint] — continuous adjoint.
/// - [OdeWrapper::solve_adjoint_fwd] / [OdeWrapper::solve_adjoint_bkwd] — discrete adjoint.
/// - [OdeWrapper::solve_vjp_fwd] / [OdeWrapper::solve_vjp_bkwd] — reverse mode
///   through the solver steps.
///
/// # Low-level evaluation
/// - [OdeWrapper::y0] — compute initial state.
/// - [OdeWrapper::rhs] — evaluate the RHS function.
/// - [OdeWrapper::rhs_jac_mul] — evaluate the Jacobian-vector product.
///
/// # Serialization
/// `OdeWrapper` implements `Serialize`/`Deserialize` for JIT-backed solvers.
pub mod ode;
/// C FFI functions for creating, configuring, solving, and destroying [OdeWrapper] objects.
///
/// Provides `extern "C"` functions for the full lifecycle of an ODE solver:
/// - `diffsol_ode_wrapper_new_*` — constructors (feature-gated by JIT backend or external).
/// - `diffsol_ode_wrapper_get_*` / `diffsol_ode_wrapper_set_*` — getters/setters for tolerances,
///   time settings, solver type, and linear solver.
/// - `diffsol_ode_wrapper_y0`, `diffsol_ode_wrapper_rhs`, `diffsol_ode_wrapper_rhs_jac_mul` —
///   low-level RHS evaluation.
/// - `diffsol_ode_wrapper_solve`, `diffsol_ode_wrapper_solve_dense`,
///   `diffsol_ode_wrapper_solve_fwd_sens`, `diffsol_ode_wrapper_solve_continuous_adjoint`,
///   `diffsol_ode_wrapper_solve_adjoint_fwd`, `diffsol_ode_wrapper_solve_adjoint_bkwd` —
///   solve functions returning [SolutionWrapper] pointers.
/// - `diffsol_ode_solve_vjp_fwd`, `diffsol_ode_solve_vjp_bkwd` — reverse mode
///   through the solver steps, with a [VjpCheckpointWrapper] between the two passes.
/// - `diffsol_ode_wrapper_free` — free an `OdeWrapper`.
/// - Serialization: `diffsol_ode_wrapper_serialize`, `diffsol_ode_wrapper_deserialize`.
#[path = "ode_c.rs"]
pub mod ode_c;
/// ODE equations defined by C callbacks.
///
/// [OdeCallbacks] implements every flavour of [diffsol::OdeEquations] on top of a table of C
/// function pointers, [OdeCallbacksDesc], one for each closure accepted by
/// [diffsol::OdeBuilder] plus a `user_data` argument. See the module documentation for the
/// callback conventions and the ownership of `user_data`.
pub mod ode_callbacks;
/// C FFI functions for creating an [OdeWrapper] from equations given as C callbacks.
///
/// - `diffsol_ode_new_callbacks_f64` / `diffsol_ode_new_callbacks_f32` — construct an [OdeWrapper]
///   from a [DiffsolOdeCallbacksF64](ode_callbacks::DiffsolOdeCallbacksF64) /
///   [DiffsolOdeCallbacksF32](ode_callbacks::DiffsolOdeCallbacksF32) descriptor.
#[path = "ode_callbacks_c.rs"]
pub mod ode_callbacks_c;
/// DiffSL equations: the [OdeWrapper] constructors (`new_jit`, `new_external`,
/// `new_external_dynamic`), the solver factories, and the `SolveEqn` impls for each code
/// generation backend. All items are `pub(crate)`, apart from the [OdeWrapper] methods.
mod ode_diffsl;
/// C API constructors for DiffSL equations: JIT-compiled code, and external symbols.
#[cfg(any(
    feature = "external",
    feature = "diffsl-external-dynamic",
    feature = "diffsl-cranelift",
    feature = "diffsl-llvm",
))]
#[path = "ode_diffsl_c.rs"]
pub mod ode_diffsl_c;
/// ODE solver convergence and performance options for the dynamic dispatch API.
///
/// This module defines [OdeSolverOptions], a handle obtained via
/// [OdeWrapper::get_options]. It provides getters and
/// setters for tuning the nonlinear solver and time-stepping behaviour of the ODE integrator:
/// - Nonlinear solver: [OdeSolverOptions::get_max_nonlinear_solver_iterations],
///   [OdeSolverOptions::get_max_error_test_failures],
///   [OdeSolverOptions::get_max_nonlinear_solver_failures].
/// - Jacobian updates: [OdeSolverOptions::get_update_jacobian_after_steps],
///   [OdeSolverOptions::get_update_rhs_jacobian_after_steps],
///   [OdeSolverOptions::get_threshold_to_update_jacobian],
///   [OdeSolverOptions::get_threshold_to_update_rhs_jacobian].
/// - Step size: [OdeSolverOptions::get_min_timestep].
/// - BDF derivative solves (forward sensitivities, VJPs):
///   [OdeSolverOptions::get_derivative_solve_tolerance],
///   [OdeSolverOptions::get_derivative_solve_max_iter].
///
/// Also includes [OdeSolverOptionsSnapshot], a serializable snapshot used for serde
/// round-tripping of solver configuration.
pub mod ode_options;
/// C FFI functions for getting and setting [OdeSolverOptions].
///
/// Provides `extern "C"` getter/setter functions for each option field exposed by
/// `OdeSolverOptions`, using `f64` for floating-point values and `usize` for integer fields.
#[path = "ode_options_c.rs"]
pub mod ode_options_c;
mod ode_solver_tag;
/// ODE solver method type.
///
/// This module defines [OdeSolverType], an enum specifying which ODE integration method to use:
/// - [OdeSolverType::Bdf] — Backward Differentiation Formula (stiff ODEs, singular mass matrices).
/// - [OdeSolverType::Esdirk34] — Explicit Singly Diagonally Implicit Runge-Kutta (moderately stiff).
/// - [OdeSolverType::TrBdf2] — Trapezoidal BDF of order 2 (moderately stiff).
/// - [OdeSolverType::Tsit45] — Tsitouras 4/5th order Explicit Runge-Kutta (non-stiff, explicit).
///
/// The internal `solve` methods on this enum dispatch to the appropriate diffsol solver type
/// via tag structs defined in the private `ode_solver_tag` module.
pub mod ode_solver_type;
/// C FFI functions for querying and converting [OdeSolverType] enum values.
///
/// Provides `extern "C"` functions to map between `i32` values and the `OdeSolverType` enum
/// variants, and to get the name of an ODE solver type as a C string.
#[path = "ode_solver_type_c.rs"]
pub mod ode_solver_type_c;
/// Floating-point scalar type for diffisol.
///
/// This module defines [ScalarType], an enum identifying the floating-point type used
/// by the solver:
/// - [ScalarType::F32] — 32-bit single precision.
/// - [ScalarType::F64] — 64-bit double precision.
///
/// It also defines the [Scalar] trait (combining [DiffSlScalar](diffsol::DiffSlScalar)
/// with [ToScalarType]) and the [ToScalarType] trait for mapping Rust types (`f32`, `f64`)
/// to their `ScalarType` variant.
pub mod scalar_type;
/// C FFI functions for querying and converting [ScalarType] enum values.
///
/// Provides `extern "C"` functions to map between `i32` values and the `ScalarType` enum
/// variants (`F32` / `F64`), and to get the name of a scalar type as a C string.
#[path = "scalar_type_c.rs"]
pub mod scalar_type_c;
/// Internal trait used by [SolutionWrapper] for type-erased solution access.
///
/// The `Solution` trait provides the object-safe interface that `SolutionWrapper` wraps.
/// It is implemented for [diffsol::Solution] for all compatible vector
/// types `V`. The trait is `pub(crate)` — the public API is exposed through `SolutionWrapper`.
pub mod solution;
/// Solution wrapper for the dynamic dispatch API.
///
/// This module defines [SolutionWrapper], a thread-safe handle around a type-erased ODE
/// solution. Returned by all solve methods on [OdeWrapper], it
/// provides methods to extract the solution data:
/// - [SolutionWrapper::get_ys] — the state values at each time point (returns [Tensor]).
/// - [SolutionWrapper::get_ts] — the time points (returns [Tensor]).
/// - [SolutionWrapper::get_sens] — the sensitivity matrices (returns `Vec<Tensor>`).
///
/// `SolutionWrapper` implements `Serialize`, serializing as `{dtype, ts, ys, sensitivities}`, with
/// the values in the scalar type of the solver (`dtype`).
pub mod solution_wrapper;
/// C FFI functions for extracting data from and freeing [SolutionWrapper] objects.
///
/// Provides `extern "C"` functions to retrieve the time points, state values, and sensitivities
/// from a `SolutionWrapper`, and to free the wrapper when no longer needed.
#[path = "solution_wrapper_c.rs"]
pub mod solution_wrapper_c;
/// Core dynamic dispatch trait and its implementation.
///
/// Defines the `Solve` trait, the object-safe trait that erases the generic type parameters
/// of the core `diffsol` solver. Each combination of matrix type, codegen backend, and solver
/// method implements this trait. The concrete `GenericSolve<M, CG>` struct provides the
/// implementation.
///
/// Also provides factory functions (`solve_factory_jit`, `solve_factory_external`,
/// `solve_factory_external_dynamic`) that create the appropriate `Box<dyn Solve>` for a given
/// configuration. These are called by [OdeWrapper]'s constructors.
///
/// All items in this module are `pub(crate)`; the public API is exposed through `OdeWrapper`.
pub mod solve;
/// The hooks for each equation type that the solver uses.
///
/// Defines the `SolveEqn` trait, and implements it for DiffSL equations with each code
/// generation backend. The hooks give serialization, the requirement checks before a solve, and
/// the errors that the equations recorded. All items are `pub(crate)`.
mod solve_eqn;
/// Internal macros for generating ODE solver option accessor methods.
///
/// This module provides macros used by the `Solve` trait implementation
/// to automatically generate getter/setter methods for initial condition and ODE solver options.
/// The macros are `pub(crate)` and intended only for internal use within the `diffsol-c` crate.
pub mod solve_macros;
/// C FFI memory management helpers for string and byte buffer allocation.
///
/// Provides `extern "C"` functions for allocating and freeing Rust-owned memory from C code:
/// - `diffsol_alloc_string` / `diffsol_free_string` — allocate/free Rust-owned C strings.
/// - `diffsol_alloc` / `diffsol_free` — allocate/free byte buffers.
///
/// These are used by the other `_c` modules when returning dynamically sized data (e.g.
/// serialized equation blobs) to C callers.
#[path = "string_c.rs"]
pub mod string_c;
/// Arrays that Rust and the host language share without a copy.
///
/// This module defines two types, a bridge between numeric arrays in Rust and in the host
/// language (Python, C, Wasm/JS). Both store a raw data pointer together with shape, strides
/// (in bytes) and scalar type metadata.
/// - [Tensor] is an output. It always owns the value that holds its data (a `Box<dyn Any>`), so
///   the data stays valid while the `Tensor` exists. It is the return type of
///   [SolutionWrapper::get_ys], [SolutionWrapper::get_ts], [SolutionWrapper::get_sens] and of the
///   [OdeWrapper] methods that give values.
/// - [TensorView] is an input, for example `params` and `t_eval` of the [OdeWrapper] solve
///   methods. It does not own its data, and the lifetime of the view is that of the data. It is
///   small, `Copy`, only on the stack, and has at most [tensor::MAX_NDIM] (3) axes.
/// - [TensorViewMut] is a mutable view, the output `y` of a C callback (see [ode_callbacks]).
///   No two of its indices give the same value.
///
/// [TensorView] and [TensorViewMut] have the C layout of [tensor::RawLayout] (the fields `ptr`,
/// `dtype`, `ndim`, `shape` and `strides`), so a C callback reads their fields directly.
///
/// # Batches
/// A diffsol vector or dense matrix can have more than one lane (`nbatch`). The arrays use the
/// column-major order of diffsol, and the last axis of an array of lanes is always the lane,
/// also when `nbatch` is 1. For a diffsol vector, the
/// shape is `[n, nbatch]`. For a dense matrix, the shape is `[nrows, ncols, nbatch]`. If an input
/// array has one lane, all the lanes get its values.
///
/// # Key methods
/// - [Tensor::from_vec] — make an array that owns a `Vec`, in column-major order.
/// - [Tensor::new] — make an array that owns any value that holds the data on the heap
///   (`unsafe`).
/// - [Tensor::view] — a [TensorView] of an array, with no copy.
/// - [TensorView::from_slice] — view a slice, in column-major order.
/// - [TensorView::new] — view data with strides that obey the layout rules (`unsafe`: the caller
///   keeps the data valid while the view exists). It gives an error for other layouts, for
///   example a row-major array.
/// - [Tensor::column], [Tensor::columns] ([TensorView::column], [TensorView::columns]) — the
///   columns `[:, j, k]` as slices, with no copy. Each column is contiguous, by the layout rules.
/// - [Tensor::index] ([TensorView::index]) — a reference to one value. The [Tensor] docs give
///   the data layout and the layout rules.
/// - [Tensor::shape], [Tensor::strides], [Tensor::dtype], [Tensor::data_ptr] (and the same
///   methods of [TensorView]) — the metadata. With these, a host language can show the data with
///   no copy, for example as a NumPy array with the same shape and strides.
pub mod tensor;
/// C FFI functions for inspecting and freeing [Tensor] objects.
///
/// Provides `extern "C"` functions for querying `Tensor` metadata (dimensions, strides,
/// data type, raw pointer) and for freeing a `Tensor` previously returned by this library. The C
/// header uses the same name, `Tensor`.
#[path = "tensor_c.rs"]
pub mod tensor_c;
/// Utility functions for querying library capabilities.
///
/// Provides standalone functions useful for runtime capability checks:
/// - [version] — returns the crate version string.
/// - [is_klu_available] — returns `true` if the `suitesparse` feature (KLU sparse linear solver) was enabled at compile time.
pub mod utils;
/// Internal validation of linear solver compatibility with matrix types.
///
/// Provides `validate_linear_solver::<M>(linear_solver)` which checks that a given
/// [LinearSolverType] is compatible with a
/// matrix type `M`. For example, KLU is only valid for `FaerSparseMat<f64>` when the
/// `suitesparse` feature is enabled. Uses `LuValidator<M>` and `KluValidator<M>` traits
/// to associate each matrix type with its valid linear solver implementations.
pub mod valid_linear_solver;
/// VJP checkpoint wrapper for keeping the forward pass of a reverse-mode solve.
///
/// This module provides [VjpCheckpointWrapper], a thread-safe wrapper around the internal
/// `VjpCheckpoint` trait object. It is created by the forward pass of a VJP solve (via
/// [OdeWrapper::solve_vjp_fwd]) and used by one or more backward passes (via
/// [OdeWrapper::solve_vjp_bkwd]).
///
/// It holds a [DenseVjpTape](diffsol::DenseVjpTape): the solver state after each step of the
/// forward solve. The backward pass must use the solver of the forward pass, so the checkpoint
/// also keeps the method, the linear solver and the parameters.
pub mod vjp_checkpoint;
/// C FFI function for freeing [VjpCheckpointWrapper] objects, which
/// `diffsol_ode_solve_vjp_fwd` returns.
#[path = "vjp_checkpoint_c.rs"]
pub mod vjp_checkpoint_c;

#[cfg(test)]
mod test_support;

#[cfg(test)]
mod ode_callbacks_requirements_test;

pub use adjoint_checkpoint::AdjointCheckpointWrapper;
pub use error::DiffsolRtError;
pub use initial_condition_options::{
    InitialConditionSolverOptions, InitialConditionSolverOptionsSnapshot,
};
pub use jit::{default_enabled_jit_backend, JitBackendType};
pub use linear_solver_type::LinearSolverType;
pub use matrix_type::MatrixType;
pub use ode::OdeWrapper;
pub use ode_callbacks::{
    for_each_batch, CallbackMatrix, CallbackScalar, OdeCallbackError, OdeCallbacks,
    OdeCallbacksDesc,
};
pub use ode_options::{OdeSolverOptions, OdeSolverOptionsSnapshot};
pub use ode_solver_type::OdeSolverType;
pub use scalar_type::{Scalar, ScalarType, ToScalarType};
pub use solution_wrapper::SolutionWrapper;
pub use tensor::{Tensor, TensorView, TensorViewMut};
pub use utils::{is_klu_available, version};
pub use vjp_checkpoint::VjpCheckpointWrapper;