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
	Wetted-area fraction A_wet/A of the planar-bed cell at stage eta. Piecewise C0, monotone from 0 (η ≤ z1) to 1 (η ≥ z3). This is dh̄/dη. Inputs must be sorted (z1 <= z2 <= z3).
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrMeanDepthFromEtaExact (double z1, double z2, double z3, double eta) noexcept
	EXACT cell-mean depth h̄(η) of the planar-bed cell (per unit area; V = A·h̄). Returns 0 for η ≤ z1. Inputs must be sorted.
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrStageAtWetFraction (double z1, double z2, double z3, double eps) noexcept
	Stage η_s at which the wetted-area fraction equals eps (0 < eps < 1). Inputs must be sorted and non-flat (z3 − z1 ≥ kVfrFlatRelief).
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrMeanDepthFromEta (double z1, double z2, double z3, double eta, double eps) noexcept
	Regularized cell-mean depth h̄(η): exact for η ≥ η_s (wet fraction ≥ eps), tangent-line continuation below (slope eps), clamped at 0. eps == 0 gives the exact relation. The EXACT inverse of vfrEtaFromMeanDepth for the same eps, so head ↔ volume seeding round-trips (hotstart, reinitialize). Inputs must be sorted.
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrEtaFromMeanDepth (double z1, double z2, double z3, double mean_depth, double eps) noexcept
	Regularized free-surface elevation η(h̄) — the solver closure.
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrDryEta (double z1, double z2, double z3, double eps) noexcept
	Dry-cell free surface of the regularized closure: η(V = 0). This is the value a dry cell's head must be seeded with under CELL_CLOSURE = VFR so that head → volume seeding (vfrMeanDepthFromEta) returns exactly 0. Inputs must be sorted.
OPENSWMM_KERNEL_FN double	openswmm::twoD::vfrDEtaDMeanDepth (double z1, double z2, double z3, double eta, double eps) noexcept
	dη/dh̄ of the regularized closure at stage eta: 1/max(w(η), eps). Divide by the cell area A to get dη/dV (the preconditioner chain-rule factor; equals 1/A for a fully wet cell, matching the flat closure). Inputs must be sorted.

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 (standard math 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

Apache-2.0

Macro Definition Documentation

OPENSWMM_KERNEL_FN

#define OPENSWMM_KERNEL_FN   inline