outram_foam_multiphase/lib.rs
1// SPDX-License-Identifier: GPL-3.0-only
2// Copyright (C) 2026 OUTRAM PARK contributors
3// Derived from OpenFOAM (www.openfoam.com)
4// Copyright (C) 2004-2023 OpenFOAM Foundation
5// Copyright (C) 2016-2023 OpenCFD Ltd.
6//
7// This file is part of OUTRAM PARK.
8//
9// OUTRAM PARK is free software: you can redistribute it and/or modify it
10// under the terms of the GNU General Public License as published by the
11// Free Software Foundation, either version 3 of the License, or (at your
12// option) any later version.
13//
14// OUTRAM PARK is distributed in the hope that it will be useful, but
15// WITHOUT ANY WARRANTY; without even the implied warranty of
16// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17// General Public License for more details.
18//
19// You should have received a copy of the GNU General Public License along
20// with OUTRAM PARK. If not, see <https://www.gnu.org/licenses/>.
21
22//! # outram-foam-multiphase
23//!
24//! **OUTRAM-FOAM Phase II — multiphase CFD** (bead epic `op-2kk`). Pure-Rust
25//! translation of OpenFOAM's multiphase solver family on top of
26//! [`outram_foam_basic_lib`]'s finite-volume framework (`FvMesh`, fields,
27//! `fvc`/`fvm` operators). This is the **authoritative high-fidelity reference**
28//! from which TAMPINES' 1D reduced-order system-code physics (epic `op-dt3`)
29//! are derived — 1D models must trace back to a validated 3D reference here,
30//! never be invented independently.
31//!
32//! > **⚠️ Unverified until validated — early/scaffold.** Everything here is a
33//! > work-in-progress translation with no human V&V yet. Not for nuclear
34//! > facility operation, reactor control, safety-critical, or licensing
35//! > decisions. Independent OUTRAM PARK fork, not the official OpenFOAM
36//! > software (see the workspace `TRADEMARKS.md`).
37//!
38//! ## Roadmap (per the Phase II architecture; each solver bead has its own DoD:
39//! ## theory docs + verification tests + reference-benchmark comparison + uom)
40//!
41//! - **Stage 1 — Drift Flux** ([`drift_flux`]) — mixture continuity/momentum,
42//! void-fraction transport, algebraic slip / drift-velocity closures
43//! (Zuber-Findlay, terminal velocity, user-defined). Ref OpenFOAM
44//! `incompressibleDriftFlux`. Foundation done (bead `op-2kk.1`); the mixture
45//! momentum + pressure coupling it deliberately leaves out is provided by
46//! [`pimple`] (see below).
47//! - **Stage 2 — Euler-Euler two-fluid** ([`two_fluid`]) — per-phase
48//! continuity + drag closures (Schiller-Naumann, Wen-Yu), 6-equation
49//! architecture scaffolded. Ref OpenFOAM `multiphaseEuler`. Foundation done
50//! (bead `op-2kk.2`).
51//! - **Stage 3 — Wall boiling framework** ([`wall_boiling`]) — RPI heat-flux
52//! partitioning (Kurul & Podowski). Foundation done (bead `op-2kk.3`).
53//! - **Stage 4 — CHF models** ([`chf`]) — Biasi / W-3 / Bowring correlations +
54//! Groeneveld LUT framework. Foundation done (bead `op-2kk.4`).
55//! - **Stage 5 — Dryout / post-dryout framework** ([`dryout`]) — reserved
56//! interfaces + Dougall-Rohsenow worked example. Foundation done (`op-2kk.5`).
57//!
58//! ### Pressure-velocity coupling
59//!
60//! Two segregated PISO/PIMPLE loops close the momentum + pressure solve the
61//! drift-flux and two-fluid foundations deliberately leave out:
62//!
63//! - [`pimple`] — drift-flux **mixture** PISO/PIMPLE: a Rhie-Chow
64//! pressure-correction loop on the single mixture-momentum field, advancing
65//! `U_m`–`p`–`α` together.
66//! - [`two_fluid_pimple`] — **shared-pressure Euler-Euler** PISO: two per-phase
67//! momentum predictors coupled through one mixture-continuity pressure
68//! equation, advancing `U_d`–`U_c`–`p`–`α_d` together.
69//!
70//! All modules here are **unit-tested foundations, not validated solvers**
71//! (verification checks — hydrostatic balance, at-rest stability, boundedness —
72//! only; benchmark validation is a later human step) — see each module's
73//! "Honest scope".
74//!
75//! ## Design rules (workspace `CLAUDE.md`)
76//!
77//! Enum dispatch (no `Box<dyn>`), no lifetime parameters (`Arc`, index ids),
78//! `uom`-typed API boundaries, GPLv3 + OpenFOAM provenance headers on ported
79//! files, Android-buildable (pure-Rust, no system BLAS/GUI).
80
81pub mod chf;
82pub mod drift_flux;
83pub mod dryout;
84pub mod heat_transfer;
85pub mod pimple;
86pub mod two_fluid;
87pub mod two_fluid_pimple;
88pub mod wall_boiling;
89
90/// Errors produced by the multiphase solvers in this crate.
91#[derive(Debug, thiserror::Error)]
92pub enum MultiphaseError {
93 /// A model input was outside its valid physical range.
94 #[error("invalid input: {0}")]
95 InvalidInput(String),
96 /// A requested feature is scaffolded but not yet implemented.
97 #[error("not yet implemented: {0}")]
98 NotImplemented(String),
99 /// A numerical failure (non-convergence, non-physical state) occurred.
100 #[error("solver error: {0}")]
101 Solver(String),
102}