semiflow

Status: beta (0.15.0-beta). The API is stabilising toward 1.0; minor versions may still make breaking changes. Bug reports and feedback are welcome.

SemiFlow solves evolution equations ∂ₜu = Lu (heat, diffusion, Schrödinger, graph and manifold PDEs, …) by Chernoff approximation of operator semigroups: no matrix exponentials, no linear solves, a flat memory footprint. The core is a no_std + alloc Rust library with 3 runtime dependencies (num-traits, libm, num-complex); the same engines are available from Python, JavaScript/WebAssembly and C.

The method evaluates e^{tL}f by iterating an explicit step operator S(τ): (S(t/n))ⁿ f → e^{tL} f as n → ∞. Each step is an explicit stencil over a Vec-backed grid with reused scratch buffers, so steady-state evolution does not allocate.

Mathematical foundation: Theorem 6 of I. D. Remizov (2025), Vladikavkaz Math. J. 27(4), 124–135 (doi:10.46698/a3908-1212-5385-q).

Honest performance note. The primary measured advantage is memory frugality: a flat ~3 MB working set across the 1D/2D/3D families versus 50–418 MB for heavy frameworks. Wall-clock speed is not a general strength — for matched-accuracy PDE solving SemiFlow is slower than adaptive ODE solvers and spectral methods, and parallelism pays off only on large 3D grids. Two measured niches: tail-latency-sensitive pricing (Diffusion4thChernoff ≈ 41 ns p99.9 per tick) and L1-resident low-rank carriers (TtChernoff, ReverseChernoff). Treat memory and latency as measured properties of the concrete grid types, not guarantees of the traits. The 2026-10 overhaul (docs/perf/overhaul-v0_15.md) made the grid engines 2.6–39× faster bit-for-bit, the stiff Chebyshev graph action O(√(λt)) instead of O(λt) (559× on issue #16), ETDRK4 2.1× and the general Taylor action 2.1× faster; Richardson extrapolation (richardson=) raises any engine's order by levels − 1. Head-to-head comparisons quoted in the user guide predate it.

Install

[dependencies]
semiflow = "0.15.0-beta"

MSRV: Rust 1.81. The default build is #![no_std] + alloc with AVX2/NEON kernels (feature simd, scalar lanes elsewhere); std is needed only for parallel. See below.

Quickstart

Solve ∂ₜu = ½·∂ₓₓu from u₀(x) = e^{-x²} to t = 1 and compare with the closed-form solution u(1,x) = 3^{-1/2}·e^{-x²/3}:

use semiflow::{ChernoffSemigroup, DiffusionChernoff, Grid1D, GridFn1D, State};

let grid = Grid1D::new(-10.0, 10.0, 1000).expect("valid grid");
let u0 = GridFn1D::from_fn(grid, |x| (-x * x).exp());

// L = a(x)·∂²ₓ with a ≡ ½ (a' = a'' = 0), bound ‖a‖ = ½.
let diffusion = DiffusionChernoff::new(|_| 0.5_f64, |_| 0.0, |_| 0.0, 0.5, grid);
let semigroup = ChernoffSemigroup::new(diffusion, 100).expect("n >= 1");
let u1 = semigroup.evolve(1.0, &u0).expect("evolve");

let exact = GridFn1D::from_fn(grid, |x| (-x * x / 3.0).exp() / 3.0_f64.sqrt());
let mut err = u1.clone();
err.axpy(-1.0, &exact);
assert!(err.norm_sup() < 1e-5, "sup-norm error {}", err.norm_sup());

More: Quickstart, User Guide and the runnable examples (cargo run -p semiflow --example heat_2d_demo).

no_std

[dependencies]
semiflow = "0.15.0-beta"   # no_std + alloc, SIMD kernels

The crate is #![no_std] by default and needs only alloc; the std feature is needed only for parallel. What that means in practice:

• Your binary provides a #[global_allocator] and a #[panic_handler], as for any no_std + alloc program (a std program already has both).
• The target needs pointer-sized atomics (the engines share coefficient closures through alloc::sync::Arc): Cortex-M3/M4/M7/M33, RISC-V with the a extension, x86_64-unknown-none and similar work; thumbv6m does not.
• SemiflowError implements Debug, Display and core::error::Error (the same trait as std::error::Error) in every build.
• f32/f64 transcendentals come from the pure-Rust libm in every build, and the SIMD kernels use the same lane arithmetic with or without intrinsics, so std, no_std, simd and non-simd builds give bit-identical results on every CPU.
• simd works without std (the intrinsics come from core::arch); parallel requires std.

This is verified on every pull request, not just type-checked:

Feature flags

Engine catalogue

1D Chernoff functions

Compositions

2D tensor-product

3D tensor-product

Adaptive

Boundary conditions

Resolvent and nonautonomous

Riemannian manifold

High-dimensional and sparse-grid

Matrix-valued operators

Quantum graphs

Reverse-mode AD

Scope: constant-a DiffusionChernoff<F> only. Multi-parameter (K>1) sensitivity via ReverseChernoff::with_region_map. Variable-coefficient kernels are deferred.

Tensor-train carrier

Scope: linear diagonal-A Gaussian class (TtChernoff); separable diagonal variable coefficients (VarCoefTt). Non-separable variable coefficients and off-diagonal A are research-track. VarCoefTt::new returns SemiflowError::VarCoefOutOfClass when inputs fall outside the separable diagonal class.

Gridless / particle-ensemble

Schrödinger, graph and quantum-graph operators

Conservative, stiff and semilinear problems

Executor

ChernoffSemigroup<C, S> — wraps a ChernoffFunction and a step count; call .evolve(t, &f) to compute (S(t/n))ⁿ f.

Examples

cargo run -p semiflow --example heat_2d_demo

Bindings

The bindings mirror the user-facing engines, not the internal composition types (AxisLift, StrangSplit, … are Rust-side building blocks). Variable coefficients cross the language boundary as pre-sampled arrays (evaluated in Rust, no call back into the host language during evolve); some classes also accept a host-language callback (e.g. Heat1D.with_a_function in Python, Heat1D.withAFunction in JS, smf_state_new_with_closure in C). The Bindings guide has side-by-side examples.

Documentation

Accuracy and design

Every numerical claim is gated in CI against a closed-form or high-order reference oracle (convergence-order and sup-norm tests). Design principles: no_std + alloc core; 3 runtime dependencies; SIMD hot paths isolated to src/simd/ (AVX2 on x86_64, NEON on aarch64, scalar fallback elsewhere); bit-reproducible parallelism across thread counts; no unsafe in the math kernels. Builds with and without simd agree to rounding but not always bit for bit, so golden files are tied to one configuration.

How to cite

If you use SemiFlow in academic work, cite both the software and the theorem.

@software{volkov2026semiflow,
  author  = {Volkov, Ilia},
  title   = {{SemiFlow}: {Chernoff} Approximation of Operator Semigroups},
  year    = {2026},
  version = {0.15.0-beta},
  doi     = {10.5281/zenodo.20837851},
  url     = {https://doi.org/10.5281/zenodo.20837851}
}

@article{Remizov2025,
  author  = {I. D. Remizov},
  title   = {Chernoff Approximations of the Solution of Linear ODE with Variable Coefficients},
  journal = {Vladikavkaz Math. J.},
  volume  = {27},
  number  = {4},
  pages   = {124--135},
  year    = {2025},
  doi     = {10.46698/a3908-1212-5385-q}
}

The concept DOI 10.5281/zenodo.20837851 always resolves to the latest version; CITATION.cff has the full entry (GitHub's "Cite this repository" reads it).

License

Dual-licensed under MIT or Apache-2.0, at your option.

Author, contributing, security

SemiFlow is created and maintained by Ilia Volkov. See CONTRIBUTING.md and CODE_OF_CONDUCT.md. Report vulnerabilities privately as described in SECURITY.md — not in public issues.