OpenSWMM Engine  6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
Loading...
Searching...
No Matches
openswmm::xsect Namespace Reference

Namespaces

namespace  shape
 The analytic shape formulas — the single definition of each.
 

Classes

struct  LocateLut
 
struct  XsectEval
 The geometry layer itself, parameterized on where its tables live. More...
 
struct  XsectTables
 

Enumerations

enum class  LutId : int {
  Y_Gothic = 0 ,
  Y_Catenary ,
  Y_SemiEllip ,
  Y_SemiCirc ,
  A_HorizEllipse ,
  A_VertEllipse ,
  A_Arch ,
  S_Circ ,
  S_Egg ,
  S_Horseshoe ,
  S_Gothic ,
  S_Catenary ,
  S_SemiEllip ,
  S_BasketHandle ,
  S_SemiCirc ,
  COUNT
}
 Pointers to the shared geometry tables, in whichever memory space the consumer runs in. More...
 

Functions

double getAofY (const XSectParams &xs, double y)
 Query native wetted area from depth through the shared host evaluator.
 
double getRofY (const XSectParams &xs, double y)
 Query native hydraulic radius from depth through the shared host evaluator.
 
double getWofY (const XSectParams &xs, double y)
 Query native top width from depth through the shared host evaluator.
 
double getYofA (const XSectParams &xs, double a)
 Query native depth from area through the shared host evaluator.
 
double getSofA (const XSectParams &xs, double a)
 Query native section factor from area through the shared host evaluator.
 
double getRofA (const XSectParams &xs, double a)
 Query native hydraulic radius from area through the shared host evaluator.
 
double getdSdA (const XSectParams &xs, double a)
 Query native section-factor derivative with respect to area through the shared host evaluator.
 
double getAofS (const XSectParams &xs, double s_factor)
 Query native area from section factor through the shared host evaluator.
 
double getAmax (const XSectParams &xs)
 Read the built-in area-at-maximum-conveyance ratio.
 
double getYcrit (const XSectParams &xs, double q)
 Query native critical depth from discharge through the shared host evaluator.
 
bool isOpen (int type)
 Classify a kernel shape using the legacy open-section set.
 
int setParams (XSectParams &xs, int type, const double p[], double ucf)
 Derive native full-flow geometry from authored shape dimensions.
 
double lookup (double x, const double *table, int n_items)
 Interpolate a borrowed equally spaced normalized geometry table.
 
double invLookup (double y, const double *table, int n_items, const LocateLut *lut=nullptr)
 Invert a borrowed normalized geometry table including the legacy declining top.
 
int locate (double y, const double *table, int n)
 Find a lower bracket in a nondecreasing geometry table.
 
double getYcircular (double alpha)
 Compute normalized circular depth from area ratio.
 
double getScircular (double alpha)
 Compute normalized circular section factor from area ratio.
 
const XsectTables & hostTables ()
 Borrow host pointers, lengths and inverse maps for every built-in geometry table.
 
const XsectEval & hostEval ()
 Borrow the immutable host evaluator bound to process-lifetime tables.
 
double lookup_exact (double x, const double *t, int n) noexcept
 Interpolate a normalized geometry table with the legacy arithmetic grouping.
 
double lookup_fast (double x, const double *t, int n) noexcept
 Interpolate normalized geometry using reciprocal multiplication and endpoint clamps.
 
double norm_x (double depth, double param) noexcept
 Normalize a depth with the selected exact or fast-lookup operand convention.
 
double norm_lookup (double depth, double param, const double *t, int n) noexcept
 Normalize a depth and dispatch the build-selected table interpolation.
 
int lut_bucket (const LocateLut &L, double y) noexcept
 Map a value to one of64 locate-acceleration buckets.
 
int locate_bisect (double y, const double *table, int jLast) noexcept
 Find a lower bracketing index in a nondecreasing table.
 
void build_locate_lut (LocateLut &L, const double *table, int jLast) noexcept
 Build a byte-indexed acceleration map for a monotone geometry table.
 
int locate_lut (double y, const double *table, int jLast, const LocateLut &L) noexcept
 Find the same lower bracket using a prebuilt bucket map.
 
int locate_maybe_lut (double y, const double *table, int jLast, const LocateLut *L) noexcept
 Use a matching enabled bucket map or fall back to plain bisection.
 
void build_invlookup_lut (LocateLut &L, const double *table, int n_items) noexcept
 Build a map for the actual truncated extent used by inverse geometry lookup.
 

Variables

