//! 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), and the /// temperature (model units) when the flow carries heat (empty otherwise). #[derive(Debug, Clone, PartialEq)] pub struct Fields { pub density: Vec, pub velocity: Vec<[f64; 3]>, pub temperature: Vec, } /// A stepper of one prepared flow. pub trait Backend { /// What steps the flow, for reports: `cpu`, `gpu: `. 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; /// The total mass of the fluid cells (the sum of every population). fn mass(&mut self) -> Result; /// The momentum each force group received in the last step (lattice units: force per step). fn forces(&mut self) -> Result>; /// The heat each force group received in the last step (lattice units: temperature times /// cell faces per step); empty without heat. fn heat(&mut self) -> Result>; 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> + Send + Sync; static FACTORY: OnceLock> = 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) { 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 { 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> { 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())), }, } }