VfrClosure.hpp File Reference

Volume–free-surface (VFR) closure for a planar-bed triangular cell. More...

#include <cmath>

Include dependency graph for VfrClosure.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces
namespace	openswmm
namespace	openswmm::twoD

Macros
#define	OPENSWMM_KERNEL_FN   inline

Functions
OPENSWMM_KERNEL_FN void	openswmm::twoD::vfrSort3 (double &z1, double &z2, double &z3) noexcept
	Sort three vertex elevations in place so z1 <= z2 <= z3.
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrWetFraction (double z1, double z2, double z3, double eta) noexcept
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrMeanDepthFromEtaExact (double z1, double z2, double z3, double eta) noexcept
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrStageAtWetFraction (double z1, double z2, double z3, double eps) noexcept
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrMeanDepthFromEta (double z1, double z2, double z3, double eta, double eps) noexcept
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrEtaFromMeanDepth (double z1, double z2, double z3, double mean_depth, double eps) noexcept
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrDryEta (double z1, double z2, double z3, double eps) noexcept
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrDEtaDMeanDepth (double z1, double z2, double z3, double eta, double eps) noexcept

Variables
constexpr double	openswmm::twoD::kVfrFlatRelief = 1.0e-9

Detailed Description

Volume–free-surface (VFR) closure for a planar-bed triangular cell.

Exact stage–storage relations for a cell whose bed is the plane through its three vertex elevations, after Begnudelli & Sanders (2006, 2007): the "volume/free-surface relationships" (VFRs) that make wetting and drying conservative and free of the flat-closure bias η = z̄ + V/A, which overstates the free surface of a partially wet cell by up to two-thirds of the cell relief and drives the water-climbs-uphill artifact (see plans/2d/2D_VFR_SOLVER_CLOSURE_PLAN.md).

With sorted vertex elevations z1 ≤ z2 ≤ z3, z̄ = (z1+z2+z3)/3, and h̄ = V/A the cell-mean depth:

z1 < η ≤ z2 : h̄(η) = (η−z1)³ / (3(z2−z1)(z3−z1)) z2 < η ≤ z3 : h̄(η) = (η−z̄) + (z3−η)³ / (3(z3−z1)(z3−z2)) η ≥ z3 : h̄(η) = η − z̄ (fully wet, flat)

The inverse η(h̄) is exact (closed-form cube root on the lower branch, safeguarded Newton on the upper). For use inside the implicit (CVODE/ARKODE) solvers, where dη/dV = 1/A_wet must stay bounded as the cell dries, the inverse takes a wet-area-fraction floor ε: the exact relation is continued below wet fraction ε by its tangent line (slope 1/(εA)), keeping the closure C¹ and monotone with η(V=0) slightly above z1. ε = 0 gives the exact (unregularized) relation, used by the render path.

Header-only, dependency-free (<cmath> only): shared by the CPU solvers, the flux calculator, the vertex render reconstruction and (eventually) the Kokkos kernels — the single source of truth for the closure.

See also

plans/2d/2D_VFR_SOLVER_CLOSURE_PLAN.md

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n Apache-2.0

Macro Definition Documentation

OPENSWMM_KERNEL_FN

#define OPENSWMM_KERNEL_FN   inline