constexpr double TINY = 1.0e-6
 
constexpr double PI = 3.141592654
 
constexpr double GRAVITY = 32.2
 
constexpr double RECT_ALFMAX = 0.97
 
constexpr double RECT_TRIANG_ALFMAX = 0.98
 
constexpr double RECT_ROUND_ALFMAX = 0.98
 

Enumeration Type Documentation

◆ LutId

enum class openswmm::xsect::LutId : int
strong

Pointers to the shared geometry tables, in whichever memory space the consumer runs in.

Plain POD: trivially copyable into a device kernel by value. The member names are deliberately identical to the xsect_tables:: symbols they bind to, so the moved bodies differ from the originals by exactly one token.

The tables invLookup() inverts, and so the ones that carry a LocateLut (plan XSECT_LOOKUP_ACCEL §4 item A1).

Every other shared table is only ever read forward, where the index is a divide-and-truncate and there is no search to accelerate. Keeping the maps in one array indexed by this enum costs XsectTables a single pointer instead of fifteen, and keeps the host binding (XSection.cpp hostTables) and any device binding to one block to copy.

Enumerator
Y_Gothic 
Y_Catenary 
Y_SemiEllip 
Y_SemiCirc 
A_HorizEllipse 
A_VertEllipse 
A_Arch 
S_Circ 
S_Egg 
S_Horseshoe 
S_Gothic 
S_Catenary 
S_SemiEllip 
S_BasketHandle 
S_SemiCirc 
COUNT 

Function Documentation

◆ build_invlookup_lut()

void openswmm::xsect::build_invlookup_lut ( LocateLut & L,
const double * table,
int n_items )
inlinenoexcept

Build a map for the actual truncated extent used by inverse geometry lookup.

When table[n-3]>table[n-1], excludes the two nonmonotone top rows before building. Does not alter source data or accelerate the inverse lookup's separate top-branch interpolation.

Parameters
[out]LReset/filled map; NULL/short source disables it.
[in]tableOptional readable n_items-entry finite well-scaled geometry table; same safety preconditions as build_locate_lut.
[in]n_itemsLogical table length; fewer than4 disables map.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ build_locate_lut()

void openswmm::xsect::build_locate_lut ( LocateLut & L,
const double * table,
int jLast )
inlinenoexcept

Build a byte-indexed acceleration map for a monotone geometry table.

Refuses nonmonotone comparisons (including NaN) and nonpositive span by leaving scale0. Caller supplies finite well-scaled geometry values; infinities/underflow/overflow are not independently guarded. Builds65 bucket lower bounds without allocation. Rebuild after table values change.

Parameters
[out]LReset to disabled first, then populated in place when eligible.
[in]tableNULL disables; otherwise readable0..jLast table with finite bounded values making scale/mapped products finite and int-representable.
[in]jLastInclusive extent; only2..254 can enable the map, otherwise disabled.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getAmax()

double openswmm::xsect::getAmax ( const XSectParams & xs)

Read the built-in area-at-maximum-conveyance ratio.

Returns a ratio rather than the physical custom/irregular xs.a_bot area.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
Returns
Dimensionless built-in ratio for kernel codes0..25, otherwise1.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getAofS()

double openswmm::xsect::getAofS ( const XSectParams & xs,
double s_factor )

Query native area from section factor through the shared host evaluator.

Nonpositive factor/DUMMY returns0; table inverse or Newton candidate is returned without a convergence flag. Direct-table normalized input precedes local s_max cap, preserving current legacy arithmetic. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]s_factorFinite nonnegative factor in xs.s_full conventions.
Returns
Computed ft2.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getAofY()

double openswmm::xsect::getAofY ( const XSectParams & xs,
double y )

Query native wetted area from depth through the shared host evaluator.

Nonpositive depth/full depth returns0; tabulated shapes hold endpoints, analytic open profiles can extend beyond full depth. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]yFinite nonnegative depth ft.
Returns
Computed ft2.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getdSdA()

double openswmm::xsect::getdSdA ( const XSectParams & xs,
double a )

Query native section-factor derivative with respect to area through the shared host evaluator.

Uses analytic/table-segment derivative or normalized-area finite difference; no complete area/finiteness validation. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]aFinite nonnegative wetted area ft2.
Returns
Computed section-factor units per ft2.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getRofA()

double openswmm::xsect::getRofA ( const XSectParams & xs,
double a )

Query native hydraulic radius from area through the shared host evaluator.

