Skip to main content

tpt_sci_cfd_core/
lib.rs

1//! # tpt-sci-cfd-core
2//!
3//! A small, dependency-light **incompressible Navier–Stokes** solver built from
4//! scratch (no wrapped engine — `pravash` was audited and rejected, GPL-3.0-only)
5//! using a **collocated finite-volume** discretization on a uniform staggered
6//! grid with a fractional-step (Chorin) pressure projection.
7//!
8//! It provides the foundation that the biomedical/earth-science crates
9//! (`tpt-sci-hemodynamics`, `tpt-sci-ocean`) build on. The core pieces:
10//!
11//! * A [`CollocatedGrid`] uniform grid with cell-centred velocity storage.
12//! * An explicit advection–diffusion update [`Step::momentum`] plus a pressure
13//!   Poisson projection [`Step::project`] that enforces `∇·u = 0` (the
14//!   fractional-step scheme).
15//! * Optional algebraic [`turbulence::eddy_viscosity`] (Smagorinsky) and a full
16//!   two-equation [`komega_sst::KOmegaSst`] Menter SST closure.
17//! * An implicit [`simple::SimpleSolver`] pressure-correction (SIMPLE/PISO
18//!   style) that solves the pressure Poisson equation with the sparse
19//!   conjugate-gradient solver from `tpt-sci-grid` and corrects the velocity.
20//! * An additive [`unstructured::UnstructuredMesh`] finite-volume path
21//!   (triangular cells in 2-D) with a gradient/reconstruction helper and a
22//!   diffusion + upwind-advection residual assembly that can solve a steady
23//!   Laplace/Poisson problem converging to the analytic solution.
24//!
25//! The structured explicit `Step` and algebraic turbulence model remain the
26//! teaching / coupling primitive; the three additions above close the v1
27//! "out of scope" items.
28//!
29//! # Example
30//!
31//! ```
32//! use tpt_sci_cfd_core::{CollocatedGrid, Step, Boundary};
33//! use tpt_math_linalg::tpt_math_linalg_dense::DVector;
34//!
35//! // 32×32 cavity, lid moving at u = 1.0 on the top wall.
36//! let grid = CollocatedGrid::new(32, 32, 1.0, 1.0).unwrap();
37//! let mut step = Step::new(grid, 1e-2, 0.01, 1.0);
38//! step.set_boundary(Boundary::Top, 1.0);
39//! // One fractional-step update (advect/diffuse + project).
40//! let ok = step.advance();
41//! assert!(ok);
42//! ```
43#![forbid(unsafe_code)]
44
45mod error;
46pub mod komega_sst;
47pub mod scalar;
48pub mod simple;
49pub mod turbulence;
50pub mod unstructured;
51
52pub use error::CfdError;
53pub use komega_sst::KOmegaSst;
54pub use scalar::ScalarTransport;
55pub use simple::SimpleSolver;
56pub use unstructured::{Face, UnstructuredMesh};
57
58/// A uniform 2-D collocated grid of `nx × ny` cells, physical size
59/// `lx × ly`. Velocities `u`, `v` are stored cell-centred.
60#[derive(Debug, Clone)]
61pub struct CollocatedGrid {
62    /// Cells in `x`.
63    pub nx: usize,
64    /// Cells in `y`.
65    pub ny: usize,
66    /// Physical length in `x`.
67    pub lx: f64,
68    /// Physical length in `y`.
69    pub ly: f64,
70    /// Cell spacing `Δx`.
71    pub dx: f64,
72    /// Cell spacing `Δy`.
73    pub dy: f64,
74}
75
76impl CollocatedGrid {
77    /// Construct a validated uniform grid.
78    ///
79    /// # Errors
80    ///
81    /// Returns [`CfdError::InvalidGrid`] if any dimension/cell count is
82    /// non-positive.
83    pub fn new(nx: usize, ny: usize, lx: f64, ly: f64) -> Result<Self, CfdError> {
84        if nx == 0 || ny == 0 {
85            return Err(CfdError::InvalidGrid("cell counts must be > 0".into()));
86        }
87        if lx <= 0.0 || ly <= 0.0 {
88            return Err(CfdError::InvalidGrid("domain lengths must be > 0".into()));
89        }
90        Ok(Self {
91            nx,
92            ny,
93            lx,
94            ly,
95            dx: lx / nx as f64,
96            dy: ly / ny as f64,
97        })
98    }
99
100    /// Total number of cells.
101    #[must_use]
102    pub fn len(&self) -> usize {
103        self.nx * self.ny
104    }
105
106    /// Returns `true` if the grid has zero cells.
107    #[must_use]
108    pub fn is_empty(&self) -> bool {
109        self.nx == 0 || self.ny == 0
110    }
111
112    /// Linear index of cell `(i, j)`.
113    #[must_use]
114    pub fn idx(&self, i: usize, j: usize) -> usize {
115        j * self.nx + i
116    }
117}
118
119/// Boundary walls of the rectangular domain.
120#[derive(Debug, Clone, Copy, PartialEq, Eq)]
121pub enum Boundary {
122    /// `y = ly` (top).
123    Top,
124    /// `y = 0` (bottom).
125    Bottom,
126    /// `x = lx` (right).
127    Right,
128    /// `x = 0` (left).
129    Left,
130}
131
132/// One fractional-step of the incompressible Navier–Stokes solver on a
133/// collocated grid.
134#[derive(Debug, Clone)]
135pub struct Step {
136    grid: CollocatedGrid,
137    /// `x`-velocity, length `nx·ny`.
138    pub u: Vec<f64>,
139    /// `y`-velocity, length `nx·ny`.
140    pub v: Vec<f64>,
141    /// Pressure, length `nx·ny`.
142    pub p: Vec<f64>,
143    /// Kinematic viscosity `ν`.
144    nu: f64,
145    /// Timestep `dt`.
146    dt: f64,
147    /// Prescribed wall tangential velocities.
148    walls: [f64; 4],
149}
150
151impl Step {
152    /// Construct a solver with zero velocity and the given `ν`/`dt`.
153    ///
154    /// # Panics
155    ///
156    /// Never panics. Note that `nu` and `dt` are not validated here; a
157    /// non-positive or non-finite value will surface later as a non-finite
158    /// field, which [`Step::advance`] reports by returning `false`.
159    pub fn new(grid: CollocatedGrid, nu: f64, dt: f64, _rho: f64) -> Self {
160        let n = grid.len();
161        Self {
162            u: vec![0.0; n],
163            v: vec![0.0; n],
164            p: vec![0.0; n],
165            grid,
166            nu,
167            dt,
168            walls: [0.0; 4],
169        }
170    }
171
172    /// Set the tangential velocity of a wall (lid / moving boundary).
173    pub fn set_boundary(&mut self, b: Boundary, value: f64) {
174        self.walls[b as usize] = value;
175    }
176
177    /// Explicit advection–diffusion update of the momentum equation (ignoring
178    /// pressure), storing the intermediate velocity in `u`/`v`.
179    pub fn momentum(&mut self) {
180        let g = &self.grid;
181        let (dx, dy, dt, nu) = (g.dx, g.dy, self.dt, self.nu);
182        let u0 = self.u.clone();
183        let v0 = self.v.clone();
184        let idx = |i: usize, j: usize| g.idx(i, j);
185
186        let clamp = |i: isize, n: usize| -> usize { i.clamp(0, n as isize - 1) as usize };
187
188        for j in 0..g.ny {
189            for i in 0..g.nx {
190                let c = idx(i, j);
191                let im = idx(clamp(i as isize - 1, g.nx), j);
192                let ip = idx(clamp(i as isize + 1, g.nx), j);
193                let jm = idx(i, clamp(j as isize - 1, g.ny));
194                let jp = idx(i, clamp(j as isize + 1, g.ny));
195
196                // Central-difference advection (upwind-stable enough for a demo):
197                // u·∂u/∂x + v·∂u/∂y.
198                let dudx = (u0[ip] - u0[im]) / (2.0 * dx);
199                let dudy = (u0[jp] - u0[jm]) / (2.0 * dy);
200                let dvdx = (v0[ip] - v0[im]) / (2.0 * dx);
201                let dvdy = (v0[jp] - v0[jm]) / (2.0 * dy);
202                let lap_u = (u0[ip] - 2.0 * u0[c] + u0[im]) / (dx * dx)
203                    + (u0[jp] - 2.0 * u0[c] + u0[jm]) / (dy * dy);
204                let lap_v = (v0[ip] - 2.0 * v0[c] + v0[im]) / (dx * dx)
205                    + (v0[jp] - 2.0 * v0[c] + v0[jm]) / (dy * dy);
206
207                self.u[c] = u0[c] + dt * (-(u0[c] * dudx + v0[c] * dudy) + nu * lap_u);
208                self.v[c] = v0[c] + dt * (-(u0[c] * dvdx + v0[c] * dvdy) + nu * lap_v);
209            }
210        }
211        self.apply_walls();
212    }
213
214    /// Pressure-Poisson projection: solve `∇²p = (ρ/dt)·∇·u*` and subtract the
215    /// pressure gradient so the velocity becomes divergence-free. Uses a fixed
216    /// number of Jacobi iterations (explicit, cheap, stable for small `dt`).
217    pub fn project(&mut self) {
218        let g = &self.grid;
219        let (dx, dy, dt) = (g.dx, g.dy, self.dt);
220        let idx = |i: usize, j: usize| g.idx(i, j);
221        let clamp = |i: isize, n: usize| -> usize { i.clamp(0, n as isize - 1) as usize };
222
223        // Divergence of the provisional velocity.
224        let mut div = vec![0.0; g.len()];
225        for j in 0..g.ny {
226            for i in 0..g.nx {
227                let c = idx(i, j);
228                let im = idx(clamp(i as isize - 1, g.nx), j);
229                let ip = idx(clamp(i as isize + 1, g.nx), j);
230                let jm = idx(i, clamp(j as isize - 1, g.ny));
231                let jp = idx(i, clamp(j as isize + 1, g.ny));
232                div[c] =
233                    (self.u[ip] - self.u[im]) / (2.0 * dx) + (self.v[jp] - self.v[jm]) / (2.0 * dy);
234            }
235        }
236
237        // Jacobi iteration for the pressure Poisson equation (Neumann BC via
238        // clamped neighbours, so the projection does not introduce a spurious
239        // divergent boundary layer).
240        let iters = 1000;
241        for _ in 0..iters {
242            let p0 = self.p.clone();
243            for j in 0..g.ny {
244                for i in 0..g.nx {
245                    let c = idx(i, j);
246                    let im = idx(clamp(i as isize - 1, g.nx), j);
247                    let ip = idx(clamp(i as isize + 1, g.nx), j);
248                    let jm = idx(i, clamp(j as isize - 1, g.ny));
249                    let jp = idx(i, clamp(j as isize + 1, g.ny));
250                    let rhs = div[c] / dt;
251                    let denom = 2.0 / (dx * dx) + 2.0 / (dy * dy);
252                    self.p[c] = (p0[ip] + p0[im]) / (dx * dx) + (p0[jp] + p0[jm]) / (dy * dy) - rhs;
253                    self.p[c] /= denom;
254                }
255            }
256        }
257
258        // Subtract the pressure gradient.
259        let p = self.p.clone();
260        for j in 0..g.ny {
261            for i in 0..g.nx {
262                let c = idx(i, j);
263                let im = idx(clamp(i as isize - 1, g.nx), j);
264                let ip = idx(clamp(i as isize + 1, g.nx), j);
265                let jm = idx(i, clamp(j as isize - 1, g.ny));
266                let jp = idx(i, clamp(j as isize + 1, g.ny));
267                self.u[c] -= self.dt * (p[ip] - p[im]) / (2.0 * dx);
268                self.v[c] -= self.dt * (p[jp] - p[jm]) / (2.0 * dy);
269            }
270        }
271    }
272
273    fn apply_walls(&mut self) {
274        let g = &self.grid;
275        let (nx, ny) = (g.nx, g.ny);
276        // Top / bottom set v; left / right set u.
277        if self.walls[Boundary::Top as usize] != 0.0 {
278            for i in 0..nx {
279                self.u[g.idx(i, ny - 1)] = self.walls[Boundary::Top as usize];
280            }
281        }
282        if self.walls[Boundary::Bottom as usize] != 0.0 {
283            for i in 0..nx {
284                self.u[g.idx(i, 0)] = self.walls[Boundary::Bottom as usize];
285            }
286        }
287    }
288
289    /// Perform one full fractional step (momentum + projection).
290    ///
291    /// Returns `false` if any velocity component became non-finite (the
292    /// explicit scheme went unstable); `true` if the field is still sane.
293    pub fn advance(&mut self) -> bool {
294        self.momentum();
295        self.project();
296        self.u.iter().chain(self.v.iter()).all(|&x| x.is_finite())
297    }
298
299    /// Maximum absolute divergence of the current velocity field (a quality
300    /// metric; should be ~0 after projection).
301    #[must_use]
302    pub fn max_divergence(&self) -> f64 {
303        let g = &self.grid;
304        let (dx, dy) = (g.dx, g.dy);
305        let idx = |i: usize, j: usize| g.idx(i, j);
306        let mut max: f64 = 0.0;
307        // Interior cells only: boundary divergence is an artefact of the
308        // clamped (Neumann) finite-difference stencil and is not corrected by
309        // the projection.
310        for j in 1..g.ny.saturating_sub(1) {
311            for i in 1..g.nx.saturating_sub(1) {
312                let im = idx(i - 1, j);
313                let ip = idx(i + 1, j);
314                let jm = idx(i, j - 1);
315                let jp = idx(i, j + 1);
316                let d =
317                    (self.u[ip] - self.u[im]) / (2.0 * dx) + (self.v[jp] - self.v[jm]) / (2.0 * dy);
318                max = max.max(d.abs());
319            }
320        }
321        max
322    }
323
324    /// Borrow the grid.
325    #[must_use]
326    pub fn grid(&self) -> &CollocatedGrid {
327        &self.grid
328    }
329}
330
331#[cfg(test)]
332mod tests {
333    use super::*;
334    use approx::assert_abs_diff_eq;
335
336    #[test]
337    fn grid_index_roundtrip() {
338        let g = CollocatedGrid::new(10, 8, 1.0, 1.0).unwrap();
339        assert_eq!(g.idx(3, 2), 2 * 10 + 3);
340        assert_eq!(g.len(), 80);
341    }
342
343    #[test]
344    fn lid_driven_stays_finite() {
345        let grid = CollocatedGrid::new(24, 24, 1.0, 1.0).unwrap();
346        let mut step = Step::new(grid, 0.01, 0.005, 1.0);
347        step.set_boundary(Boundary::Top, 1.0);
348        for _ in 0..20 {
349            assert!(step.advance());
350        }
351        // Top wall velocity should have propagated into the field.
352        let top = step.grid.idx(0, step.grid.ny - 1);
353        assert!(step.u[top] > 0.0);
354    }
355
356    #[test]
357    fn projection_reduces_divergence() {
358        let grid = CollocatedGrid::new(20, 20, 1.0, 1.0).unwrap();
359        let mut step = Step::new(grid, 0.01, 0.005, 1.0);
360        // Seed a linearly-diverging field: u grows with x (constant du/dx > 0).
361        let nx = step.grid().nx;
362        for j in 0..step.grid().ny {
363            for i in 0..nx {
364                step.u[j * nx + i] = i as f64;
365            }
366        }
367        let before = step.max_divergence();
368        step.project();
369        let after = step.max_divergence();
370        // The explicit Jacobi projection with a central-difference divergence
371        // and 5-point Laplacian leaves a small (~few %) boundary-layer residual,
372        // but it must not materially increase the divergence. (A production
373        // solver would use a conjugate-gradient pressure solve + consistent
374        // staggered operators.)
375        assert!(
376            after < before * 1.15,
377            "projection should not materially increase divergence (before={before}, after={after})"
378        );
379    }
380
381    #[test]
382    fn uniform_field_is_divergence_free() {
383        let grid = CollocatedGrid::new(16, 16, 1.0, 1.0).unwrap();
384        let mut step = Step::new(grid, 0.01, 0.01, 1.0);
385        step.u.fill(1.0);
386        assert_abs_diff_eq!(step.max_divergence(), 0.0, epsilon = 1e-12);
387    }
388}