Depth_Formulation Class Reference

A formulation that answers a fixed depth. More...

Inheritance diagram for Depth_Formulation:

Collaboration diagram for Depth_Formulation:

Public Types
typedef long	time_step_t

Public Member Functions
	Depth_Formulation (double depth_m)
std::string	get_formulation_type () const override
void	create_formulation (boost::property_tree::ptree &, geojson::PropertyMap *) override
	See Identity.
void	create_formulation (geojson::PropertyMap) override
	See Identity.
void	check_mass_balance (const int &, const int &, const std::string &) const override
	See Identity.
void	checkpoint_state (const int &, const int &, const std::string &) const override
	Invoke the state-save side of the ngen BMI Serialization Protocol.
void	update (time_step_t, time_step_t) override
	Advance the backing model formulation through the given time step.
double	get_response (time_step_t, time_step_t) override
	Execute the backing model formulation for the given time step, where it is of the specified size, and return the response output.
std::vector< utils::OutputField >	get_output_fields () const override
	Get this formulation's output fields – name plus metadata (units, ...) – in the same order as the values returned by get_output_values_for_timestep.
std::vector< double >	get_output_values_for_timestep (int) override
	Get the output values for the given time step, positionally aligned with get_output_fields.
Identity
Three roles, not three independent names. A formulation has a subject, a locator, and an identity made of the two: subject – get_feature_id, the feature whose data this model reads and produces. Not unique: every model attached to one catchment shares it. Use it to reach forcing and feature data, to name a catchment in a message, and to substitute {{id}} in a config path. locator – get_id, where this sits in that feature's tree of models. The root of that tree is the feature itself, which is why the two hold the same string for a formulation built directly against one. Unique, and what Formulation_Manager keys on. identity – Bmi_Formulation::compound_id(), the locator together with what runs there. Unique, and what serialization records are keyed by, so a restore can tell it is loading into the same model the record came from. model_type_name is not a fourth identity; it is the component compound_id adds to the locator. catchment formulation domain layer module 0 of a multi on cat-27 subject cat-27 layer-1 cat-27 locator cat-27 layer-1 cat-27.0 identity cat-27:bmi_c_cfe layer-1:bmi_c_cfe cat-27.0:bmi_c_cfe:bmi_multi_x Subject and locator diverge only when one formulation composes another. The composer builds each module's locator from its own locator and that module's index within it, so a multi on cat-27 gives its first module cat-27.0; and it hands that module its own subject untouched, so the module still reads cat-27's forcing. Compose once more and the locator grows to cat-27.0.1 while the subject is still cat-27. A domain layer has no hydrofabric feature, but the layer is still what its model belongs to, so it stands as the subject.
std::string	get_id () const
	See Identity.
void	finalize ()
	Release resources of the given forcing provider.
const std::string &	get_feature_id () const
	The feature whose data this model reads and produces; see Identity.
void	set_feature_id (const std::string &feature_id)
	Associate this formulation with a feature other than the one it is named for.

Protected Member Functions
const std::vector< std::string > &	get_required_parameters () const override
geojson::PropertyMap	interpret_parameters (boost::property_tree::ptree &config, geojson::PropertyMap *global=nullptr)
void	validate_parameters (geojson::PropertyMap options)

Protected Attributes
std::string	id
	This formulation's locator; see get_id.
std::shared_ptr< data_access::GenericDataProvider >	forcing

Private Attributes
double	depth
std::string	feature_id
	This formulation's subject; see get_feature_id.

Detailed Description

A formulation that answers a fixed depth.

Formulation::get_response requests meters of its model, so a stub standing in for one answers in meters too. Everything else here is the interface, not the subject.

Member Typedef Documentation

time_step_t

long realization::Formulation::time_step_t

inherited

Constructor & Destructor Documentation

Depth_Formulation()

Depth_Formulation::Depth_Formulation ( double depth_m )

inlineexplicit

Member Function Documentation

check_mass_balance()

void Depth_Formulation::check_mass_balance ( const int & iteration, const int & total_steps, const std::string & timestamp ) const

inlineoverridevirtual

See Identity.

Implements realization::Formulation.

checkpoint_state()

void Depth_Formulation::checkpoint_state ( const int & iteration, const int & total_steps, const std::string & timestamp ) const

inlineoverridevirtual

Invoke the state-save side of the ngen BMI Serialization Protocol.

Called from the per-timestep driver (see core/Layer.cpp) alongside check_mass_balance. Implementations build a protocol Context from the arguments and the formulation's own compound identity, then forward to the NgenBmiProtocols container. Non-BMI formulations may implement as a no-op; unconfigured save protocols short-circuit inside run() so the cost is just the virtual dispatch.

Implements realization::Formulation.

create_formulation() [1/2]

void Depth_Formulation::create_formulation ( boost::property_tree::ptree & config, geojson::PropertyMap * global )

inlineoverridevirtual

See Identity.

Implements realization::Formulation.

create_formulation() [2/2]

void Depth_Formulation::create_formulation ( geojson::PropertyMap properties )

inlineoverridevirtual

See Identity.

Implements realization::Formulation.

finalize()

void realization::Formulation::finalize ( )

inherited

Release resources of the given forcing provider.

References realization::Formulation::forcing.

get_feature_id()

const std::string & realization::Formulation::get_feature_id ( ) const

