Crate diffsol_c 

Diffsol-c

Diffsol-c is a companion crate to 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 one of the feature-gated 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).

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 HostArray objects, which are read-only views of the Rust-allocated data that can be safely accessed from the host language without copying.

The adoint solve methods involve an AdjointCheckpointWrapper that stores forward-pass checkpoint data required for the backward pass.

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.

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.
• solution_wrapper_c — extract solution data and destroy SolutionWrapper 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.
• host_array_c — inspect and free HostArray data.
• error_c — retrieve and clear thread-local error messages.
• string_c — allocate and free Rust-owned strings from C.

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).

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.
• utils::is_sens_available — checks whether sensitivity analysis is supported on this platform.

Re-exports

pub use adjoint_checkpoint::AdjointCheckpointWrapper;

pub use error::DiffsolRtError;

pub use host_array::FromHostArray;

pub use host_array::HostArray;

pub use host_array::ToHostArray;

pub use initial_condition_options::InitialConditionSolverOptions;

pub use initial_condition_options::InitialConditionSolverOptionsSnapshot;

pub use jit::default_enabled_jit_backend;

pub use jit::JitBackendType;

pub use linear_solver_type::LinearSolverType;

pub use matrix_type::MatrixType;

pub use ode::OdeWrapper;

pub use ode_options::OdeSolverOptions;

pub use ode_options::OdeSolverOptionsSnapshot;

pub use ode_solver_type::OdeSolverType;

pub use scalar_type::Scalar;

pub use scalar_type::ScalarType;

pub use scalar_type::ToScalarType;

pub use solution_wrapper::SolutionWrapper;

pub use utils::is_klu_available;

pub use utils::is_sens_available;

pub use utils::version;

Modules

adjoint_checkpoint

Adjoint checkpoint wrapper for storing and retrieving forward-pass checkpoint data.

c_api_utils

Macros and helper functions for the C FFI layer.

error

Runtime error type for the dynamic dispatch API.

error_c

C FFI error handling.

host_array

Read-only array allocated in Rust, safe to access from the host language without copying.

host_array_c

C FFI functions for inspecting and freeing HostArray objects.

initial_condition_options

Options for the initial condition solver used before integration.

initial_condition_options_c

C FFI functions for getting and setting InitialConditionSolverOptions.

jit

JIT backend type for compiling DiffSL code at runtime.

jit_c

C FFI functions for querying JitBackendType enum values.

linear_solver_type

Linear solver type for implicit ODE solvers.

linear_solver_type_c

C FFI functions for querying and converting LinearSolverType enum values.

matrix_type

Matrix backend type for the ODE solver.

matrix_type_c

C FFI functions for querying and converting MatrixType enum values.

ode

Dynamic dispatch ODE wrapper — the primary entry point for the dynamic dispatch API.

ode_c

C FFI functions for creating, configuring, solving, and destroying OdeWrapper objects.

ode_options

ODE solver convergence and performance options for the dynamic dispatch API.

ode_options_c

C FFI functions for getting and setting OdeSolverOptions.

ode_solver_type

ODE solver method type.

ode_solver_type_c

C FFI functions for querying and converting OdeSolverType enum values.

scalar_type

Floating-point scalar type for diffisol.

scalar_type_c

C FFI functions for querying and converting ScalarType enum values.

solution

Internal trait used by SolutionWrapper for type-erased solution access.

solution_wrapper

Solution wrapper for the dynamic dispatch API.

solution_wrapper_c

C FFI functions for extracting data from and freeing SolutionWrapper objects.

solve

Core dynamic dispatch trait and its implementation.

solve_macros

Internal macros for generating ODE solver option accessor methods.

string_c

C FFI memory management helpers for string and byte buffer allocation.

utils

Utility functions for querying library capabilities.

valid_linear_solver

Internal validation of linear solver compatibility with matrix types.

Macros

c_error

c_getter_simple

c_invalid_arg

c_null_err

c_setter_simple

generate_ic_option_accessors

generate_ode_option_accessors

generate_option_accessors

generate_trait_ic_option_accessors

generate_trait_ode_option_accessors

option_value_from_store

option_value_to_store