diffsol-c 0.8.0

A diffsol wrapper featuring runtime scalar/matrix/solver types and a C API
Documentation

diffsol-c

A runtime-typed wrapper and C API around diffsol.

Where the diffsol crate selects its scalar, matrix, and solver types at compile time via generics, diffsol-c exposes them as runtime choices behind a C-compatible interface, making diffsol usable from C and other languages via FFI.

The crate is built as a C dynamic library and a Rust library (crate-type = ["cdylib", "rlib"]). A C static library is made on request (see below).

What's in this crate

  • Runtime selection of scalar / matrix / linear-solver / ODE-solver types.
  • A C API for building and solving ODE/DAE problems.
  • Integration with the DiffSL DSL for specifying equations.

Features

  • diffsl-cranelift: DiffSL with the Cranelift JIT backend.
  • diffsl-llvm15 … diffsl-llvm21: DiffSL with the corresponding LLVM backend, linked statically.
  • diffsl-llvm15-prefer-dynamic … diffsl-llvm21-prefer-dynamic: the same, but link the shared LLVM library (libLLVM) if it is available.
  • diffsl-external-f64 / diffsl-external-f32 / diffsl-external-dynamic: externally compiled DiffSL modules.
  • suitesparse: enable the KLU sparse direct solver (via diffsol/suitesparse).
  • wasm: WebAssembly support.

Use from C

On Debian 12+ and Ubuntu 22.04+, you can install the library as Debian packages (libdiffsol<version> and libdiffsol-dev, which install the library as libdiffsol.so). See the book chapter The C API. The packaging is in debian/.

To build the library yourself:

A build of this crate makes these files in target/<profile>:

  • The dynamic library: libdiffsol_c.so (Linux), libdiffsol_c.dylib (macOS), or diffsol_c.dll with the import library diffsol_c.dll.lib (Windows).
  • include/diffsol.h: the C header. The build script makes it with cbindgen. The header agrees with the features of the build. It defines a macro for each enabled feature, for example DIFFSOL_DIFFSL_CRANELIFT.

Link with the dynamic library:

cargo build -p diffsol-c --release --features diffsl-cranelift
cc main.c -I target/release/include -L target/release -ldiffsol_c -lm \
   -Wl,-rpath,target/release -o main

Or make and link the static library libdiffsol_c.a (diffsol_c.lib on Windows). Then also link the system libraries that the static library needs. This command makes the static library, and lists the system libraries for your platform and features:

cargo rustc -p diffsol-c --release --lib --features diffsl-cranelift --crate-type staticlib \
    -- --print native-static-libs

For example, on macOS:

cc main.c -I target/release/include target/release/libdiffsol_c.a -lc++ -liconv -lm -o main

The book chapter The C API gives more details. The directory examples/c has two examples, and the script examples/c/run_examples.sh, which compiles and runs them against a Cargo build. From the root of the workspace: crates/diffsol-c/examples/c/run_examples.sh target/debug. The CI runs it on Linux, macOS and Windows.

  • logistic_callbacks.c: give the equations as C callbacks (diffsol_ode_new_callbacks_f64).
  • logistic_diffsl_jit.c: give the equations as DiffSL code, which the library compiles at run time (diffsol_ode_new_jit). This needs a JIT backend feature.

Links

License

Licensed under the MIT license. See the repository for details.