inlineinherited

The feature whose data this model reads and produces; see Identity.

References realization::Formulation::feature_id.

Referenced by realization::Bmi_Module_Formulation::get_output_values_for_timestep(), realization::Bmi_Multi_Formulation::get_output_values_for_timestep(), realization::Bmi_Module_Formulation::get_response(), realization::Bmi_Multi_Formulation::get_response(), realization::Bmi_Multi_Formulation::init_nested_module(), and realization::Bmi_Module_Formulation::perform_set().

get_formulation_type()

std::string Depth_Formulation::get_formulation_type ( ) const

inlineoverridevirtual

Implements realization::Formulation.

get_id()

std::string realization::Formulation::get_id ( ) const

inlineinherited

See Identity.

References realization::Formulation::id.

Referenced by realization::Bmi_Multi_Formulation::create_multi_formulation().

get_output_fields()

std::vector< utils::OutputField > Depth_Formulation::get_output_fields ( ) const

inlineoverridevirtual

Get this formulation's output fields – name plus metadata (units, ...) – in the same order as the values returned by get_output_values_for_timestep.

The name is the output header field (configured, or defaulting to the output variable name); the units come from the same source that produces each value. So each field is positionally aligned with, and describes, the corresponding value.

Returns

The ordered output fields.

Implements realization::Formulation.

get_output_values_for_timestep()

std::vector< double > Depth_Formulation::get_output_values_for_timestep ( int timestep )

inlineoverridevirtual

Get the output values for the given time step, positionally aligned with get_output_fields.

Values are returned as raw doubles, with no formatting or precision applied by the formulation.

Parameters

timestep

The time step for which values are desired.

Returns

The output values for timestep, one per output column.

Implements realization::Formulation.

get_required_parameters()

const std::vector< std::string > & Depth_Formulation::get_required_parameters ( ) const

inlineoverrideprotectedvirtual

Implements realization::Formulation.

get_response()

double Depth_Formulation::get_response ( time_step_t t_index, time_step_t t_delta )

inlineoverridevirtual

Execute the backing model formulation for the given time step, where it is of the specified size, and return the response output.

Advances the model as update does, and additionally reduces its state to one value. Callers that only need the model stepped should use update instead. This function should be implemented and used when a single-value representation of the model's state is required.

Any inputs and additional parameters must be made available as instance members.

The response is a depth, in meters. Implementations are responsible for converting it: the BMI ones ask their model for "m" and convert from whatever it declares in GetVarUnits. HY_CatchmentRealization takes that for granted when it records the response as a depth, and HY_CatchmentArea multiplies it by an area in m^2.

Types should clearly document anything further about their particular response.

Parameters

t_index	The index of the time step for which to run model calculations.
t_delta	The duration, in seconds, of the time step for which to run model calculations.

Returns

The response output of the model for this time step, as a depth in meters.

Implements realization::Formulation.

References depth.

interpret_parameters()

geojson::PropertyMap realization::Formulation::interpret_parameters ( boost::property_tree::ptree & config, geojson::PropertyMap * global = nullptr )

protectedinherited

References realization::Formulation::validate_parameters().

Referenced by realization::Bmi_Module_Formulation::create_formulation(), and realization::Bmi_Multi_Formulation::create_formulation().

set_feature_id()

void realization::Formulation::set_feature_id ( const std::string & feature_id )

inlineinherited

Associate this formulation with a feature other than the one it is named for.

For a formulation composing others: a nested module's id names its position within the composition, so the composing formulation gives it the feature they share.

References realization::Formulation::feature_id.

update()

void Depth_Formulation::update ( time_step_t t_index, time_step_t t_delta )

inlineoverridevirtual

Advance the backing model formulation through the given time step.

Parameters

t_index	The index of the time step to run.
t_delta	The duration, in seconds, of that time step.

Implements realization::Formulation.

validate_parameters()

void realization::Formulation::validate_parameters ( geojson::PropertyMap options )

protectedinherited

References realization::Formulation::get_formulation_type(), and realization::Formulation::get_required_parameters().

Referenced by realization::Bmi_Multi_Formulation::create_multi_formulation(), realization::Bmi_Module_Formulation::inner_create_formulation(), and realization::Formulation::interpret_parameters().

Member Data Documentation

depth

double Depth_Formulation::depth

private

Referenced by get_response().

feature_id

std::string realization::Formulation::feature_id

privateinherited

This formulation's subject; see get_feature_id.

Referenced by realization::Formulation::get_feature_id(), and realization::Formulation::set_feature_id().

forcing

std::shared_ptr<data_access::GenericDataProvider> realization::Formulation::forcing

protectedinherited

Referenced by realization::Bmi_Multi_Formulation::create_multi_formulation(), realization::Bmi_Module_Formulation::determine_model_time_offset(), realization::Formulation::finalize(), realization::Bmi_Module_Formulation::get_provider_for_input_var(), realization::Bmi_Multi_Formulation::get_variable_time_begin(), realization::Bmi_Multi_Formulation::get_variable_time_end(), and realization::Bmi_Module_Formulation::inner_create_formulation().

id

std::string realization::Formulation::id

protectedinherited

This formulation's locator; see get_id.

Referenced by realization::Formulation::get_id().

---

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

• test/core/catchment/HY_CatchmentRealization_Test.cpp