Nonpositive area returns0; unsupported/DUMMY positive area is invalid for generic recursive radius dispatch. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]aFinite nonnegative wetted area ft2.
Returns
Computed ft.
Here is the call graph for this function:

◆ getRofY()

double openswmm::xsect::getRofY ( const XSectParams & xs,
double y )

Query native hydraulic radius from depth through the shared host evaluator.

Requires valid positive full geometry; optional missing radius table returns0. Unsupported/DUMMY positive-area radius queries are outside the valid domain. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]yFinite nonnegative depth ft.
Returns
Computed ft.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getScircular()

double openswmm::xsect::getScircular ( double alpha)

Compute normalized circular section factor from area ratio.

Parameters
[in]alphaFinite area/full-area ratio; <=0 returns0, >=1 returns1.
Returns
S/Sfull via small-area approximation or angle formula; no separate convergence status.
Here is the call graph for this function:

◆ getSofA()

double openswmm::xsect::getSofA ( const XSectParams & xs,
double a )

Query native section factor from area through the shared host evaluator.

Ordinary units are ft^(8/3), with the FORCE_MAIN full-factor convention described on XSectParams. Uses specialized S tables/crown corrections or A*R^(2/3); valid non-DUMMY supported geometry is required. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]aFinite nonnegative wetted area ft2.
Returns
Computed native section-factor units.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getWofY()

double openswmm::xsect::getWofY ( const XSectParams & xs,
double y )

Query native top width from depth through the shared host evaluator.

Shape-specific dry/crown rules apply; closed rectangle returns0 at exact full depth. Missing optional width table/unsupported code returns0. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]yFinite nonnegative depth ft.
Returns
Computed ft.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getYcircular()

double openswmm::xsect::getYcircular ( double alpha)

Compute normalized circular depth from area ratio.

Parameters
[in]alphaFinite area/full-area ratio; <=0 returns0, >=1 returns1.
Returns
Depth/full-depth via small-area approximation or angle Newton solve; iteration exhaustion uses empirical angle guess.
Here is the call graph for this function:

◆ getYcrit()

double openswmm::xsect::getYcrit ( const XSectParams & xs,
double q )

Query native critical depth from discharge through the shared host evaluator.

Nonpositive discharge/DUMMY returns0. Uses analytic,25-interval enumeration or Ridder solve; upper depth capped y_full and no separate root-failure status. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]qFinite nonnegative discharge cfs; caller prevents q*q overflow.
Returns
Computed ft.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getYofA()

double openswmm::xsect::getYofA ( const XSectParams & xs,
double a )

Query native depth from area through the shared host evaluator.

Nonpositive area returns0. Uses analytic inverses, direct Y tables or inversion of borrowed A tables; no universal above-full clamp. No display-unit conversion, allocation on normal query path or ownership transfer.

Parameters
[in]xsBorrowed initialized native geometry with kernel shape numbering and live applicable tables/LUTs; queried physical shape must be supported.
[in]aFinite nonnegative wetted area ft2.
Returns
Computed ft.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ hostEval()

const XsectEval & openswmm::xsect::hostEval ( )

Borrow the immutable host evaluator bound to process-lifetime tables.

Local-static first initialization binds hostTables; normal queries perform no evaluator allocation or state mutation.

Returns
Static read-only evaluator reference; safe for concurrent read-only queries with valid independently owned section data.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ hostTables()

const XsectTables & openswmm::xsect::hostTables ( )

Borrow host pointers, lengths and inverse maps for every built-in geometry table.

Initialized once through thread-safe local static; does not copy/allocate the table sample arrays. Device code requires its own accessible bindings.

Returns
Static immutable table-binding record valid for process lifetime; arrays remain statically owned.

The host-bound table set and evaluator: hostTables() binds every pointer straight back to the xsect_tables:: arrays, so hostEval() reproduces the pre-extraction code exactly. A device consumer builds its own pair over device copies of the same arrays.

Here is the caller graph for this function:

◆ invLookup()

double openswmm::xsect::invLookup ( double y,
const double * table,
int n_items,
const LocateLut * lut = nullptr )

Invert a borrowed normalized geometry table including the legacy declining top.

Parameters
[in]yFinite dependent table-unit value.
[in]tableReadable n_items entries, monotone except the supported two-row declining top.
[in]n_itemsLogical count>=4.
[in]lutOptional live map built for the same unchanged table/search extent.
Returns
Normalized coordinate clamped0..1; no pointer/count/finiteness validation.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ isOpen()

bool openswmm::xsect::isOpen ( int type)

