oxiflow

Generic numerical engine for transport–reaction–diffusion problems.

oxiflow provides the architectural building blocks to construct rigorous, maintainable and performant PDE solvers in Rust — from simple 1D chromatography models to complex multi-physics coupled systems. It is designed from the ground up to support structured grids (v1.0), unstructured finite element meshes (v2.0), and a family of domain-specific frameworks (v3.0).

Architecture

oxiflow is structured as an engine + niche frameworks:

oxiflow              (engine — fields, fluxes, meshes, couplings, solvers)
├── oxiflow-chrom    (chromatography framework)
├── oxiflow-geo      (surface geophysics framework)
├── oxiflow-thermo   (heat transfer framework)
├── oxiflow-em       (diffusive electromagnetism framework)
└── ...              (third-party frameworks on crates.io)

Each framework is an independent crate that depends on the engine and provides domain-specific models, boundary conditions, nomenclature and declarative configuration. Third parties can publish their own oxiflow-* frameworks on crates.io using the same plugin API — the engine exposes stable, object-safe extension points for exactly this purpose.

Engine Features

• Generic context system — ContextValue supports scalars, vectors, matrices and 2D fields; no more f64-only bottlenecks
• Type-safe dependency declaration — models declare what they need via RequiresContext; missing calculators are caught before the solver runs
• Multi-component systems — indexed PhysicalQuantity handles N-solute problems, competitive adsorption, thermal coupling and more
• Multi-domain coupling — CouplingOperator connects distinct physical domains across moving interfaces (gravitational flows, fluid–solid interaction, ...)
• Abstract spatial operators — DiscreteOperator decouples solvers from discretisation schemes; FD, FV and (in v2.0) FEM plug in without rewriting integrators
• Abstract mesh — Mesh trait keeps PhysicalState free of grid assumptions; UniformGrid1D in v1.0, unstructured triangular meshes in v2.0
• Rich integrator library — Forward Euler, RK4, Dormand–Prince 4/5, Backward Euler, Crank–Nicolson, BDF2/3, IMEX (Strang splitting)
• Spatial schemes — upwind/centred FD, WENO3/5, conservative FV, Lax–Wendroff, flux limiters (MinMod, Van Leer, Superbee)
• Plugin-safe API — all public traits are object-safe, enabling third-party niche frameworks to extend the engine without touching its internals (v2.0 — INV-4)
• Optional parallelism — Rayon-based, opt-in via parallel feature flag

Quick Start

[dependencies]
oxiflow = "0.2"
# oxiflow-chrom = "3.0"    # chromatography framework (available from v3.0)

A minimal transport–diffusion model using the engine directly:

use oxiflow::prelude::*;

struct DiffusionModel { diffusivity: f64 }

impl PhysicalModel for DiffusionModel {
    fn compute(&self, state: &PhysicalState, ctx: &ComputeContext)
        -> Result<PhysicalState, OxiflowError>
    {
        let u     = ctx.vector(ContextVariable::Concentration)?;
        let lap_u = ctx.vector(ContextVariable::Laplacian)?;
        Ok(state.update(u + self.diffusivity * lap_u * ctx.time_step()?))
    }
}

impl RequiresContext for DiffusionModel {
    fn required_variables(&self) -> Vec<ContextVariable> {
        vec![
            ContextVariable::Concentration,
            ContextVariable::Laplacian,
            ContextVariable::TimeStep,
        ]
    }
}

fn main() -> Result<(), OxiflowError> {
    let result = Scenario::builder()
        .mesh(UniformGrid1D::new(100, 0.0, 1.0))
        .model(DiffusionModel { diffusivity: 1e-3 })
        .integrator(CrankNicolson::default())
        .time_span(0.0, 10.0)
        .dt(0.01)
        .build()?
        .solve()?;

    println!("{:?}", result.state());
    Ok(())
}

Note: The API above reflects the v0.2 target — see Development Status.

Covered Domains

The engine is domain-agnostic. Any problem of the canonical form ∂u/∂t + ∇·F(u, ∇u) = S(u, x, t) is a candidate:

Design Invariants

Four constraints guarantee a non-breaking evolution from v1.0 to v3.0, and ensure that third-party frameworks remain compatible across engine versions:

Development Status

See DEVELOPMENT.md for the full architectural specification.

Feature Flags

Contributing

Contributions are welcome at every milestone — bug fixes, new features (after discussion), documentation, benchmarks, tests, and niche framework development.

Building a framework on oxiflow? Open a GitHub Discussion before publishing so it can be listed in the official ecosystem documentation. Third-party oxiflow-* crates are explicitly encouraged — the engine plugin API (INV-4) is designed for exactly this.

Read CONTRIBUTING.md before submitting a pull request. Coverage is tracked on Codecov: target ≥ 85% overall, ≥ 90% on INV components.

License

Copyright 2026 [ton nom]

Licensed under the Apache License, Version 2.0.

You may use, distribute and modify this software freely, including for commercial purposes, provided you retain the copyright notice and the NOTICE file in any redistribution. The license includes a patent retaliation clause protecting the author — see the full text for details.