pith. sign in

arxiv: 2605.31011 · v1 · pith:ZALTVTNUnew · submitted 2026-05-29 · ⚛️ physics.flu-dyn · physics.ao-ph· physics.comp-ph

amerta: A Python Library for Idealized 1D Saint--Venant Dam-Break Simulation

Pith reviewed 2026-06-28 21:00 UTC · model grok-4.3

classification ⚛️ physics.flu-dyn physics.ao-phphysics.comp-ph
keywords Saint-Venant equationsdam-break simulationshallow water equationsMUSCL-HLLC schemeRiemann problemsPython librarynumerical verificationconservation laws
0
0 comments X

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.

amerta is an open-source Python library that solves the one-dimensional frictionless Saint-Venant shallow water equations on a uniform Cartesian grid. It combines MUSCL reconstruction with a minmod limiter, the HLLC approximate Riemann solver, and two-stage SSP-RK time integration, with Numba JIT acceleration. The code is verified end-to-end against the four canonical Riemann problems: wet-bed dam break, dry-bed dam break, double rarefaction, and double shock. A six-part post-processing pipeline confirms exact discrete mass conservation, identical entropy satisfaction, and sub-centimetre agreement with analytical wave curves in the depth-velocity plane. All source code, evaluators, scripts, and NetCDF data are released under the MIT license.

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

These are editorial extensions of the paper, not claims the author makes directly.

  • 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

Figures reproduced from arXiv: 2605.31011 by Astyka Pamumpuni, Dasapta E. Irawan, Deny J. Puradimaja, Edi Riawan, Faruq Khadami, Iwan P. Anwar, Rendy D. Kartiko, Rusmawan Suwarman, Sandy H. S. Herho.

Figure 1
Figure 1. Figure 1: Three-dimensional space-time surfaces of the depth field [PITH_FULL_IMAGE:figures/full_fig_p012_1.png] view at source ↗
Figure 2
Figure 2. Figure 2: overlays the numerical depth profile hnum(x, tfinal) (colored solid line) and the analytical Riemann solution han(x, tfinal) (black dashed line) for each case at t = tfinal. The pointwise depth error ej (tfinal) of (47) is summarized through its empirical quantiles Qp [PITH_FULL_IMAGE:figures/full_fig_p013_2.png] view at source ↗
Figure 3
Figure 3. Figure 3: Self-similarity collapse of the depth field in the ( [PITH_FULL_IMAGE:figures/full_fig_p015_3.png] view at source ↗
Figure 4
Figure 4. Figure 4: Time evolution of integral error norms on a logarithmic ordinate against the exact Riemann solution: [PITH_FULL_IMAGE:figures/full_fig_p016_4.png] view at source ↗
Figure 5
Figure 5. Figure 5: Boundary-flux-corrected conservation diagnostics. (a) Mass residual [PITH_FULL_IMAGE:figures/full_fig_p018_5.png] view at source ↗
Figure 6
Figure 6. Figure 6: Phase-plane projection of the final-time numerical state [PITH_FULL_IMAGE:figures/full_fig_p020_6.png] view at source ↗
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.

Desk editor's note, referee report, simulated authors' rebuttal, and a circularity audit. Tearing a paper down is the easy half of reading it; the pith above is the substance, this is the friction.

Referee Report

2 major / 1 minor

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)
  1. [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.
  2. [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)
  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

2 responses · 0 unresolved

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
  1. 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

  2. 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

0 steps flagged

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

0 free parameters · 2 axioms · 0 invented entities

No free parameters or invented entities are introduced. The work rests on the standard shallow-water equations and established numerical schemes from prior literature.

axioms (2)
  • domain assumption The Saint-Venant shallow water equations govern the idealized frictionless dam-break flows under consideration.
    Stated in the opening sentence of the abstract as the governing system.
  • domain assumption MUSCL-minmod reconstruction, HLLC Riemann solver, and SSP-RK time integration are appropriate and stable for the four Riemann configurations.
    Invoked as the discretization choices whose correctness is verified.

pith-pipeline@v0.9.1-grok · 5881 in / 1243 out tokens · 30854 ms · 2026-06-28T21:00:50.904370+00:00 · methodology

discussion (0)

Sign in with ORCID, Apple, or X to comment. Anyone can read and Pith papers without signing in.

Reference graph

Works this paper leans on

36 extracted references · 25 canonical work pages

  1. [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. [2]

    Die Fortpflanzung der Wasserwellen.Z

    Ritter, A. Die Fortpflanzung der Wasserwellen.Z. Ver. Deutsch. Ing.1892,36, 947–954

  3. [3]

    Stoker, J.J.Water Waves: The Mathematical Theory with Applications; Interscience Publishers: New York, NY, USA, 1957

  4. [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. [5]

    Batchelor, G.K.An Introduction to Fluid Dynamics; Cambridge University Press: Cambridge, UK, 1967

  6. [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. [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. [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. [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. [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. [11]

    On Upstream Differencing and Godunov-Type Schemes for Hyperbolic Conservation Laws.SIAM Rev.1983,25(1), 35–61.https://doi.org/10.1137/1025002

    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. [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. [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. [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

  15. [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. [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. [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. [18]

    Vreugdenhil, C.B.Numerical Methods for Shallow-Water Flow; Kluwer Academic Publishers: Dordrecht, The Netherlands, 1994

  19. [19]

    Restoration of the contact surface in the HLL-Riemann solver.Shock Waves1994,4, 25–34.https://doi.org/10.1007/BF01414629

    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. [20]

    Toro, E.F.Shock-Capturing Methods for Free-Surface Shallow Flows; John Wiley & Sons: Chichester, UK, 2001

  21. [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. [22]

    LeVeque, R.J.Finite Volume Methods for Hyperbolic Problems; Cambridge University Press: Cambridge, UK, 2002.https://doi.org/10.1017/CBO9780511791253

  23. [23]

    A Fast and Stable Well-Balanced Scheme with Hydrostatic Reconstruction for Shallow Water Flows.SIAM J

    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. [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

  25. [25]

    SWASHES: a compilation of shallow water analytic solutions for hydraulic and environmental studies.Int

    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. [26]

    kh2d-solver: A Python Library for Idealized Two-Dimensional Incompressible Kelvin–Helmholtz Instability

    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. [27]

    wave- attenuation-1d: An Idealized One-Dimensional Framework for Wave Attenuation Through Coastal Veg- etation Using Numba-Accelerated Shallow Water Equations.J

    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. [28]

    An Open-Source Pseudo-Spectral Solver for Idealized Korteweg–de Vries Soliton Simulations.Water2026,18, 779.https://doi.org/10.3390/w18070779

    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. [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. [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. [31]

    K., Pitrou, A., & Seibert, S

    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. [32]

    R., Millman, K

    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. [33]

    E., et al

    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. [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. [35]

    readthedocs.io/

    Clark, A.; Murray, A.; van Kemenade, H.Pillow: The Python Imaging Library Fork.https://pillow. readthedocs.io/

  36. [36]

    da Costa-Luis, C.O.; Larroque, S.K.tqdm: A Fast, Extensible Progress Bar for Python and CLI.https: //tqdm.github.io/. 23