Classify a kernel shape using the legacy open-section set.

Parameters
[in]typeKernel XSectShape ordinal, not model-storage enum.
Returns
True for DUMMY/RECT_OPEN/TRAPEZOIDAL/TRIANGULAR/PARABOLIC/POWERFUNC/IRREGULAR/STREET_XSECT; false otherwise.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ locate()

int openswmm::xsect::locate ( double y,
const double * table,
int n )

Find a lower bracket in a nondecreasing geometry table.

Parameters
[in]yQuery in table units, endpoint held; NaN resolves index0.
[in]tableReadable nondecreasing indices0..n.
[in]nNonnegative inclusive last index, rather than entry count.
Returns
Bracket index clamped0..n.
Here is the call graph for this function:

◆ locate_bisect()

int openswmm::xsect::locate_bisect ( double y,
const double * table,
int jLast )
inlinenoexcept

Find a lower bracketing index in a nondecreasing table.

Interior equal values follow the bisection comparison; all-equal/bottom endpoint returns0. No interpolation or table validation.

Parameters
[in]yQuery in table units; endpoint queries clamp, NaN resolves to0.
[in]tableBorrowed ascending/nondecreasing table with readable indices0..jLast; lifetime covers query.
[in]jLastNonnegative inclusive final search index; caller prevents midpoint integer overflow.
Returns
Zero-based lower bracket,0 at/below first and jLast at/above last.
Here is the caller graph for this function:

◆ locate_lut()

int openswmm::xsect::locate_lut ( double y,
const double * table,
int jLast,
const LocateLut & L )
inlinenoexcept

Find the same lower bracket using a prebuilt bucket map.

Does not validate map identity/extent; stale maps can produce incorrect or unsafe brackets.

Parameters
[in]yQuery in table units; NaN/below-first returns0 and above-last returns jLast.
[in]tableBorrowed ascending/nondecreasing table with readable indices0..jLast; lifetime covers query.
[in]jLastNonnegative inclusive final search index; caller prevents midpoint integer overflow.
[in]LBorrowed enabled map built from this unchanged table and extent; interior mapped expression must fit int.
Returns
Lower bracket after bucket narrowing and exact bisection comparisons.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ locate_maybe_lut()

int openswmm::xsect::locate_maybe_lut ( double y,
const double * table,
int jLast,
const LocateLut * L )
inlinenoexcept

Use a matching enabled bucket map or fall back to plain bisection.

Parameters
[in]yQuery in table units; same value-domain requirements as selected implementation.
[in]tableBorrowed ascending/nondecreasing table with readable indices0..jLast; lifetime covers query.
[in]jLastNonnegative inclusive final search index; caller prevents midpoint integer overflow.
[in]LOptional borrowed map; scale>0 and matching j_last select it. Caller ensures table identity/content still match.
Returns
Bracketing index from locate_lut or locate_bisect; no interpolation.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ lookup()

double openswmm::xsect::lookup ( double x,
const double * table,
int n_items )

Interpolate a borrowed equally spaced normalized geometry table.

Parameters
[in]xNormalized coordinate; nonpositive/NaN selects first, >1 selects final entry.
[in]tableReadable n_items-entry table, n_items>=4 for low-end quadratic lookahead.
[in]n_itemsLogical count>=4.
Returns
Table-unit value using the exact legacy shared lookup, with lower-result floor0 for interior interpolation.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ lookup_exact()

double openswmm::xsect::lookup_exact ( double x,
const double * t,
int n )
inlinenoexcept

Interpolate a normalized geometry table with the legacy arithmetic grouping.

Uses exact division and a positive low-end quadratic refinement. No negative-input clamp; caller must prevent unsafe indices/nonfinite casts. No allocation or ownership transfer; bitwise legacy agreement requires compatible FP/compiler settings.

Parameters
[in]xFinite nonnegative normalized coordinate, normally0..1; x/(1/(n-1)) must fit int. Values>=1 return final entry.
[in]tBorrowed readable n-entry equally spaced table on0..1; n>=4 for low-end quadratic lookahead.
[in]nLogical entry count>=4; no local validation.
Returns
Interpolated dependent value in table units, floored0, or final value at/above upper extent.
Here is the caller graph for this function:

◆ lookup_fast()

double openswmm::xsect::lookup_fast ( double x,
const double * t,
int n )
inlinenoexcept

Interpolate normalized geometry using reciprocal multiplication and endpoint clamps.

Faster arithmetic can differ by ULPs from lookup_exact; no NaN guard before integer cast. No allocation or table mutation.

