outram_foam_appbuilder_lib/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//! **This is OUTRAM PARK's independent Rust translation of selected
23//! OpenFOAM® solver-application algorithms — it is not the official
24//! OpenFOAM® software and is not affiliated with, endorsed by, or
25//! sanctioned by OpenCFD Ltd. or the ESI Group.** OpenFOAM® is a registered
26//! trademark of OpenCFD Limited. See `TRADEMARKS.md` (this crate's
27//! directory, mirrored from the workspace root) for the full attribution
28//! and non-affiliation notice.
29//!
30//! # `outram-foam-appbuilder-lib` — Layer 5: solver applications and case I/O
31//!
32//! This crate is the **application layer** of the OUTRAM PARK OpenFOAM-in-Rust
33//! stack. It sits on top of `outram-foam-basic-lib` (Layers 1–4: tensors,
34//! fields, mesh, `fvm`/`fvc` operators, linear solvers) and
35//! `outram-foam-turbulence-lib` (turbulence closures), and supplies the parts
36//! those crates deliberately do not: the **time-advancement loops**, the
37//! **case-file structures**, and the **multiphysics coupling drivers**.
38//!
39//! ```text
40//! outram-foam-basic-lib Layers 1–4 primitives, fields, mesh, FV operators
41//! outram-foam-turbulence-lib Layer 4 RAS/LES closures
42//! │
43//! ▼
44//! outram-foam-appbuilder-lib Layer 5 ← THIS CRATE
45//! ```
46//!
47//! ## Where to start
48//!
49//! - [`solvers`] — one submodule per ported OpenFOAM application. Each owns its
50//! PISO/PIMPLE (or explicit) time loop. Construct one with `new(mesh, control,
51//! schemes, solution)`, set the field state, then call `step()` or `run()`.
52//! - [`case_runner`] — the layer above that: read an OpenFOAM case directory,
53//! build the solver's initial state from it, march the loop and write the
54//! fields back. `CaseRun::from_case(dir, SolverKind::PimpleFoam)` is the
55//! one-line way in; the CLI binaries in `outram-foam-cli` are thin wrappers
56//! over it, and it is what the Python bindings expose.
57//! - [`io`] — readers for `constant/polyMesh` and `0/<field>` files, plus typed
58//! `controlDict` / `fvSchemes` / `fvSolution` structs.
59//! - [`turbulence`] — pick a closure for a solver run.
60//! - [`prelude`] — one `use` that pulls in the commonly needed public items.
61//! - `tutorials/` — runnable end-to-end cases; the intended entry point for a
62//! reader new to the crate.
63//!
64//! ## Maturity — read before depending on this
65//!
66//! This is an early (0.1.0), in-progress crate and its surface is uneven:
67//! some paths are validated against published benchmarks, others are
68//! unexercised, and several are `todo!()`. The **`README.md` "Limitations"
69//! section is the authoritative per-module status** and is deliberately
70//! detailed. Two consequences bite immediately:
71//!
72//! - **No OpenFOAM dictionary parsing.** [`io::control_dict::ControlDict::read`],
73//! [`io::fv_schemes::FvSchemes::read`] and
74//! [`io::fv_solution::FvSolution::read`] are `todo!()`. Configure a case by
75//! constructing the structs in Rust (`Default::default()` plus field
76//! assignment), not by reading `system/…` from disk.
77//! - **No field output.** Every writer in [`io::output`] is `todo!()`, so a
78//! solver run leaves its results in memory only — read them off the solver's
79//! public field members.
80//!
81//! Per the workspace `RESPONSIBLE_USE.md`, nothing here is for reactor
82//! operation, control, licensing, or any safety-critical or operational use.
83
84/// The crate's single error type, [`error::AppBuilderError`].
85/// Driving a solver from an OpenFOAM case directory: read the case, build the
86/// solver's initial state, march the time loop, write the fields back.
87pub mod case_runner;
88/// Ready-made flow cases (boundary conditions + diagnostics) shared by V&V
89/// tests and demos, e.g. [`cases::laminar_pipe`].
90pub mod cases;
91
92pub mod error;
93/// GeN-Foam reactor-multiphysics port (neutronics + TH + thermo-mechanics).
94/// See `docs/genfoam-port-plan.md` for the module map and translation order.
95pub mod genfoam;
96/// Pebble-bed HTGR closures (original work, not a GeN-Foam port): bed
97/// effective conductivity (Breitbach default, ZBS comparison), KTA 3102.2 heat
98/// transfer, KTA 3102.3 pressure drop, and the IAEA-TECDOC-1694 HTR-10 solid
99/// conductivities. See [`htgr_closures`].
100pub mod htgr_closures;
101/// The HTR-10 R-Z solid conduction and radiation model (original work,
102/// gh:#1149 part B): the TECDOC-1694 44-region THERMIX-style model built from
103/// the cited input sheet on the solid conduction field, with the
104/// [`htgr_closures`] properties. See [`htr10_rz`].
105pub mod htr10_rz;
106/// OpenFOAM case input/output — polyMesh and field readers, typed
107/// `controlDict`/`fvSchemes`/`fvSolution`, and (unimplemented) field writers.
108pub mod io;
109/// Re-exports of the crate's commonly used public items, for
110/// `use outram_foam_appbuilder_lib::prelude::*;`.
111pub mod prelude;
112/// The ported OpenFOAM solver applications and their time-advancement loops.
113pub mod solvers;
114/// Turbulence-closure selection for the solver loops — the Layer-5 adapter over
115/// `outram-foam-turbulence-lib`. See [`turbulence::TurbulenceClosure`].
116pub mod turbulence;