Loading...
Searching...
No Matches
HydroCouple::Spatial::ICrossSection Class Referenceabstract

The shape of a channel at one place, as a function of stage. More...

#include <hydrocouplespatial.h>

Collaboration diagram for HydroCouple::Spatial::ICrossSection:

Public Member Functions

virtual ~ICrossSection ()=default
 
virtual CrossSectionKind kind () const =0
 How the producer holds this shape.
 
virtual double invertElevation () const =0
 Lowest elevation in the section (positive up).
 
virtual double topWidth (double stage) const =0
 Width of the water surface at stage.
 
virtual double storageArea (double stage) const =0
 Total wetted area at stage — everything holding water.
 
virtual double flowArea (double stage) const =0
 The conveying part of that area at stage.
 
virtual double wettedPerimeter (double stage) const =0
 Wetted perimeter of the conveying area at stage.
 
virtual void evaluate (std::span< const double > stages, std::span< double > topWidths, std::span< double > storageAreas, std::span< double > flowAreas, std::span< double > wettedPerimeters) const =0
 Evaluates the section at many stages in one call.
 
virtual int64_t stationCount () const =0
 Number of survey points, or 0 when the producer holds no points.
 
virtual void stations (double *stations, double *elevations) const =0
 The survey points, ordered left bank to right bank.
 

Detailed Description

The shape of a channel at one place, as a function of stage.

Why this is not a list of survey points. The three model families this has to serve do not store the same thing. HEC-RAS and SWMM hold station and elevation pairs across the section. CE-QUAL-W2 holds width as a step function of elevation and has no stations at all. A closed conduit has a formula and neither. An interface built around survey points would force two of the three to invent points they do not have, and every consumer to re-integrate them.

So the contract is the derived quantities, which all three can answer exactly from what they actually hold. stationCount() is offered for the producers that do have points, and returns zero for the ones that do not — a consumer must be able to work without them.

Flow area and storage area are separate on purpose. They differ wherever part of the section holds water without conveying it: over a floodplain beyond the bank stations, behind a levee, in a backwater. A model that uses the storage area for momentum overstates conveyance in exactly the places where the distinction is largest. Splitting them here means a partner cannot collapse the two by accident, and has to say which one it means.

Conventions. Elevations are positive up in the vertical datum the parent geometry's ISpatialReferenceSystem declares, and every length here — stages, elevations, widths, stations — is in that system's verticalDistanceUnits() (areas in its square); a section never carries units of its own. stage throughout is a water-surface elevation in that datum, not a depth. Below invertElevation() every quantity is zero rather than negative or an error, because a dry section is an ordinary state.

At exactly invertElevation(), the areas are zero but topWidth() and wettedPerimeter() take their limiting values from above — for a flat-bottomed section, the width of that bottom, not zero. The distinction looks like pedantry over a measure-zero case and is not: a wave celerity of sqrt(g A / T) and any wetted-perimeter friction law both divide by these at the moment a channel begins to fill, and a producer that returned zero would hand its partner an infinity exactly at the wet front. This paragraph exists because two independent implementations of this interface both chose the limiting value and the closed form checked against them did not, which is a question the specification should have already answered.

Constructor & Destructor Documentation

◆ ~ICrossSection()

virtual HydroCouple::Spatial::ICrossSection::~ICrossSection ( )
virtualdefault

Member Function Documentation

◆ evaluate()

virtual void HydroCouple::Spatial::ICrossSection::evaluate ( std::span< const double > stages,
std::span< double > topWidths,
std::span< double > storageAreas,
std::span< double > flowAreas,
std::span< double > wettedPerimeters ) const
pure virtual

Evaluates the section at many stages in one call.

The per-stage accessors above sit inside a 1-D solver's Newton loop, one virtual call per node per iteration; a partner that would rather tabulate once and interpolate asks here. Every output span is either empty (not wanted) or the length of stages.

Parameters
[in]stagesWater-surface elevations to evaluate at.
[out]topWidthsReceives topWidth() per stage, or empty.
[out]storageAreasReceives storageArea() per stage, or empty.
[out]flowAreasReceives flowArea() per stage, or empty.
[out]wettedPerimetersReceives wettedPerimeter() per stage, or empty.

◆ flowArea()

virtual double HydroCouple::Spatial::ICrossSection::flowArea ( double stage) const
nodiscardpure virtual

The conveying part of that area at stage.

Never greater than storageArea(). Equal to it for a section with no ineffective flow area, which is the common case and not the general one.

◆ invertElevation()

virtual double HydroCouple::Spatial::ICrossSection::invertElevation ( ) const
nodiscardpure virtual

Lowest elevation in the section (positive up).

◆ kind()

virtual CrossSectionKind HydroCouple::Spatial::ICrossSection::kind ( ) const
nodiscardpure virtual

How the producer holds this shape.

◆ stationCount()

virtual int64_t HydroCouple::Spatial::ICrossSection::stationCount ( ) const
nodiscardpure virtual

Number of survey points, or 0 when the producer holds no points.

◆ stations()

virtual void HydroCouple::Spatial::ICrossSection::stations ( double * stations,
double * elevations ) const
pure virtual

The survey points, ordered left bank to right bank.

Parameters
[out]stationsBuffer of at least stationCount() doubles.
[out]elevationsBuffer of at least stationCount() doubles.

Does nothing when stationCount() is 0. A consumer that needs a shape regardless must use the area and width accessors, which every producer answers.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ storageArea()

virtual double HydroCouple::Spatial::ICrossSection::storageArea ( double stage) const
nodiscardpure virtual

Total wetted area at stage — everything holding water.

◆ topWidth()

virtual double HydroCouple::Spatial::ICrossSection::topWidth ( double stage) const
nodiscardpure virtual

Width of the water surface at stage.

◆ wettedPerimeter()

virtual double HydroCouple::Spatial::ICrossSection::wettedPerimeter ( double stage) const
nodiscardpure virtual

Wetted perimeter of the conveying area at stage.

Paired with flowArea() rather than storageArea(), so that their ratio is the hydraulic radius a friction law expects.


The documentation for this class was generated from the following file: