A model attached to a feature: what is run for that feature, and what it emits. More...

#include <Formulation.hpp>

Inheritance diagram for realization::Formulation:

Collaboration diagram for realization::Formulation:

Public Types
typedef long	time_step_t

Public Member Functions

Formulation (const std::string &id, std::shared_ptr< data_access::GenericDataProvider > forcing)

Formulation (const std::string &id)

virtual ~Formulation ()

virtual std::string get_formulation_type () const =0

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.

virtual void create_formulation (boost::property_tree::ptree &config, geojson::PropertyMap *global=nullptr)=0

See Identity.

virtual void create_formulation (geojson::PropertyMap properties)=0

See Identity.

virtual void check_mass_balance (const int &iteration, const int &total_steps, const std::string &timestamp) const =0

See Identity.

virtual void checkpoint_state (const int &iteration, const int &total_steps, const std::string &timestamp) const =0

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

virtual void update (time_step_t t_index, time_step_t t_delta)=0

Advance the backing model formulation through the given time step.

virtual double get_response (time_step_t t_index, time_step_t t_delta)=0

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

virtual std::vector< utils::OutputField > get_output_fields () const =0

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

virtual std::vector< double > get_output_values_for_timestep (int timestep)=0

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

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
virtual const std::vector< std::string > &	get_required_parameters () const =0

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
std::string	feature_id
	This formulation's subject; see get_feature_id.

Detailed Description

A model attached to a feature: what is run for that feature, and what it emits.

A formulation is driven by a forcing provider, advances a time step at a time, and emits a set of named output fields. It is identified both by its own id and by the id of the feature it is attached to, which an HY_CatchmentRealization uses to realize that feature.

Member Typedef Documentation

◆ time_step_t

long realization::Formulation::time_step_t

Constructor & Destructor Documentation

◆ Formulation() [1/2]

realization::Formulation::Formulation	(	const std::string &	id,
		std::shared_ptr< data_access::GenericDataProvider >	forcing )

◆ Formulation() [2/2]

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

◆ ~Formulation()

virtual realization::Formulation::~Formulation ( )

inlinevirtual

Member Function Documentation

◆ check_mass_balance()

virtual void realization::Formulation::check_mass_balance	(	const int &	iteration,
		const int &	total_steps,
		const std::string &	timestamp ) const

pure virtual

See Identity.

Implemented in Depth_Formulation, realization::Bmi_Module_Formulation, and realization::Bmi_Multi_Formulation.

◆ checkpoint_state()

virtual void realization::Formulation::checkpoint_state	(	const int &	iteration,
		const int &	total_steps,
		const std::string &	timestamp ) const

pure virtual

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.

Implemented in Depth_Formulation, realization::Bmi_Module_Formulation, and realization::Bmi_Multi_Formulation.

◆ create_formulation() [1/2]

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

pure virtual

See Identity.

Implemented in Depth_Formulation, realization::Bmi_Module_Formulation, and realization::Bmi_Multi_Formulation.

◆ create_formulation() [2/2]

virtual void realization::Formulation::create_formulation ( geojson::PropertyMap properties )

pure virtual

See Identity.

Implemented in Depth_Formulation, realization::Bmi_Module_Formulation, and realization::Bmi_Multi_Formulation.

◆ finalize()

void realization::Formulation::finalize ( )

Release resources of the given forcing provider.

References forcing.

◆ get_feature_id()

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

inline

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

References 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()

virtual std::string realization::Formulation::get_formulation_type ( ) const

pure virtual

Implemented in Depth_Formulation, realization::Bmi_C_Formulation, realization::Bmi_Cpp_Formulation, and realization::Bmi_Multi_Formulation.

Referenced by realization::Bmi_Module_Formulation::get_value(), realization::Bmi_Module_Formulation::get_values(), realization::Bmi_Module_Formulation::update(), and validate_parameters().

◆ get_id()

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

inline

See Identity.

References id.

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

◆ get_output_fields()

virtual std::vector< utils::OutputField > realization::Formulation::get_output_fields ( ) const

pure virtual

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.

Implemented in Depth_Formulation, realization::Bmi_Module_Formulation, and realization::Bmi_Multi_Formulation.

◆ get_output_values_for_timestep()

virtual std::vector< double > realization::Formulation::get_output_values_for_timestep ( int timestep )

pure virtual

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.

Implemented in Depth_Formulation, realization::Bmi_Module_Formulation, and realization::Bmi_Multi_Formulation.

Referenced by ngen::DomainLayer::update_models().

◆ get_required_parameters()

virtual const std::vector< std::string > & realization::Formulation::get_required_parameters ( ) const

protectedpure virtual

Implemented in Depth_Formulation, realization::Bmi_Formulation, and realization::Bmi_Module_Formulation.

Referenced by validate_parameters().

◆ get_response()

virtual double realization::Formulation::get_response	(	time_step_t	t_index,
		time_step_t	t_delta )

pure virtual

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.

Implemented in Depth_Formulation, realization::Bmi_Module_Formulation, and realization::Bmi_Multi_Formulation.

Referenced by HY_CatchmentRealization::get_response().

◆ interpret_parameters()

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

protected

References 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 )

inline

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 feature_id.

◆ update()

virtual void realization::Formulation::update	(	time_step_t	t_index,
		time_step_t	t_delta )

pure virtual

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.

Implemented in Depth_Formulation, realization::Bmi_Formulation, realization::Bmi_Module_Formulation, and realization::Bmi_Multi_Formulation.

Referenced by ngen::DomainLayer::update_models().

◆ validate_parameters()

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

protected

References get_formulation_type(), and get_required_parameters().

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

Member Data Documentation

◆ feature_id

std::string realization::Formulation::feature_id

private

This formulation's subject; see get_feature_id.

Referenced by get_feature_id(), and set_feature_id().

◆ forcing

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

protected

Referenced by realization::Bmi_Multi_Formulation::create_multi_formulation(), realization::Bmi_Module_Formulation::determine_model_time_offset(), 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

protected

This formulation's locator; see get_id.

Referenced by get_id().

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

include/realizations/catchment/Formulation.hpp
src/realizations/catchment/Formulation.cpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Private Attributes

Detailed Description

Member Typedef Documentation

◆ time_step_t

Constructor & Destructor Documentation

◆ Formulation() [1/2]

◆ Formulation() [2/2]

◆ ~Formulation()

Member Function Documentation

◆ check_mass_balance()

◆ checkpoint_state()

◆ create_formulation() [1/2]

◆ create_formulation() [2/2]

◆ finalize()

◆ get_feature_id()

◆ get_formulation_type()

◆ get_id()

◆ get_output_fields()

◆ get_output_values_for_timestep()

◆ get_required_parameters()

◆ get_response()

◆ interpret_parameters()

◆ set_feature_id()

◆ update()

◆ validate_parameters()

Member Data Documentation

◆ feature_id

◆ forcing

◆ id