amerta: A Python Library for Idealized 1D Saint--Venant Dam-Break Simulation
Pith reviewed 2026-06-28 21:00 UTC · model grok-4.3
The pith
The amerta library solves 1D Saint-Venant dam-break flows while conserving mass to floating-point precision and matching analytical solutions to sub-centimetre accuracy.
A machine-rendered reading of the paper's core claim, the machinery that carries it, and where it could break.
Core claim
The implementation conserves discrete mass to floating-point precision, satisfies discrete entropy admissibility identically, and reproduces all four analytical wave-curve geometries to within sub-centimetre accuracy in the depth-velocity phase plane.
What carries the argument
MUSCL reconstruction with minmod slope limiter, HLLC approximate Riemann solver, and SSP-RK2 time integration on a uniform grid, together with a six-component verification pipeline that includes phase-plane comparison to analytical wave curves.
If this is right
- The same discrete conservation and entropy properties hold for repeated simulations of any of the four verified configurations.
- The post-processing pipeline can be applied directly to quantify self-similarity collapse and boundary-flux-corrected energy diagnostics on new runs.
- The released NetCDF archives allow exact reproduction of the reported space-time topology and final-time error norms.
- Numba-compiled kernels enable the same verification workflow to be executed efficiently on standard hardware.
Where Pith is reading between the lines
- The verification workflow could be reused without modification to test extensions that add bottom friction or move to two spatial dimensions.
- Exact floating-point mass conservation implies the underlying finite-volume discretization is fully conservative even at domain boundaries.
- Sub-centimetre phase-plane agreement across all wave families indicates the limiter and Riemann solver combination handles both rarefactions and shocks without introducing spurious oscillations.
Load-bearing premise
Verification against the four canonical Riemann problems on a uniform grid is sufficient to establish correctness for the broader class of idealized dam-break flows.
What would settle it
A single run of any of the four Riemann problems that produces mass conservation error exceeding machine epsilon or phase-plane deviation from the analytical curves larger than sub-centimetre would falsify the central claims.
Figures
read the original abstract
The Saint-Venant shallow water equations (SWE) govern depth-integrated free-surface flows arising in dam-break inundation, flood routing, tsunami runup, and estuarine tidal dynamics. Closed-form analytical solutions exist only for highly idealized Riemann configurations, making rigorously verified numerical solvers essential. This work presents amerta, an open-source Python library that solves the one-dimensional frictionless Saint-Venant system on a uniform Cartesian grid using Monotone Upstream-centered Schemes for Conservation Laws (MUSCL) reconstruction with a minmod slope limiter, the Harten-Lax-van Leer-Contact (HLLC) approximate Riemann solver, and two-stage strong-stability-preserving Runge-Kutta (SSP-RK) time integration. Numba just-in-time (JIT) compilation accelerates the performance-critical kernels. The solver is verified end-to-end against the four canonical Riemann configurations: wet-bed dam break, dry-bed dam break, double rarefaction, and double shock. A six-component post-processing pipeline quantifies space-time topology, final-time error norms with empirical quantile decomposition, self-similarity collapse onto the analytical Riemann fan, integral-norm evolution, boundary-flux-corrected mass and energy diagnostics, and phase-plane analysis against analytical wave curves. The implementation conserves discrete mass to floating-point precision, satisfies discrete entropy admissibility identically, and reproduces all four analytical wave-curve geometries to within sub-centimetre accuracy in the depth-velocity phase plane. The complete source code, analytical-solution evaluators, post-processing scripts, and Network Common Data Format (NetCDF) archives are released under the MIT license.
Editorial analysis
A structured set of objections, weighed in public.
Referee Report
Summary. The manuscript presents amerta, an open-source Python library implementing a 1D frictionless Saint-Venant solver on uniform grids via MUSCL-minmod reconstruction, HLLC approximate Riemann solver, and SSP-RK2 time integration with Numba JIT. It describes a six-component post-processing pipeline and reports verification against the four canonical Riemann problems (wet-bed dam break, dry-bed dam break, double rarefaction, double shock), claiming machine-precision discrete mass conservation, identical discrete entropy admissibility, and sub-centimetre accuracy in depth-velocity phase-plane comparisons to analytical wave curves.
Significance. If the reported numerical properties hold under scrutiny, the work supplies a reproducible, MIT-licensed tool with exact conservation diagnostics and analytical evaluators that can serve as a benchmark for other shallow-water codes. The explicit release of source, post-processing scripts, and NetCDF archives is a clear strength for the field.
major comments (2)
- [Abstract / Verification paragraph] Abstract and verification paragraph: the central claims of end-to-end verification, machine-precision mass conservation, and sub-centimetre phase-plane accuracy rest on unexamined implementation specifics, yet the manuscript supplies no quantitative error tables, L1/L2 norms, or grid-convergence studies to support them.
- [Verification paragraph] Verification paragraph: the assertion that tests on the four canonical Riemann problems suffice to establish correctness for the broader class of idealized dam-break flows described in the abstract is presented without additional justification or tests on non-Riemann configurations.
minor comments (1)
- The six-component post-processing pipeline is described at a high level; a concise table listing each diagnostic and its purpose would improve clarity.
Simulated Author's Rebuttal
We thank the referee for their constructive feedback and for recognizing the potential value of the released code and data as a benchmark. We address each major comment below, indicating planned revisions where appropriate.
read point-by-point responses
-
Referee: [Abstract / Verification paragraph] Abstract and verification paragraph: the central claims of end-to-end verification, machine-precision mass conservation, and sub-centimetre phase-plane accuracy rest on unexamined implementation specifics, yet the manuscript supplies no quantitative error tables, L1/L2 norms, or grid-convergence studies to support them.
Authors: We agree that the manuscript text does not present tabulated L1/L2 error norms or grid-convergence studies, even though the post-processing pipeline computes these quantities. The claims of machine-precision mass conservation and sub-centimetre phase-plane accuracy are supported by the released NetCDF archives and scripts, but the numerical values are not summarized in tables within the paper. In the revised version we will add a table of final-time L1 and L2 norms for depth and velocity for each of the four test cases, together with a short grid-convergence study on one representative problem to make the quantitative support explicit. revision: yes
-
Referee: [Verification paragraph] Verification paragraph: the assertion that tests on the four canonical Riemann problems suffice to establish correctness for the broader class of idealized dam-break flows described in the abstract is presented without additional justification or tests on non-Riemann configurations.
Authors: The four canonical Riemann problems were chosen because they collectively exercise every wave type and state combination that arises in idealized 1D dam-break flows (wet and dry beds, shocks, rarefactions, and contacts). These are the only configurations that admit exact analytical solutions, which is why they form the standard verification suite in the shallow-water literature. We acknowledge that the manuscript does not explicitly justify this selection or include non-Riemann test cases. In revision we will insert a concise paragraph explaining the coverage of wave structures and noting that the library is intended for these exact analytical benchmarks rather than for general non-Riemann flows. revision: partial
Circularity Check
No significant circularity identified
full rationale
The paper implements a standard MUSCL-minmod + HLLC + SSP-RK2 finite-volume scheme for the 1D Saint-Venant equations and verifies it directly against four independent analytical Riemann solutions. Claims of machine-precision mass conservation, identical discrete entropy satisfaction, and sub-centimetre phase-plane accuracy follow from the conservative discretization and known HLLC properties on wet/dry problems; no self-definitional relations, fitted inputs renamed as predictions, or load-bearing self-citations appear. The six-component post-processing pipeline simply reports these properties against external analytical wave curves, rendering the verification chain self-contained.
Axiom & Free-Parameter Ledger
axioms (2)
- domain assumption The Saint-Venant shallow water equations govern the idealized frictionless dam-break flows under consideration.
- domain assumption MUSCL-minmod reconstruction, HLLC Riemann solver, and SSP-RK time integration are appropriate and stable for the four Riemann configurations.
Reference graph
Works this paper leans on
-
[1]
Th´ eorie du Mouvement Non Permanent des Eaux, avec Application aux Crues des Rivi` eres et ` a l’Introduction des Mar´ ees dans leur Lit.Comptes Rendus Acad
de Saint-Venant, A.J.C. Th´ eorie du Mouvement Non Permanent des Eaux, avec Application aux Crues des Rivi` eres et ` a l’Introduction des Mar´ ees dans leur Lit.Comptes Rendus Acad. Sci. Paris1871,73, 147–154, 237–240
-
[2]
Die Fortpflanzung der Wasserwellen.Z
Ritter, A. Die Fortpflanzung der Wasserwellen.Z. Ver. Deutsch. Ing.1892,36, 947–954
-
[3]
Stoker, J.J.Water Waves: The Mathematical Theory with Applications; Interscience Publishers: New York, NY, USA, 1957
1957
-
[4]
Hyperbolic systems of conservation laws II.Commun
Lax, P.D. Hyperbolic systems of conservation laws II.Commun. Pure Appl. Math.1957,10, 537–566. https://doi.org/10.1002/cpa.3160100406
-
[5]
Batchelor, G.K.An Introduction to Fluid Dynamics; Cambridge University Press: Cambridge, UK, 1967
1967
-
[6]
First Order Quasilinear Equations in Several Independent Variables.Math
Kruzhkov, S.N. First Order Quasilinear Equations in Several Independent Variables.Math. USSR Sb.1970, 10, 217–243.https://doi.org/10.1070/SM1970v010n02ABEH002156
-
[7]
An algorithm with guaranteed convergence for finding a zero of a function.Comput
Brent, R.P. An algorithm with guaranteed convergence for finding a zero of a function.Comput. J.1971, 14(4), 422–425.https://doi.org/10.1093/comjnl/14.4.422
-
[8]
Differentiation Under the Integral Sign.Am
Flanders, H. Differentiation Under the Integral Sign.Am. Math. Mon.1973,80(6), 615–627.https: //doi.org/10.2307/2319163
-
[9]
Towards the Ultimate conservative difference scheme
van Leer, B. Towards the Ultimate conservative difference scheme. V. A second-Order sequel to Godunov’s Method.J. Comput. Phys.1979,32(1), 101–136.https://doi.org/10.1016/0021-9991(79)90145-1
-
[10]
Monotone difference approximations for scalar conservation laws.Math
Crandall, M.G.; Majda, A. Monotone difference approximations for scalar conservation laws.Math. Comp. 1980,34, 1–21.https://doi.org/10.1090/S0025-5718-1980-0551288-3
-
[11]
Harten, A.; Lax, P.D.; van Leer, B. On Upstream Differencing and Godunov-Type Schemes for Hyperbolic Conservation Laws.SIAM Rev.1983,25(1), 35–61.https://doi.org/10.1137/1025002
-
[12]
1983, Journal of Computational Physics, 49, 357, doi: 10.1016/0021-9991(83)90136-5
Harten, A. High resolution schemes for hyperbolic conservation laws.J. Comput. Phys.1983,49(3), 357– 393.https://doi.org/10.1016/0021-9991(83)90136-5
-
[13]
High Resolution Schemes Using Flux Limiters for Hyperbolic Conservation Laws.SIAM J
Sweby, P.K. High Resolution Schemes Using Flux Limiters for Hyperbolic Conservation Laws.SIAM J. Numer. Anal.1984,21(5), 995–1011.https://doi.org/10.1137/0721062
-
[14]
6 of Course of Theoretical Physics
Landau, L.D.; Lifshitz, E.M.Fluid Mechanics, 2nd ed.; Pergamon Press: Oxford, UK, 1987; Vol. 6 of Course of Theoretical Physics
1987
-
[15]
The numerical viscosity of entropy stable schemes for systems of conservation laws
Tadmor, E. The numerical viscosity of entropy stable schemes for systems of conservation laws. I.Math. Comp.1987,49, 91–103.https://doi.org/10.1090/S0025-5718-1987-0890255-3
-
[16]
Efficient implementation of essentially non-oscillatory shock-capturing schemes.J
Shu, C.-W.; Osher, S. Efficient implementation of essentially non-oscillatory shock-capturing schemes.J. Comput. Phys.1988,77(2), 439–471.https://doi.org/10.1016/0021-9991(88)90177-5
-
[17]
On Godunov-Type Methods for Gas Dynamics.SIAM J
Einfeldt, B. On Godunov-Type Methods for Gas Dynamics.SIAM J. Numer. Anal.1988,25(2), 294–318. https://doi.org/10.1137/0725021
-
[18]
Vreugdenhil, C.B.Numerical Methods for Shallow-Water Flow; Kluwer Academic Publishers: Dordrecht, The Netherlands, 1994
1994
-
[19]
Toro, E.F.; Spruce, M.; Speares, W. Restoration of the contact surface in the HLL-Riemann solver.Shock Waves1994,4, 25–34.https://doi.org/10.1007/BF01414629
-
[20]
Toro, E.F.Shock-Capturing Methods for Free-Surface Shallow Flows; John Wiley & Sons: Chichester, UK, 2001
2001
-
[21]
Strong Stability-Preserving High-Order Time Discretization Methods
Gottlieb, S.; Shu, C.-W.; Tadmor, E. Strong Stability-Preserving High-Order Time Discretization Methods. SIAM Rev.2001,43(1), 89–112.https://doi.org/10.1137/S003614450036757X
-
[22]
LeVeque, R.J.Finite Volume Methods for Hyperbolic Problems; Cambridge University Press: Cambridge, UK, 2002.https://doi.org/10.1017/CBO9780511791253
-
[23]
Audusse, E.; Bouchut, F.; Bristeau, M.-O.; Klein, R.; Perthame, B. A Fast and Stable Well-Balanced Scheme with Hydrostatic Reconstruction for Shallow Water Flows.SIAM J. Sci. Comput.2004,25(6), 2050–2065.https://doi.org/10.1137/S1064827503431090
-
[24]
Augmented Riemann Solvers for the Shallow Water Equations Over Variable Topography with Steady States and Inundation.J
George, D.L. Augmented Riemann Solvers for the Shallow Water Equations Over Variable Topography with Steady States and Inundation.J. Comput. Phys.2008,227(6), 3089–3113.https://doi.org/10. 1016/j.jcp.2007.10.027
2008
-
[25]
Delestre, O.; Lucas, C.; Ksinant, P.-A.; Darboux, F.; Laguerre, C.; Vo, T.N.T.; James, F.; Cordier, S. SWASHES: a compilation of shallow water analytic solutions for hydraulic and environmental studies.Int. J. Numer. Methods Fluids2013,72, 269–300.https://doi.org/10.1002/fld.3741
-
[26]
Herho, S.H.S.; Trilaksono, N.J.; Fajary, F.R.; Napitupulu, G.; Anwar, I.P.; Khadami, F.; Irawan, D.E. kh2d-solver: A Python Library for Idealized Two-Dimensional Incompressible Kelvin–Helmholtz Instability. Appl. Comput. Mech.2025,19, 125–156.https://doi.org/10.24132/acm.2025.1040
-
[27]
Herho, S.H.S.; Anwar, I.P.; Khadami, F.; Ndruru, T.R.E.B.N.; Suwarman, R.; Irawan, D.E. wave- attenuation-1d: An Idealized One-Dimensional Framework for Wave Attenuation Through Coastal Veg- etation Using Numba-Accelerated Shallow Water Equations.J. Theor. Appl. Mech.2026,56, 89–102. https://doi.org/10.55787/jtams.2026.1.AI00236
-
[28]
Irawan, D.E.; Herho, S.H.S.; Pamumpuni, A.; Kartiko, R.D.; Khadami, F.; Anwar, I.P.; Sujatmiko, K.A.; Handayani, A.P.; Fajary, F.R.; Suwarman, R. An Open-Source Pseudo-Spectral Solver for Idealized Korteweg–de Vries Soliton Simulations.Water2026,18, 779.https://doi.org/10.3390/w18070779
-
[29]
Computing in Science and Engineering , keywords =
Hunter, J.D. Matplotlib: A 2D Graphics Environment.Comput. Sci. Eng.2007,9(3), 90–95.https: 22 //doi.org/10.1109/MCSE.2007.55
-
[30]
Data structures for statistical computing in python
McKinney, W. Data Structures for Statistical Computing in Python. InProceedings of the 9th Python in Science Conference (SciPy 2010); van der Walt, S., Millman, J., Eds.; Austin, TX, USA, 28 June–3 July 2010; pp. 56–61.https://doi.org/10.25080/Majora-92bf1922-00a
-
[31]
Lam, S.K.; Pitrou, A.; Seibert, S. Numba: A LLVM-Based Python JIT Compiler. InProceedings of the Second Workshop on the LLVM Compiler Infrastructure in HPC (LLVM-HPC 2015); Austin, TX, USA, 15 November 2015; pp. 1–6.https://doi.org/10.1145/2833157.2833162
-
[32]
Harris, C.R.; Millman, K.J.; van der Walt, S.J.; Gommers, R.; Virtanen, P.; Cournapeau, D.; Wieser, E.; Taylor, J.; Berg, S.; Smith, N.J.; Kern, R.; Picus, M.; Hoyer, S.; van Kerkwijk, M.H.; Brett, M.; Haldane, A.; del R´ ıo, J.F.; Wiebe, M.; Peterson, P.; G´ erard-Marchant, P.; Sheppard, K.; Reddy, T.; Weckesser, W.; Abbasi, H.; Gohlke, C.; Oliphant, T.E...
-
[33]
Virtanen, P.; Gommers, R.; Oliphant, T.E.; Haberland, M.; Reddy, T.; Cournapeau, D.; Burovski, E.; Peterson, P.; Weckesser, W.; Bright, J.; van der Walt, S.J.; Brett, M.; Wilson, J.; Millman, K.J.; Mayorov, N.; Nelson, A.R.J.; Jones, E.; Kern, R.; Larson, E.; Carey, C.J.; Polat, ˙I; Feng, Y.; Moore, E.W.; VanderPlas, J.; Laxalde, D.; Perktold, J.; Cimrman...
-
[34]
Whitaker, J.; Khrulev, C.; Huard, D.; Hamman, J.; May, R.; Fernandes, F.netCDF4: Python Interface to the NetCDF C Library; Unidata Program Center, University Corporation for Atmospheric Research: Boulder, CO, USA.https://unidata.github.io/netcdf4-python/
-
[35]
readthedocs.io/
Clark, A.; Murray, A.; van Kemenade, H.Pillow: The Python Imaging Library Fork.https://pillow. readthedocs.io/
-
[36]
da Costa-Luis, C.O.; Larroque, S.K.tqdm: A Fast, Extensible Progress Bar for Python and CLI.https: //tqdm.github.io/. 23
discussion (0)
Sign in with ORCID, Apple, or X to comment. Anyone can read and Pith papers without signing in.