DiCE Reaction is the first library in DiCE — Differentiable Chemical Engineering. It is a Rust-first reaction-kinetics engine designed around explicit scientific semantics, differentiable model evaluation, reproducible simulation, parameter estimation, and uncertainty analysis.
The current implementation includes differentiable simulation, global fitting, domain kinetics, reactor foundations, and scientific analysis:
- a compact textual reaction DSL;
- immutable, validated reaction models;
- irreversible and reversible reaction syntax;
- elementary mass-action and differentiable custom rate expressions;
- unit-declared, dependency-checked named derived quantities and pseudo-compounds plus unit-preserving temperature, pressure, flow, and other specified/interpolated per-experiment inputs shared by kinetics, fitting, reports, and reactor metrics;
- runtime dimensional analysis and SI normalization;
- isothermal, constant-volume batch simulation;
- BDF, ESDIRK34, and Tsitouras 4/5 integration through a backend-neutral API;
- exact forward sensitivities and arbitrary state/rate observables;
- missing observations, replicates, and five built-in error models;
- REX-compatible automatic/custom measurement weighting and strict multiphase experimental atom/carbon balance diagnostics;
- positive, bounded, fixed, linked, and scaled parameter coordinates;
- residual-aware dogleg and general scalar trust-region optimization;
- restartable global fits across several experiments;
- reference-scaled Arrhenius, Eyring, and arbitrary normalized power laws;
- covariance, correlation, Fisher/SVD identifiability, profiles, contours, and bootstrap;
- separate mean-response confidence and new-observation prediction bands;
- enzyme reduced laws, thermodynamic consistency, surface sites, adsorption, LHHW, and an index-1 DAE model contract;
- variable-volume well-mixed reactors, CSTRs, PFRs, energy balances, recycle, reactor metrics, transport blocks, integrated reaction traffic, and exact target-specific local rate-control analysis;
- phase density/volume packages, NRTL and Margules liquids, differentiable Peng--Robinson fugacity/volume, nonideal equilibrium flash, Ergun pressure drop, coupled surface packed-bed DAEs, dynamic multiphase/membrane composition, thermodynamic flow-sheet closures, dynamic PI control, and unit-aware piecewise-constant/linear open-loop control profiles with exact event sensitivities, and general flow-sheet solves;
- Fisher-information design criteria, constrained static and dynamic-profile operating optimization, runnable batch, well-mixed, PFR, packed-bed, steady-CSTR, and flow-sheet design templates, exact continuous sampling and inlet-state information derivatives using dual/hyper-dual local products, typed seeded virtual experiments and ordered multi-case simulation, synthetic/refit workflows, exact-gradient bounded dynamic control optimization, sparse colored derivatives, preconditioned steady solves, sparse-direct BDF/ESDIRK ODE/DAE integration with explicit fallback provenance, terminal/running reactor adjoints with fixed and parameter-dependent event jumps and validated index-1 DAE transpose-mass semantics, parallel CPU ensembles, and an optional checked CubeCL boundary kernel;
- versioned typed projects with executable coverage for every reactor class and named fit, uncertainty, and design workflows across Rust, CLI, Python, and desktop adapters, tidy CSV import, an explicit SBML profile, and initial Python bindings;
- a portable, searchable, versioned local mechanism library plus stable-ID project diffs and common-data competing-fit comparison;
- typed library errors with contextual CLI reporting.
Sparse policies, provenance, boundaries, and the reproducible crossover measurement are documented in docs/SPARSE_BACKENDS.md.
The remaining path through multi-reactor design adapters, scale/acceleration, application and interchange completion, and stable REX-class coverage is tracked in the roadmap, detailed implementation plan, and capability matrix. The public compatibility target and evidence rules are in the REX parity plan. Typed multi-reactor project replay is documented in PROJECT_REACTORS.md. Runnable information-design APIs are documented in DESIGN_WORKFLOWS.md. Exact-gradient static and dynamic operating objectives are documented in OPERATING_OPTIMIZATION.md. Deterministic design and optimization decision reports are documented in REPORTS.md. Typed project and CLI decision replay is documented in PROJECT_DECISIONS.md. Unit-preserving fit, uncertainty, and design replay is documented in PROJECT_WORKFLOWS.md. The exact conservative interchange boundary is documented in the SBML profile. Python artifact scope and local validation are recorded in PYTHON_PACKAGING.md. Built-in nonideal model equations, smoothness semantics, and limits are recorded in THERMODYNAMIC_MODELS.md. The pinned public REX baseline and requirement-level parity evidence are in REX_PARITY_EVIDENCE.md. Named expression, pseudo-compound, conservation, and reactor-metric semantics are documented in NAMED_QUANTITIES.md. Portable mechanism catalogs and rigorous structural/fit comparison are documented in LIBRARY_AND_COMPARISON.md. The frozen v1 Rust, schema, MSRV, error, deprecation, and semver contract is in API_STABILITY.md. Deterministic tagged release construction and verification are documented in RELEASING.md. The v1 artifact and reproducibility audit is recorded in RELEASE_EVIDENCE.md.
cargo run -p dice-reaction-cli -- validate examples/decay/model.dice
cargo run -p dice-reaction-cli -- simulate examples/decay/model.dice \
--initial A=1mol --initial B=0mol --volume 1L --temperature 298.15K \
--times 0,1,2,3,4,5
cargo run -p dice-reaction-cli -- fit \
examples/global-fit/model.dice examples/global-fit/fit.json
cargo run -p dice-reaction --example reactor_workflows
cargo run -p dice-reaction --example flowsheet_workflows
cargo run -p dice-reaction-gui
cargo run -p dice-reaction-cli -- project dice-reaction-project.json --json
cargo run -p dice-reaction-cli -- project dice-reaction-project.json \
--workflow fit --json
cargo run -p dice-reaction-cli -- library create mechanisms.json \
--name "My mechanisms"
cargo run -p dice-reaction-cli -- compare projects baseline.json candidate.jsonThe project is dual-licensed under MIT or Apache-2.0.
The Rust API mirrors the DSL and keeps validation at explicit boundaries:
use dice_reaction::{BatchExperiment, Simulator};
use dice_reaction::core::{ModelDraft, Parameter, Reaction, Species};
# fn example() -> Result<(), Box<dyn std::error::Error>> {
let model = ModelDraft::builder()
.species(Species::builder("A").build()?)
.species(Species::builder("B").build()?)
.parameter(Parameter::builder("k").value(0.5, "1/s").build()?)
.reaction(
Reaction::builder("decay")
.reactant("A", 1)
.product("B", 1)
.mass_action("k")
.build()?,
)
.build()
.compile()?;
let experiment = BatchExperiment::builder("run_1")
.volume(1.0, "L")
.temperature(298.15, "K")
.initial_amount("A", 1.0, "mol")
.initial_amount("B", 0.0, "mol")
.times([0.0, 1.0, 2.0], "s")
.build(&model)?;
let trajectory = Simulator::new(&model).simulate(&experiment)?;
# assert_eq!(trajectory.times().len(), 3);
# Ok(())
# }Library crates expose typed thiserror errors. The CLI uses anyhow only at
the application boundary to add file, command, and operation context.