NGen
Loading...
Searching...
No Matches
HY_CatchmentArea Class Reference

The two-dimensional realization of a catchment: the face it covers. More...

#include <HY_CatchmentArea.hpp>

+ Inheritance diagram for HY_CatchmentArea:
+ Collaboration diagram for HY_CatchmentArea:

Public Types

enum class  Quantity {
  depth ,
  volume ,
  volumetric_flow
}
 A quantity a perspective can express its value as, each in one canonical unit. More...
 

Public Member Functions

 HY_CatchmentArea ()
 
 HY_CatchmentArea (std::string catchment_id, std::shared_ptr< realization::Formulation > formulation, std::optional< double > area_sqkm=std::nullopt, std::shared_ptr< const geojson::geometry > bounds=nullptr)
 
 HY_CatchmentArea (std::string catchment_id, std::shared_ptr< realization::Formulation > formulation, const geojson::Feature &feature, hy_features::attributes::AreaSource preferred=hy_features::attributes::AreaSource::attribute)
 Realize a catchment from the hydrofabric feature describing it.
 
virtual ~HY_CatchmentArea ()
 
std::optional< double > area_sqkm () const override
 The areal extent of this feature, in square kilometers, where the perspective has one.
 
const std::shared_ptr< const geojson::geometry > & get_bounds () const
 The geometry describing this face, empty where no hydrofabric feature backs it.
 
Response get_response (time_step_t t_index, time_step_t t_delta) override
 The value representing the state of this feature after one time step.
 
const std::shared_ptr< realization::Formulation > & get_formulation () const
 The model producing this feature's values, or nullptr where the feature is not modeled.
 
const std::string & get_catchment_id () const
 The id this feature shares with the catchment it realizes.
 
std::shared_ptr< HY_Catchment > realize (std::vector< std::string > inflows, std::vector< std::string > outflows, long layer=0)
 Build the catchment this feature is a perspective of, and bind the two together.
 
std::shared_ptr< HY_Catchment > get_realized_catchment () const
 The catchment this feature realizes, whose inflow and outflow nexuses it shares.
 

Static Public Attributes

static constexpr std::size_t quantity_count = 3
 How many Quantity there are.
 

Protected Attributes

std::string catchment_id
 
std::shared_ptr< realization::Formulation > formulation
 
unsigned long id_number
 

Private Attributes

std::shared_ptr< const geojson::geometry > bounds
 Shared with the feature this was realized from; const, so neither can surprise the other.
 
std::optional< double > area
 
std::weak_ptr< HY_Catchment > realized_catchment
 

Detailed Description

The two-dimensional realization of a catchment: the face it covers.

Topologically a face bounded by catchment divide and flowpath edges, so this is the perspective to ask for an areal extent – the denominator when a value is distributed over the catchment.

Member Enumeration Documentation

◆ Quantity

enum class HY_CatchmentRealization::Quantity
stronginherited

A quantity a perspective can express its value as, each in one canonical unit.

Unit conversion should be handled at a higher level, outside of the perspective itself.

Enumerator
depth 

Meters.

volume 

Cubic meters, over the step.

volumetric_flow 

Cubic meters per second.

Constructor & Destructor Documentation

◆ HY_CatchmentArea() [1/3]

HY_CatchmentArea::HY_CatchmentArea ( )

◆ HY_CatchmentArea() [2/3]

HY_CatchmentArea::HY_CatchmentArea ( std::string catchment_id,
std::shared_ptr< realization::Formulation > formulation,
std::optional< double > area_sqkm = std::nullopt,
std::shared_ptr< const geojson::geometry > bounds = nullptr )
Parameters
catchment_idThe identity of the catchment this realizes.
formulationThe model producing this feature's values, or nullptr if unmodeled.
area_sqkmThe extent of the face, empty where it is not known.
boundsThe geometry describing the face, empty where there is none.

◆ HY_CatchmentArea() [3/3]

HY_CatchmentArea::HY_CatchmentArea ( std::string catchment_id,
std::shared_ptr< realization::Formulation > formulation,
const geojson::Feature & feature,
hy_features::attributes::AreaSource preferred = hy_features::attributes::AreaSource::attribute )

Realize a catchment from the hydrofabric feature describing it.

A convenience over the constructor above for the common case, taking the feature apart so a caller does not have to: the extent comes from hy_features::attributes::area_sqkm, the face from the feature's own geometry. What is kept is the same either way – an extent and a geometry, never the feature.

Parameters
catchment_idThe identity of the catchment this realizes.
formulationThe model producing this feature's values, or nullptr if unmodeled.
featureThe hydrofabric feature this catchment is realized from.
preferredWhich of the two area sources to consult first.
Exceptions
std::invalid_argumentIf the feature carries neither an area attribute nor a divide.

