forked from 1b-agent/fieldcraft-upstream
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:
1 parent
417c0c8897
commit
944a54c76b
4 files changed
+242
-43
No files matched your search
@@ -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())),
|
||||
},
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user