Expand description
§The Merlin validation book
Merlin solves hyperbolic conservation laws on uniform structured grids: linear advection, Burgers’ equation and the Euler equations closed by an ideal gas, a stiffened gas or a Mie-Gruneisen solid, in one, two and three dimensions and in cylindrical and spherical symmetry, with WENO and linear high-order reconstruction, and the transport of a level set. This book is the case that its answers are right. It states the equations, the numerical methods and the method of checking them, and then records every check that has been made, grouped by geometry, with the numbers.
It is part of the generated documentation, so the API pages (merlin_core, merlin_materials,
merlin_systems, merlin_finite_volume, merlin_levelset, merlin_io, merlin_driver,
merlin_cli) and the evidence sit side by side.
§How to read it
| Part | What it answers |
|---|---|
| Equations | What is being solved: the PDEs, their exact solutions, and the conditions an answer must satisfy |
| The crates | How the code is split, and which crate may depend on which |
| Materials | What a material is: the fluid models (ideal, stiffened and Mie-Gruneisen gases), the response of each side of an interface, and the solve that matches two sides |
| Coupled materials | Several fluids on one grid: the owner of each cell, the band of ghost cells, the velocity that moves the interface, and the checks (one material is Solver bit for bit, the order of the coupling, restart, output) |
| Numerical methods | How: the finite-volume discretisation, reconstruction, Riemann fluxes, time integration, coordinates, blocks and threads |
| Verification method | How “correct” is measured: observed order of convergence, norms, invariants, bit comparisons, independent reference solvers |
| Validation by geometry | The evidence, one page per geometry: 1D, 2D, 3D, cylindrical, spherical, high order and level set |
| Convergence and analytics | Every measured order of convergence in one table, the conservation checks, and the exact solutions behind them |
| Choosing a scheme | The validation read as advice: which scheme, flux, variables and integrator for which problem |
| Known limitations | Where the schemes are expected to fail, and what has not been validated |
| Reproducing the results | The commands that produced every number |
§Kinds of evidence
A result is only worth as much as the reference it is compared with. Each claim in the book names one of these:
- An exact solution. A closed-form or independently computed answer: the characteristics solution of Burgers’ equation, the exact Riemann solution of the Euler equations (Toro, 2009), an isentropic vortex (Shu, 1998), Noh’s implosion (1987), a linear sound wave in cylindrical or spherical symmetry. The error is measured and the observed order of convergence is compared with the order the scheme is designed for.
- A published reference. Tabulated values, such as Toro’s star-region pressures and velocities, or published configurations with no exact answer (Lax and Liu, 1998), where only what can be derived is asserted: symmetry, positivity, jump conditions, conservation, refinement.
- An invariant. A property the answer must have exactly, such as a gas at rest staying at rest, a stationary contact staying stationary, or conservation of mass and energy in a closed domain to round-off.
- A bit comparison. Two ways of computing the same thing must agree to the last bit: any number of threads, any block layout, a file-driven run against a library-driven run, HDF5 against CSV, a scheme in a box against the scheme itself.
- An independent implementation. Reference solutions written separately in
Python (
src/pymerlin/exact_solutions) and checked against published tables, so that the Rust code is not compared with itself.
§Notation
Inline mathematics is written $u_t + f(u)_x = 0$ and displayed mathematics
looks like this, the integral form of a conservation law that the finite-volume
method enforces cell by cell:
\frac{d}{dt}\int_{x_{i-1/2}}^{x_{i+1/2}} u\,dx = f\bigl(u(x_{i-1/2},t)\bigr) - f\bigl(u(x_{i+1/2},t)\bigr)KaTeX (vendored in docs/assets/katex) draws them; without JavaScript the TeX source is shown.
§Symbols
Most symbols keep one meaning throughout; these do not, so the page says which is meant.
| Symbol | Meaning | Where |
|---|---|---|
$\mathbf{u}$, $u$ | the vector of conserved variables, or a scalar unknown | everywhere |
$u$, $v$, $w$ | velocity components ($w$ is the azimuthal one in the swirl) | Euler, swirl |
$\mathbf{u}$ | the velocity field that advects a level set | level set |
$\phi$ | the level-set function, negative inside | level set |
$h$, $\Delta x$ | cell width | everywhere |
$\nu$ | the Courant number (stability analysis); the number of space dimensions in Noh’s and Sedov’s formulas | stability, curvilinear |
$\alpha$ | 1 or 2 for cylinder or sphere in the geometric terms; Sedov’s energy constant | curvilinear |
$r$ | radius; or half the width of a stencil | methods, high order |
$p$ | pressure; the order of convergence; the gradient in a Hamilton-Jacobi equation | context |
$c$ | sound speed; a stencil coefficient $c_j$; a Runge-Kutta stage time $c_k$ | context |
$S$ | a wave speed $S_L,S_R,S_*$ in HLL and HLLC; the smoothed sign in reinitialisation | methods, high order |
$L$ | the spatial operator $L(u)$; the left eigenvectors in the characteristic variables | methods, high order |
$E$ | the total energy density; in Sedov’s problem, the energy released | Euler, Sedov |
$F$ | a flux, $F_{i\pm1/2}$ at a face | methods |
$u^L$, $u^R$ | the reconstructed states on the left and right of a face | methods |
§Building this book
cargo doc --workspace --no-deps --open; the commands and checks are on the
reproduction page.
Modules§
- choosing
- Choosing a scheme
- convergence
- Convergence and analytics
- crates
- The crates
- equations
- The equations
- limitations
- Known limitations
- materials
- Materials: fluid models and interface responses
- methods
- Numerical methods
- multimaterial
- Coupled materials: several fluids on one grid
- reproduce
- Reproducing the results
- validation
- Validation by geometry
- verification
- Verification method