Parameters
[in]xNon-NaN normalized coordinate; values below0/above1, including infinities, clamp to endpoints.
[in]tBorrowed readable n-entry equally spaced table; n>=4 for quadratic lookahead.
[in]nLogical count>=4, caller-validated.
Returns
Interpolated table-unit value floored0, with final table value at upper endpoint.
Here is the caller graph for this function:

◆ lut_bucket()

int openswmm::xsect::lut_bucket ( const LocateLut & L,
double y )
inlinenoexcept

Map a value to one of64 locate-acceleration buckets.

Clamping occurs after the integer cast; it does not make nonfinite or enormous inputs safe. No table lookup or mutation.

Parameters
[in]LBorrowed initialized map; scale positive and mapped query expression representable as int.
[in]yValue in the same units as L.t0; (y-t0)*scale must be finite/int-representable.
Returns
Truncated bucket index clamped into0..63.
Here is the caller graph for this function:

◆ norm_lookup()

double openswmm::xsect::norm_lookup ( double depth,
double param,
const double * t,
int n )
inlinenoexcept

Normalize a depth and dispatch the build-selected table interpolation.

Parameters
[in]depthDepth in consistent native length units, finite and safely normalizable.
[in]paramDefault full-depth denominator or FAST_LOOKUP reciprocal, matching norm_x build convention.
[in]tBorrowed readable normalized geometry table with n>=4 entries.
[in]nLogical entry count>=4.
Returns
Dependent table-unit value via lookup_exact by default or lookup_fast when opted in.
Here is the call graph for this function:

◆ norm_x()

double openswmm::xsect::norm_x ( double depth,
double param )
inlinenoexcept

Normalize a depth with the selected exact or fast-lookup operand convention.

The fast branch does not catch NaN multiplication. Supplying a full depth to a reciprocal build (or reverse) silently misnormalizes; no units or finiteness validation.

Parameters
[in]depthDepth in the same length convention as full depth; finite inputs supplied by caller.
[in]paramDefault build: positive full depth; FAST_LOOKUP build: its precomputed reciprocal.
Returns
Default depth/param when both positive else0; fast depth*param clamped0..1.
Here is the caller graph for this function:

◆ setParams()

int openswmm::xsect::setParams ( XSectParams & xs,
int type,
const double p[],
double ucf )

Derive native full-flow geometry from authored shape dimensions.

Trapezoid uses p1 bottom width,p2/p3 side slopes; triangle/parabola/power use height/width with power exponent p2. Standard ellipse/arch code selects inch-based catalogue dimensions; otherwise custom dimensions apply. Arc radius is raised to at least width/2. FORCE_MAIN retains p1 as C/roughness without conversion and uses R^0.63 full factor. This is not complete validation: many nonpositive/nonfinite dimensions can return0, and -1 can leave partial fields changed.

Parameters
[in,out]xsBorrowed destination; type is assigned first, applicable geometry fields change incrementally and unrelated fields/pointers are retained.
[in]typeKernel XSectShape ordinal. Table-backed IRREGULAR/CUSTOM/STREET, DUMMY and unknown codes change only type and return0.
[in]pReadable four-double shape parameter span. Slot0 is height/diameter or standard-size code; slot1 width, sediment depth or FORCE_MAIN roughness; slot2 exponent, arc radius, excluded-bank count or standard ellipse/arch code; slot3 second trapezoid side slope. Caller supplies shape-valid finite values.
[in]ucfPositive finite authored-length-units per native ft; length slots divide by it, dimensionless slopes/codes/exponents remain unscaled.
Returns
0 after a handled/default branch, -1 for selected fill/rectangle/arc/standard-size constraints.
Here is the call graph for this function:
Here is the caller graph for this function:

Variable Documentation

◆ GRAVITY

double openswmm::xsect::GRAVITY = 32.2
inlineconstexpr

◆ PI

double openswmm::xsect::PI = 3.141592654
inlineconstexpr

◆ RECT_ALFMAX

double openswmm::xsect::RECT_ALFMAX = 0.97
inlineconstexpr

◆ RECT_ROUND_ALFMAX

double openswmm::xsect::RECT_ROUND_ALFMAX = 0.98
inlineconstexpr

◆ RECT_TRIANG_ALFMAX

double openswmm::xsect::RECT_TRIANG_ALFMAX = 0.98
inlineconstexpr

◆ TINY

double openswmm::xsect::TINY = 1.0e-6
inlineconstexpr