odelia: ODE solver with automatic differentiation, in C++ header files

odelia is an ODE solver implemented in C++ header files, with an interface to R via Rcpp. Three adaptive steppers (Cash-Karp RK4(5), Dormand-Prince 5(4), and RODAS4(3) for stiff systems) run entirely in compiled code, so it is fast. ODE systems are templated on their scalar type, so a run can be recorded and differentiated in reverse mode: one sweep over the recorded run gives the exact derivative of a solution with respect to every parameter and initial condition at once, for optimisation and calibration.

The core solver was first developed by Rich FitzJohn as part of the plant package. This package spins that code out so it can be used more widely.

Features

Installation

odelia compiles C++ from source, so you need a working C++ toolchain (Rtools on Windows, Xcode command-line tools on macOS, a recent g++/clang on Linux). Then:

# install.packages("remotes")
# remotes::install_github("traitecoevo/odelia")
install.packages("odelia", repos = c('https://traitecoevo.r-universe.dev', 'https://cloud.r-project.org'))

Quick start

odelia ships with one ready-to-run system, the classic Lorenz system, so you can try the solver out of the box. It is bundled purely as a demonstration — to model your own problem you write a small C++ system class (and a thin Rcpp/R6 interface) that the same solver then drives. See Building your own model for a complete worked example.

The example below solves the bundled Lorenz system. (A right-hand side written in R can be solved without any C++ at all; see ode_solve() and vignette("odelia").)

library(odelia)

# Define the system (parameters) and its initial state
lz <- LorenzSystem$new(sigma = 10, R = 28, b = 8 / 3)
lz$set_state(c(1, 1, 1))   # autonomous system, so no time needed

# Solver control settings (tolerances, step sizes) use sensible defaults
ctrl <- OdeControl$new()

# Build a solver (a "runner") and advance with adaptive stepping
runner <- Lorenz_Solver$new(lz$ptr, ctrl$ptr)
runner$advance_adaptive(seq(0, 100, by = 0.01))

# Collect output as a tibble
out <- runner$history()

For more, see the vignettes (also rendered on the package website):

And the worked examples:

From C++

A System is a class templated on its scalar type that holds parameters and state and knows its rates. The solver drives it:

// [[Rcpp::plugins(cpp20)]]   (or CXX_STD = CXX20 in a package's Makevars)
#include <odelia/ode_solver.hpp>
#include <examples/lorenz_system.hpp>   // the shipped example System

LorenzSystem<double> system(10.0, 28.0, 8.0 / 3.0);
odelia::ode::Solver<LorenzSystem<double>> s(system, odelia::ode::OdeControl());
s.advance_adaptive({0.0, 10.0});
std::vector<double> y = s.state();

A gradient of that run is three more lines: keep the record, set the output's adjoint wanted, and sweep.

s.set_keep_states(true);                       // before the run
s.advance_adaptive({0.0, 10.0});
auto lambda = odelia::ode::adjoint_batch::one({1.0, 0.0, 0.0});   // d x(10)
odelia::ode::adjoint_batch dp(1, 3);            // one per output, zeroed
s.sweep_adjoint(lambda, dp);                   // dp[0][j] = d x(10) / d parameter j

A package that uses the headers adds odelia to LinkingTo and Imports, compiles as C++20 with -DXAD_NO_THREADLOCAL -DXAD_USE_STRONG_INLINE, and on Windows links against odelia's DLL; ARCHITECTURE.md has the details and a map of the headers. inst/include/examples/lorenz_system.hpp is the template for a System of your own, with its members marked by which contract they serve; the article Building your own model walks through one with external drivers.

Parameter fitting with automatic differentiation

The shipped Lorenz and leaf-thermal runners expose a $loss_and_gradient() method that returns the least-squares loss against a target trajectory and its exact gradient with respect to the parameters (and initial conditions), by one reverse sweep over a replay of the reference run. Hand it to a gradient-based optimiser such as optim():

fit_runner <- Lorenz_Solver$new(lz$ptr, ctrl$ptr)
fit_runner$set_target(times, target_vals, obs_index)

res <- fit_runner$loss_and_gradient(params = c(sigma = 12, R = 30, b = 3))
res$loss      # scalar mismatch with the target trajectory
res$gradient  # exact gradient w.r.t. each parameter

A complete optimisation workflow (recovering known Lorenz parameters) is walked through in vignette("parameter-fitting"). A runner for your own System gets $loss_and_gradient() by instantiating Solver_loss_and_gradient_impl from solver_interface.hpp, as the leaf-thermal example does.

Vocabulary

odelia is organised around a few core abstractions:

License

This package is released under the GNU Affero General Public License v3 (AGPL-3). The vendored XAD library retains its own license; see inst/include/XAD/LICENSE.md.

Contributing

Contributions are welcome. By submitting a pull request or code to this repository, you agree to the terms of the Contributor License Agreement.

Linking from another package? If you LinkingTo: odelia and instantiate Solver, read ARCHITECTURE.md — it documents how the compiled XAD Tape symbols are resolved per platform, what your package must do, and the invariants that must not be broken.

ODE System Structure

An ODE system in odelia consists of:

Testing

make test

Installs the package with its tests and runs the full suite against the installed copy. The AD and DLL-lifecycle tests need an installed package.

make test-local

The fast development loop: testthat::test_local() via load_all(), skipping those tests.

make test-cpp

Builds and runs the solver core as plain C++ with no R on the include path (tests/standalone/), and compiles every core header on its own. Anything compiled against the headers outside the package's own src/ needs C++20 and -DXAD_NO_THREADLOCAL -DXAD_USE_STRONG_INLINE, matching src/Makevars.

Plant family

odelia is part of the plant family of packages in the traitecoevo org, built around the plant forest model. Docs hub: https://traitecoevo.github.io/overstorey/.

Contributing: please skim the family issue guide before filing — issues across the family are triaged on board #5, and cross-package context lives in plant-meta.