◆ ~HY_CatchmentArea()

HY_CatchmentArea::~HY_CatchmentArea ( )
virtual

Member Function Documentation

◆ area_sqkm()

std::optional< double > HY_CatchmentArea::area_sqkm ( ) const
inlineoverridevirtual

The areal extent of this feature, in square kilometers, where the perspective has one.

A face has an area, and so does the edge bounding that face; the edge running through it has a length instead. Empty therefore says the perspective has no extent to give, never that the hydrofabric withheld one: a catchment whose hydrofabric carries no extent is refused when the realization is built, so it does not reach here.

Reimplemented from HY_CatchmentRealization.

References area.

◆ get_bounds()

const std::shared_ptr< const geojson::geometry > & HY_CatchmentArea::get_bounds ( ) const
inline

The geometry describing this face, empty where no hydrofabric feature backs it.

Shared with the feature it was read from rather than copied out of it: a divide runs to thousands of coordinates, and holding one per realization would duplicate what the fabric already has. A handle rather than a reference, so a consumer that outlives this realization – a domain layer resampling onto the catchment – can keep the divide after both this and the feature collection are gone.

The variant, not a polygon: a feature may describe its face as either a Polygon or a MultiPolygon, and narrowing to one of them is what would force a copy of the other.

References bounds.

◆ get_catchment_id()

const std::string & HY_CatchmentRealization::get_catchment_id ( ) const
inlineinherited

The id this feature shares with the catchment it realizes.

References HY_CatchmentRealization::catchment_id.

Referenced by get_response(), and HY_CatchmentRealization::get_response().

◆ get_formulation()

const std::shared_ptr< realization::Formulation > & HY_CatchmentRealization::get_formulation ( ) const
inlineinherited

The model producing this feature's values, or nullptr where the feature is not modeled.

References HY_CatchmentRealization::formulation.

◆ get_realized_catchment()

std::shared_ptr< HY_Catchment > HY_CatchmentRealization::get_realized_catchment ( ) const
inherited

The catchment this feature realizes, whose inflow and outflow nexuses it shares.

Null until realize has been called.

References HY_CatchmentRealization::realized_catchment.

◆ get_response()

HY_CatchmentArea::Response HY_CatchmentArea::get_response ( time_step_t t_index,
time_step_t t_delta )
overridevirtual

The value representing the state of this feature after one time step.

E.g. depth, depth spread over the face's extent, and the rate with respect to the time step.

Exceptions
std::runtime_errorIf this feature has no formulation attached, or has no extent to spread the depth over.

Reimplemented from HY_CatchmentRealization.

References area, HY_CatchmentRealization::get_catchment_id(), HY_CatchmentRealization::get_response(), HY_CatchmentRealization::Response::in(), and HY_CatchmentRealization::Response::set().

◆ realize()

std::shared_ptr< HY_Catchment > HY_CatchmentRealization::realize ( std::vector< std::string > inflows,
std::vector< std::string > outflows,
long layer = 0 )
inherited

Build the catchment this feature is a perspective of, and bind the two together.

The catchment is given this realization's identity, so the pair cannot disagree about what it names. Each then holds the other: the catchment owns its realization, and the realization reaches back to the catchment for its nexuses.

One realization is one perspective of one catchment. Calling this again returns the catchment already built and does not apply the arguments; realizing a catchment from another perspective means another realization, which builds its own.

Parameters
inflowsIds of the nexuses contributing to the catchment.
outflowsIds of the nexuses the catchment contributes to.
layerThe hydrofabric layer the catchment belongs to.
Returns
The catchment, newly built or the one this realization already built.
Exceptions
std::bad_weak_ptrIf this realization is not already held by a shared_ptr.

References HY_CatchmentRealization::catchment_id, and HY_CatchmentRealization::realized_catchment.

Referenced by HY_CatchmentRealization_Test::SetUp().

Member Data Documentation

◆ area

std::optional<double> HY_CatchmentArea::area
private

Referenced by area_sqkm(), and get_response().

◆ bounds

std::shared_ptr<const geojson::geometry> HY_CatchmentArea::bounds
private

Shared with the feature this was realized from; const, so neither can surprise the other.

Referenced by get_bounds().

◆ catchment_id

std::string HY_CatchmentRealization::catchment_id
protectedinherited

◆ formulation

std::shared_ptr<realization::Formulation> HY_CatchmentRealization::formulation
protectedinherited

◆ id_number

unsigned long HY_CatchmentRealization::id_number
protectedinherited

◆ quantity_count

std::size_t HY_CatchmentRealization::quantity_count = 3
staticconstexprinherited

How many Quantity there are.

◆ realized_catchment

std::weak_ptr<HY_Catchment> HY_CatchmentRealization::realized_catchment
privateinherited

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