lbm: a Backend trait steps the flow, with the CPU scheme as its reference

run() drives a Backend in chunks of steps (to the next frame, history sample
or progress check) instead of the CPU Flow directly, so a device backend
registered by an application can step the same prepared flow: Flow keeps
building the grid, links and open cells and exposes them read-only, and
implements the trait itself. solve_fluid_on picks the CPU or the registered
device backend; solve_fluid stays the CPU and is unchanged in its results.

Part of #529.
This commit is contained in:
Christian Svensson authored and Irakli Kourtis committed 2026-10-17 07:23:40 -04:00
1 parent 417c0c8897
commit 944a54c76b
4 files changed
+242 -43

No files matched your search

+91
View File
@@ -0,0 +1,91 @@
//! What steps a prepared flow: the CPU scheme in [`crate::flow::Flow`], or a device backend an
//! application registers (a GPU crate above this layer implements the trait and hands a factory
//! to [`register_backend`]; `solve.fluid` picks it when asked). Every backend takes its grid,
//! links and open cells from the [`Flow`] that prepared them, so voxelisation and every boundary
//! rule exist once, here.
//!
//! The CPU result is the reference: a device backend is deterministic on its device and agrees
//! with the CPU within a stated tolerance (its tests say which).
use std::sync::OnceLock;
use crate::flow::{Flow, Group};
use crate::setup::Setup;
use crate::{Error, Result};
/// The density and velocity of every cell (lattice units; zero in solid cells).
#[derive(Debug, Clone, PartialEq)]
pub struct Fields {
pub density: Vec<f64>,
pub velocity: Vec<[f64; 3]>,
}
/// A stepper of one prepared flow.
pub trait Backend {
/// What steps the flow, for reports: `cpu`, `gpu: <adapter>`.
fn name(&self) -> String;
/// Advance `steps` time steps. Fails with [`Error::Unstable`] when a density stops being a
/// positive number or a lattice speed exceeds [`crate::setup::MAX_LATTICE_SPEED`] (a device
/// backend may notice at the end of the chunk rather than the step).
fn advance(&mut self, steps: u64) -> Result<()>;
fn steps_done(&self) -> u64;
/// The density and velocity (with the half force) of every cell.
fn fields(&mut self) -> Result<Fields>;
/// The total mass of the fluid cells (the sum of every population).
fn mass(&mut self) -> Result<f64>;
/// The momentum each force group received in the last step (lattice units: force per step).
fn forces(&mut self) -> Result<Vec<[f64; 3]>>;
fn groups(&self) -> &[Group];
fn fluid_cells(&self) -> usize;
fn is_fluid(&self, cell: usize) -> bool;
/// Obstacles that cover no cell centre.
fn empty_obstacles(&self) -> &[String];
}
/// Makes a device backend from a prepared flow (its initial state included) and its setup.
pub type BackendFactory = dyn Fn(&Flow, &Setup) -> Result<Box<dyn Backend>> + Send + Sync;
static FACTORY: OnceLock<Box<BackendFactory>> = OnceLock::new();
/// Register the process's device backend (an application does this once at start; a second
/// registration is ignored).
pub fn register_backend(factory: Box<BackendFactory>) {
let _ = FACTORY.set(factory);
}
/// The registered device backend's factory, if an application registered one.
pub fn backend_factory() -> Option<&'static BackendFactory> {
FACTORY.get().map(|b| b.as_ref())
}
/// Which backend a solve asks for.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Choice {
/// The CPU scheme: the reference, bit for bit reproducible.
#[default]
Cpu,
/// The registered device backend; an error when none is registered.
Device,
}
impl Choice {
/// `cpu` or `gpu`, exactly.
pub fn parse(s: &str) -> Option<Choice> {
match s {
"cpu" => Some(Choice::Cpu),
"gpu" => Some(Choice::Device),
_ => None,
}
}
}
/// The backend `choice` names for `flow`.
pub fn backend(choice: Choice, flow: Flow, setup: &Setup) -> Result<Box<dyn Backend>> {
match choice {
Choice::Cpu => Ok(Box::new(flow)),
Choice::Device => match backend_factory() {
Some(make) => make(&flow, setup),
None => Err(Error::Invalid("no GPU backend is available in this build: solve on the CPU (`backend: \"cpu\"`)".into())),
},
}
}