Abstraction of a formulation with a single backing model object that implements the BMI. More...

#include <Bmi_Module_Formulation.hpp>

Inheritance diagram for realization::Bmi_Module_Formulation:

Collaboration diagram for realization::Bmi_Module_Formulation:

Public Types
typedef long	time_step_t

using	data_type = DataType
	This class provides a generic interface to data services.

using	selection_type = SelectionType

Public Member Functions
	Bmi_Module_Formulation (std::string id, std::shared_ptr< data_access::GenericDataProvider > forcing_provider, utils::StreamHandler output_stream)
	Minimal constructor for objects initialize using the Formulation_Manager and subsequent calls to `create_formulation`.

	~Bmi_Module_Formulation () override=default

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

void	create_formulation (geojson::PropertyMap properties) override

boost::span< const std::string >	get_available_variable_names () const override
	Get the collection of forcing output property names this instance can provide.

std::vector< double >	get_output_values_for_timestep (int timestep) override
	Get the output variable values for the given time step, one per output column and positionally aligned with get_output_fields.

std::vector< utils::OutputField >	get_output_fields () const override
	Get this formulation's output fields (header name + units) in output order.

double	get_response (time_step_t t_index, time_step_t t_delta) override
	Get the model response for a time step.

void	update (time_step_t t_index, time_step_t t_delta) override

time_t	get_variable_time_begin (const std::string &variable_name)
	Get the inclusive beginning of the period of time over which this instance can provide data for this forcing.

long	get_data_start_time () const override
	Get the inclusive beginning of the period of time over which this instance can provide data for this forcing.

long	get_data_stop_time () const override
	Return the last valid time for which data from the requested variable can be requested.

long	record_duration () const override
	Return the stride in the time dimension.

const double	get_model_current_time () const override
	Get the current time for the backing BMI model in its native format and units.

const double	get_model_end_time () const override
	Get the end time for the backing BMI model in its native format and units.

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

const std::string &	get_config_mapped_variable_name (const std::string &model_var_name) const override
	When possible, translate a variable name for a BMI model to an internally recognized name.

size_t	get_ts_index_for_time (const time_t &epoch_time) const override
	Get the index of the forcing time step that contains the given point in time.

std::vector< double >	get_values (const CatchmentAggrDataSelector &selector, data_access::ReSampleMethod m=SUM) override
	Get the 1D values of a forcing property for an arbitrary time period, converting units if needed.

double	get_value (const CatchmentAggrDataSelector &selector, data_access::ReSampleMethod m) override
	Get the value of a forcing property for an arbitrary time period, converting units if needed.

virtual double	get_var_value_as_double (const int &index, const std::string &var_name)=0
	Get value for some BMI model variable at a specific index.

bool	is_bmi_input_variable (const std::string &var_name) const override

bool	is_bmi_output_variable (const std::string &var_name) const override

bool	is_input_variable_metadata_cached () const
	Test whether set_model_inputs_prior_to_update caches and reuses input variable metadata.

bool	is_property_sum_over_time_step (const std::string &name) const override
	Get whether a property's per-time-step values are each an aggregate sum over the entire time step.

const std::vector< std::string >	get_bmi_input_variables () const override

const std::vector< std::string >	get_bmi_output_variables () const override

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

virtual time_t	convert_model_time (const double &model_time) const =0
	Convert a time value from the model to an epoch time in seconds.

const std::string &	get_bmi_main_output_var () const

std::string	get_model_type_name () const
	Get the name of the specific type of the backing model object.

const std::vector< std::string > &	get_output_variable_names () const
	Get the names of variables in formulation output.

void	set_output_precision (int precision)
	Set the precision of output values when converted to text.

void	finalize ()
	Release resources of the given forcing provider.

virtual void	finalize ()
	Release any resources that should not be held as the run is shutting down.

virtual std::string	get_formulation_type () const =0

std::string	get_id () const

virtual data_type	get_value (const selection_type &selector, ReSampleMethod m=SUM)=0
	Get the value of a forcing property for an arbitrary time period, converting units if needed.

virtual std::vector< data_type >	get_values (const selection_type &selector, ReSampleMethod m=SUM)=0
	Get the values of a forcing property for an arbitrary time period, converting units if needed.

Static Public Member Functions
static void	config_pattern_substitution (geojson::PropertyMap &properties, const std::string &key, const std::string &pattern, const std::string &replacement)
	Perform in-place substitution on the given config property item, if the item and the pattern are present.

Protected Member Functions
void	get_bmi_output_var_name (const std::string &name, std::string &bmi_var_name) const
	Get correct BMI variable name, which may be the output or something mapped to this output.

virtual std::shared_ptr< models::bmi::Bmi_Adapter >	construct_model (const geojson::PropertyMap &properties)=0
	Construct model and its shared pointer, potentially supplying input variable values from config.

void	determine_model_time_offset ()
	Determine and set the offset time of the model in seconds, compared to forcing data.

const bool &	get_allow_model_exceed_end_time () const override
	Get whether a model may perform updates beyond its `end_time`.

const std::string &	get_bmi_init_config () const

std::shared_ptr< models::bmi::Bmi_Adapter >	get_bmi_model () const
	Get the backing model object implementing the BMI.

const time_t &	get_bmi_model_start_time_forcing_offset_s () const override

void	inner_create_formulation (geojson::PropertyMap properties, bool needs_param_validation)
	Universal logic applied when creating a BMI-backed formulation from NGen config.

void	set_initial_bmi_parameters (geojson::PropertyMap properties)
	Check configuration properties for `model_params` and attempt to set them in the bmi model.

bool	is_bmi_model_time_step_fixed () const override
	Test whether backing model has fixed time step size.

bool	is_model_initialized () const override
	Test whether the backing model object has been initialize using the BMI standard `Initialize` function.

void	set_allow_model_exceed_end_time (bool allow_exceed_end)

void	set_bmi_init_config (const std::string &init_config)

void	set_bmi_model (std::shared_ptr< models::bmi::Bmi_Adapter > model)
	Set the backing model object implementing the BMI.

void	set_bmi_model_start_time_forcing_offset_s (const time_t &offset_s)

void	set_bmi_model_time_step_fixed (bool is_fix_time_step)

virtual void	set_model_initialized (bool is_initialized)
	Set whether the backing model object has been initialize using the BMI standard `Initialize` function.

void	set_model_inputs_prior_to_update (const double &model_time, time_step_t t_delta)
	Set BMI input variable values for the model appropriately prior to calling its `BMI`update()``.

void	set_cache_input_var_metadata (bool cache_input_var_metadata)
	Set member variable indicating whether set_model_inputs_prior_to_update should store and reuse metadata.

int	get_output_precision ()

void	set_bmi_main_output_var (const std::string &main_output_var)

virtual void	set_model_type_name (std::string type_name)
	Set the name of the specific type of the backing model object.

void	set_output_header_fields (const std::vector< std::string > &output_headers)

boost::span< const std::string >	get_output_header_field_names () const
	The configured/derived output header (display) field names, positionally parallel to get_output_variable_names – header i is the output name for variable i.

void	set_output_variable_names (const std::vector< std::string > &out_var_names)
	Set the names of variables in formulation output.

const std::string &	get_catchment_id () const override

void	set_catchment_id (std::string cat_id) override

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

void	validate_parameters (geojson::PropertyMap options)

Protected Attributes
time_step_t	last_model_response_delta = 0
	The delta of the last model update execution (typically, this is time step size).

time_t	last_model_response_start_time = 0
	The epoch time of the model at the beginning of its last update.

std::map< std::string, std::shared_ptr< data_access::GenericDataProvider > >	input_forcing_providers

int	next_time_step_index = 0
	Index value (0-based) of the time step that will be processed by the next update of the model.

std::shared_ptr< std::ostringstream >	output_text_stream
	Object to help with converting numeric output values to text.

std::shared_ptr< data_access::GenericDataProvider >	forcing

std::string	id

polygon_t	bounds

utils::StreamHandler	output

std::shared_ptr< HY_Catchment >	realized_catchment

unsigned long	id_number

Private Member Functions
void	do_bmi_sets_from_stored_metadata (const time_t &src_data_start, const time_step_t &t_delta)
	Set BMI input variables before `BMI update, using saved metadata rather than re-fetching or re-calculating.

void	do_bmi_sets_with_full_refetch (const time_t &src_data_start, const time_step_t &t_delta)
	Set BMI input variables before `BMI update, re-fetching and re-calculating required metadata each time.

std::shared_ptr< data_access::GenericDataProvider > &	get_provider_for_input_var (const std::string &var_name, const std::string &mapped_alias)
	Get the appropriate data provider to set inputs for this BMI variable.

void	initialize_bmi_input_var_metadata ()
	Initialize the metadata as needed for do_bmi_sets_from_stored_metadata.

void	perform_set (const time_t &src_data_start, const time_step_t &t_delta, const std::shared_ptr< data_access::GenericDataProvider > &provider, const Bmi_Var_Details *var_details) const
	Do the action of retrieving data and setting values for an input variable ahead of advancing the model.

Private Attributes
std::unique_ptr< std::vector< Bmi_Var_Details * > >	bmi_input_var_details
	BMI input variables details for this instance, cached to improve compute performance when setting values prior to updates.

std::unique_ptr< std::vector< std::shared_ptr< data_access::GenericDataProvider > > >	bmi_input_providers
	Vector of data providers for BMI input vars, with the provider at an index corresponding to the var in bmi_input_var_details at the same index.

models::bmi::protocols::NgenBmiProtocols	bmi_protocols

bool	allow_model_exceed_end_time = false
	Whether model `Update` calls are allowed and handled in some way by the backing model for time steps after the model's `end_time`.

std::vector< std::string >	available_forcings
	The set of available "forcings" (output variables, plus their mapped aliases) that the model can provide.

std::string	bmi_init_config

std::shared_ptr< models::bmi::Bmi_Adapter >	bmi_model

bool	bmi_model_time_step_fixed = true
	Whether backing model has fixed time step size.

time_t	bmi_model_start_time_forcing_offset_s
	The offset, converted to seconds, from the model's start time to the start time of the initial forcing time step.

std::map< std::string, std::string >	bmi_var_names_map
	A configured mapping of BMI model variable names to standard names for use inside the framework.

bool	model_initialized = false

std::vector< std::string >	OPTIONAL_PARAMETERS

std::vector< std::string >	REQUIRED_PARAMETERS

bool	cache_input_variable_metadata = false
	Whether set_model_inputs_prior_to_update should store and reuse metadata.

std::string	bmi_main_output_var

std::string	model_type_name

std::vector< std::string >	output_header_fields
	Output header field strings corresponding to the variables output by the realization, as defined in `output_variable_names`.

std::vector< std::string >	output_variable_names
	Names of the variables to include in the output from this formulation, which will be some ordered subset of the BMI module output variables accessible to the instance.

int	output_precision
	The degree of precision in output values when converting to text.

std::string	cat_id

Static Private Attributes
static std::set< Bmi_Var_Details >	known_bmi_input_vars
	BMI input variables details for all instances, cached to improve compute performance when setting values prior to updates.

Friends
class	Bmi_Multi_Formulation

class	::Bmi_Formulation_Test

class	::Bmi_C_Formulation_Test

class	::Bmi_Multi_Formulation_Test

class	::Bmi_Cpp_Formulation_Test

class	::Bmi_Cpp_Multi_Array_Test

Detailed Description

Abstraction of a formulation with a single backing model object that implements the BMI.

Member Typedef Documentation

◆ data_type

template<class DataType , class SelectionType >

using data_access::DataProvider< DataType, SelectionType >::data_type = DataType

inherited

This class provides a generic interface to data services.

◆ selection_type

template<class DataType , class SelectionType >

using data_access::DataProvider< DataType, SelectionType >::selection_type = SelectionType

inherited

◆ time_step_t

long realization::Formulation::time_step_t

inherited

Constructor & Destructor Documentation

◆ Bmi_Module_Formulation()

realization::Bmi_Module_Formulation::Bmi_Module_Formulation	(	std::string	id,
		std::shared_ptr< data_access::GenericDataProvider >	forcing_provider,
		utils::StreamHandler	output_stream )

inline

Minimal constructor for objects initialize using the Formulation_Manager and subsequent calls to create_formulation.

Parameters

id
forcing_provider
output_stream

◆ ~Bmi_Module_Formulation()

realization::Bmi_Module_Formulation::~Bmi_Module_Formulation ( )

overridedefault

Member Function Documentation

◆ check_mass_balance()

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

inlineoverridevirtual

Implements realization::Formulation.

References bmi_protocols, models::bmi::protocols::MASS_BALANCE, and models::bmi::protocols::NgenBmiProtocols::run().

◆ config_pattern_substitution()

void realization::Catchment_Formulation::config_pattern_substitution	(	geojson::PropertyMap &	properties,
		const std::string &	key,
		const std::string &	pattern,
		const std::string &	replacement )

staticinherited

Perform in-place substitution on the given config property item, if the item and the pattern are present.

Any and all instances of the substring pattern are replaced by replacement, if key maps to a present string-type property value.

Parameters

properties	A reference to the properties config object to be altered.
key	The key for the configuration property to potentially adjust.
pattern	The pattern substring to search for that, when present, should be replaced.
replacement	The replacement substring to potentially insert.

References geojson::String.

Referenced by realization::Formulation_Manager::construct_formulation_from_config(), realization::Formulation_Manager::construct_missing_formulation(), and realization::Bmi_Multi_Formulation::init_nested_module().

◆ construct_model()

virtual std::shared_ptr< models::bmi::Bmi_Adapter > realization::Bmi_Module_Formulation::construct_model ( const geojson::PropertyMap & properties )

protectedpure virtual

Construct model and its shared pointer, potentially supplying input variable values from config.

Construct a model (and a shared pointer to it), checking whether additional input variable values are present in the configuration properties and need to be used during model construction.

Parameters

properties Configuration properties for the formulation, potentially containing values for input variables

Returns: A shared pointer to a newly constructed model object

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

Referenced by inner_create_formulation().

◆ convert_model_time()

virtual time_t realization::Bmi_Formulation::convert_model_time ( const double & model_time ) const

pure virtualinherited

Convert a time value from the model to an epoch time in seconds.

Model time values are typically (though not always) 0-based totals count upward as time progresses. The units are not necessarily seconds. This performs the necessary lookup and conversion for such units, and then shifts the value appropriately for epoch time representation.

Parameters

model_time

Returns

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

Referenced by determine_model_time_offset(), and set_model_inputs_prior_to_update().

◆ create_formulation() [1/2]

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

overridevirtual

Implements realization::Catchment_Formulation.

References inner_create_formulation(), and realization::Formulation::interpret_parameters().

◆ create_formulation() [2/2]

void realization::Bmi_Module_Formulation::create_formulation ( geojson::PropertyMap properties )

overridevirtual

Implements realization::Catchment_Formulation.

References inner_create_formulation().

◆ determine_model_time_offset()

void realization::Bmi_Module_Formulation::determine_model_time_offset ( )

protected

Determine and set the offset time of the model in seconds, compared to forcing data.

BMI models frequently have their model start time be set to 0. As such, to know what the forcing time is compared to the model time, an offset value is needed. This becomes important in situations when the size of the time steps for forcing data versus model execution are not equal. This method will determine and set this value.

References realization::Bmi_Formulation::convert_model_time(), realization::Catchment_Formulation::forcing, get_bmi_model(), and set_bmi_model_start_time_forcing_offset_s().

Referenced by inner_create_formulation().

◆ do_bmi_sets_from_stored_metadata()

void realization::Bmi_Module_Formulation::do_bmi_sets_from_stored_metadata	(	const time_t &	src_data_start,
		const time_step_t &	t_delta )

private

Set BMI input variables before `BMI update, using saved metadata rather than re-fetching or re-calculating.

This is one of two available execution paths used by set_model_inputs_prior_to_update for the bulk of its behavior. Certain metadata details about a BMI input variable must be available in order for the framework to execute a set_value call: e.g., the data provider that is the correct source of input values, the analogous C++ type, the number of items, etc. In this execution option, that data is obtained once and stored for subsequent reuse, optimizing compute at each time step a bit at the expense of memory.

References to objects containing these details are stored within the bmi_input_var_details vector, populated on the first call to this function. These are actually pointers to objects contained within the known_bmi_input_vars static member variable.

An important consideration is that this function is not strictly safe relying only on guarantees provided by BMI. Nothing within the BMI spec guarantees that, for example, a variable will not change the number of items it contains. It is therefore possible, in general, for stored data to become stale for a properly implemented BMI module. In practice, however, any selected module's implementation details and behavior will be known by the user, so users can elect to only use this execution path for set_model_inputs_prior_to_update when the BMI module itself guarantees such data cannot become stale.

Parameters

src_data_start	The start time (in seconds) to use when retrieving data from the appropriate provider to use for setting the model's variables.
t_delta	The size of the time step over which the formulation is going to update the model, which might be different than the model's internal time step.

References bmi_input_providers, bmi_input_var_details, initialize_bmi_input_var_metadata(), and perform_set().

Referenced by set_model_inputs_prior_to_update().

◆ do_bmi_sets_with_full_refetch()

void realization::Bmi_Module_Formulation::do_bmi_sets_with_full_refetch	(	const time_t &	src_data_start,
		const time_step_t &	t_delta )

private

Set BMI input variables before `BMI update, re-fetching and re-calculating required metadata each time.

This is one of two available execution paths used by set_model_inputs_prior_to_update for the bulk of its behavior. Certain metadata details about a BMI input variable must be available in order for the framework to execute a set_value call: e.g., the data provider that is the correct source of input values, the analogous C++ type, the number of items, etc. In this execution option, that data is freshly obtained

either recalculated, redetermined, or refetched from the BMI module itself - on every call to this method. This results in less efficient compute but also reduced memory usage.

An important consideration is that this function provides an execution option that is strictly safe relying only on guarantees provided by BMI. Nothing within the BMI spec guarantees that, for example, a variable will not change the number of items it contains. If a configured module does (or may) change input variable metadata, or if it is possible for a module to change the set of input variables, then this execution path for set_model_inputs_prior_to_update should be selected.

BMI module. In practice, however, any selected module's implementation details and behavior will be known by the user, so users can elect to only use this execution path for set_model_inputs_prior_to_update when the BMI module itself guarantees such data cannot become stale. better memory and safe for no guarantees

Parameters

src_data_start	The start time (in seconds) to use when retrieving data from the appropriate provider to use for setting the model's variables.
t_delta	The size of the time step over which the formulation is going to update the model, which might be different than the model's internal time step.

References get_bmi_model(), get_config_mapped_variable_name(), get_provider_for_input_var(), bmi::Bmi::GetVarItemsize(), and perform_set().

Referenced by set_model_inputs_prior_to_update().

◆ finalize() [1/2]

template<class DataType , class SelectionType >

virtual void data_access::DataProvider< DataType, SelectionType >::finalize ( )

inlinevirtualinherited

Release any resources that should not be held as the run is shutting down.

In particular, this should be called before MPI_Finalize()

Reimplemented in data_access::WrappedDataProvider.

◆ finalize() [2/2]

void realization::Catchment_Formulation::finalize ( )

inherited

Release resources of the given forcing provider.

References realization::Catchment_Formulation::forcing.

◆ get_allow_model_exceed_end_time()

const bool & realization::Bmi_Module_Formulation::get_allow_model_exceed_end_time ( ) const

overrideprotectedvirtual

Get whether a model may perform updates beyond its end_time.

Get whether model Update calls are allowed and handled in some way by the backing model for time steps after the model's end_time. Implementations of this type should use this function to safeguard against entering either an invalid or otherwise undesired state as a result of attempting to process a model beyond its available data.

As mentioned, even for models that are capable of validly handling processing beyond end time, it may be desired that they do not for some reason (e.g., the way they account for the lack of input data leads to valid but incorrect results for a specific application). Because of this, whether models are allowed to process beyond their end time is configuration-based.

Returns: Whether a model may perform updates beyond its end_time.

Implements realization::Bmi_Formulation.

References allow_model_exceed_end_time.

Referenced by update().

◆ get_available_variable_names()

boost::span< const std::string > realization::Bmi_Module_Formulation::get_available_variable_names ( ) const

overridevirtual

Get the collection of forcing output property names this instance can provide.

This is part of the ForcingProvider interface. This interface must be implemented for items of this type to be usable as "forcing" providers for situations when some other object needs to receive as an input (i.e., one of its forcings) a data property output from this object.

For this type, this is the collection of BMI output variables, plus any aliases included in the formulation config's output variable mapping.

Returns: The collection of forcing output property names this instance can provide.

See also: ForcingProvider

Implements data_access::DataProvider< DataType, SelectionType >.

References available_forcings.

Referenced by get_value(), and get_values().

◆ get_bmi_init_config()

const std::string & realization::Bmi_Module_Formulation::get_bmi_init_config ( ) const

protected

References bmi_init_config.

Referenced by realization::Bmi_C_Formulation::construct_model(), and realization::Bmi_Cpp_Formulation::construct_model().

◆ get_bmi_input_variables()

const std::vector< std::string > realization::Bmi_Module_Formulation::get_bmi_input_variables ( ) const

overridevirtual

Implements realization::Bmi_Formulation.

References get_bmi_model(), and bmi::Bmi::GetInputVarNames().

Referenced by is_bmi_input_variable().

◆ get_bmi_main_output_var()

const std::string & realization::Bmi_Formulation::get_bmi_main_output_var ( ) const

inlineinherited

References realization::Bmi_Formulation::bmi_main_output_var.

Referenced by get_response(), and realization::Bmi_Multi_Formulation::get_response().

◆ get_bmi_model()

std::shared_ptr< models::bmi::Bmi_Adapter > realization::Bmi_Module_Formulation::get_bmi_model ( ) const

protected

Get the backing model object implementing the BMI.

Returns: Shared pointer to the backing model object that implements the BMI.

References bmi_model.

◆ get_bmi_model_start_time_forcing_offset_s()

const time_t & realization::Bmi_Module_Formulation::get_bmi_model_start_time_forcing_offset_s ( ) const

overrideprotectedvirtual

Implements realization::Bmi_Formulation.

References bmi_model_start_time_forcing_offset_s.

Referenced by set_model_inputs_prior_to_update().

◆ get_bmi_output_var_name()

void realization::Bmi_Module_Formulation::get_bmi_output_var_name	(	const std::string &	name,
		std::string &	bmi_var_name ) const

protected

Get correct BMI variable name, which may be the output or something mapped to this output.

Parameters

name
bmi_var_name

References bmi_var_names_map, get_bmi_model(), and bmi::Bmi::GetOutputVarNames().

Referenced by get_value(), and get_values().

◆ get_bmi_output_variables()

const std::vector< std::string > realization::Bmi_Module_Formulation::get_bmi_output_variables ( ) const

overridevirtual

Implements realization::Bmi_Formulation.

References get_bmi_model(), and bmi::Bmi::GetOutputVarNames().

Referenced by is_bmi_output_variable().

◆ get_catchment_id()

const std::string & realization::Catchment_Formulation::get_catchment_id ( ) const

inlineoverrideprotectedvirtualinherited

Implements HY_CatchmentRealization.

References realization::Catchment_Formulation::cat_id.

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

◆ get_config_mapped_variable_name()

const std::string & realization::Bmi_Module_Formulation::get_config_mapped_variable_name ( const std::string & model_var_name ) const

overridevirtual

When possible, translate a variable name for a BMI model to an internally recognized name.

Translate some BMI variable name to something recognized in some internal context for use within NGen. Do this according to the map of variable names supplied in the external formulation config. If no mapping for the given variable name was configured, return the variable name itself.

For example, perhaps a BMI model has the input variable "RAIN_RATE." Configuring this variable name to map to "precip_rate" will allow the formulation to understand that this particular forcing field should be used to set the model's "RAIN_RATE" variable.

Parameters

model_var_name The BMI variable name to translate so its purpose is recognized internally.

Returns: Either the internal equivalent variable name, or the provided name if there is not a mapping entry.

Implements realization::Bmi_Formulation.

References bmi_var_names_map.

Referenced by do_bmi_sets_with_full_refetch(), and initialize_bmi_input_var_metadata().

◆ get_data_start_time()

long realization::Bmi_Module_Formulation::get_data_start_time ( ) const

overridevirtual

Get the inclusive beginning of the period of time over which this instance can provide data for this forcing.

This is part of the DataProvider interface. This interface must be implemented for items of this type to be usable as "forcing" providers for situations when some other object needs to receive as an input (i.e., one of its forcings) a data property output from this object.

Returns: The inclusive beginning of the period of time over which this instance can provide this data.

Implements data_access::DataProvider< DataType, SelectionType >.

References get_bmi_model(), and bmi::Bmi::GetStartTime().

◆ get_data_stop_time()

long realization::Bmi_Module_Formulation::get_data_stop_time ( ) const

overridevirtual

Return the last valid time for which data from the requested variable can be requested.

Implements data_access::DataProvider< DataType, SelectionType >.

◆ get_formulation_type()

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

pure virtualinherited

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

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

◆ get_id()

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

inlineinherited

References realization::Formulation::id.

◆ get_model_current_time()

const double realization::Bmi_Module_Formulation::get_model_current_time ( ) const

overridevirtual

Get the current time for the backing BMI model in its native format and units.

Returns: The current time for the backing BMI model in its native format and units.

Implements realization::Bmi_Formulation.

References get_bmi_model(), and bmi::Bmi::GetCurrentTime().

◆ get_model_end_time()

const double realization::Bmi_Module_Formulation::get_model_end_time ( ) const

overridevirtual

Get the end time for the backing BMI model in its native format and units.

Returns: The end time for the backing BMI model in its native format and units.

Implements realization::Bmi_Formulation.

References get_bmi_model(), and bmi::Bmi::GetEndTime().

◆ get_model_type_name()

std::string realization::Bmi_Formulation::get_model_type_name ( ) const

inlineinherited

Get the name of the specific type of the backing model object.

Returns: The name of the backing model object's type.

References realization::Bmi_Formulation::model_type_name.

Referenced by realization::Bmi_C_Formulation::construct_model(), realization::Bmi_Cpp_Formulation::construct_model(), realization::Bmi_C_Formulation::get_var_value_as_double(), and realization::Bmi_Cpp_Formulation::get_var_value_as_double().

◆ get_output_fields()

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

inlineoverridevirtual

Get this formulation's output fields (header name + units) in output order.

Units come straight from the backing BMI model (GetVarUnits) per output variable; std::nullopt when the model reports none (GetVarUnits fails / BMI_FAILURE) rather than failing the run.

Implements realization::Catchment_Formulation.

References get_bmi_model(), realization::Bmi_Formulation::get_output_header_field_names(), realization::Bmi_Formulation::get_output_variable_names(), and bmi::Bmi::GetVarUnits().

◆ get_output_header_field_names()

boost::span< const std::string > realization::Bmi_Formulation::get_output_header_field_names ( ) const

inlineprotectedinherited

The configured/derived output header (display) field names, positionally parallel to get_output_variable_names – header i is the output name for variable i.

A concrete subclass uses these as each column's output_name when building get_output_fields.

References realization::Bmi_Formulation::output_header_fields.

Referenced by get_output_fields(), and realization::Bmi_Multi_Formulation::get_output_fields().

◆ get_output_precision()

int realization::Bmi_Formulation::get_output_precision ( )

inlineprotectedinherited

References realization::Bmi_Formulation::output_precision.

◆ get_output_values_for_timestep()

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

overridevirtual

Get the output variable values for the given time step, one per output column and positionally aligned with get_output_fields.

The values are the model's calculated outputs for the time step; the time step index itself is not included.

Only the last processed time step is accessible, because formulations do not save results from previous time steps; there is thus no valid time step before at least one call to update has been made. Throws std::invalid_argument if timestep is not the current (last processed) time step.

Parameters

timestep The time step for which data is desired.

Returns: The output values for the given time step, one per output column.

Implements realization::Catchment_Formulation.

References realization::Catchment_Formulation::get_catchment_id(), realization::Bmi_Formulation::get_output_variable_names(), get_value(), next_time_step_index, and logging::warning().

◆ get_output_variable_names()

const std::vector< std::string > & realization::Bmi_Formulation::get_output_variable_names ( ) const

inlineinherited

Get the names of variables in formulation output.

Get the names of the variables to include in the output from this formulation, which should be some ordered subset of the BMI module output variables accessible to this instance.

Returns

References realization::Bmi_Formulation::output_variable_names.

Referenced by realization::Bmi_Multi_Formulation::check_output_var_names(), realization::Bmi_Multi_Formulation::create_multi_formulation(), get_output_fields(), realization::Bmi_Multi_Formulation::get_output_fields(), get_output_values_for_timestep(), realization::Bmi_Multi_Formulation::get_output_values_for_timestep(), and inner_create_formulation().

◆ get_provider_for_input_var()

std::shared_ptr< data_access::GenericDataProvider > & realization::Bmi_Module_Formulation::get_provider_for_input_var	(	const std::string &	var_name,
		const std::string &	mapped_alias )

private

Get the appropriate data provider to set inputs for this BMI variable.

Get the appropriate data provider for setting values for this BMI variable from input_forcing_providers.

Parameters

var_name	The BMI variable name as retrievable directly via BMI.
mapped_alias	The framework's internal mapped alias for this variable.

Returns: The appropriate data provider

References realization::Catchment_Formulation::forcing, and input_forcing_providers.

Referenced by do_bmi_sets_with_full_refetch(), and initialize_bmi_input_var_metadata().

◆ get_required_parameters()

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

overridevirtual

Reimplemented from realization::Bmi_Formulation.

References REQUIRED_PARAMETERS.

◆ get_response()

double realization::Bmi_Module_Formulation::get_response	(	time_step_t	t_index,
		time_step_t	t_delta )

overridevirtual

Get the model response for a time step.

Get the model response for the provided time step, executing the backing model formulation one or more times as needed.

Function assumes the backing model has been fully initialized an that any additional input values have been applied.

The function throws an error if the index of a previously processed time step is supplied, except if it is the last processed time step. In that case, the appropriate value is returned as described below, but without executing any model update.

Assuming updating to the implied time is valid for the model, the function executes one or more model updates to process future time steps for the necessary indexes. Multiple time steps updates occur when the given future time step index is not the next time step index to be processed. Regardless, all processed time steps have the size supplied in t_delta.

However, it is possible to provide t_index and t_delta values that would result in the aggregate updates taking the model's time beyond its end_time value. In such cases, if the formulation config indicates this model is not allow to exceed its set end_time, the function does not update the model and throws an error.

The function will return the value of the primary output variable (see get_bmi_main_output_var()) for the given time step after the model has been updated to that point. The type returned will always be a double, with other numeric types being cast if necessary.

The BMI spec requires for variable values to be passed to/from models via as arrays. This function essentially treats the variable array reference as if it were just a raw pointer and returns the 0-th array value.

Parameters

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

Returns: The total discharge of the model for the given time step.

Implements realization::Catchment_Formulation.

References realization::Bmi_Formulation::get_bmi_main_output_var(), realization::Catchment_Formulation::get_catchment_id(), get_value(), UnitsHelper::unit_conversion_exception::provider_model_name, UnitsHelper::unit_conversion_exception::provider_var_name, UnitsHelper::record_unit_conversion_fault(), UnitsHelper::unit_conversion_exception::unconverted_values, update(), and logging::warning().

◆ get_ts_index_for_time()

size_t realization::Bmi_Module_Formulation::get_ts_index_for_time ( const time_t & epoch_time ) const

overridevirtual

Get the index of the forcing time step that contains the given point in time.

This is part of the ForcingProvider interface. This interface must be implemented for items of this type to be usable as "forcing" providers for situations when some other object needs to receive as an input (i.e., one of its forcings) a data property output from this object.

An std::out_of_range exception should be thrown if the time is not in any time step.

Parameters

epoch_time The point in time, as a seconds-based epoch time.

Returns: The index of the forcing time step that contains the given point in time.

Exceptions

std::out_of_range If the given point is not in any time step.

Implements data_access::DataProvider< DataType, SelectionType >.

◆ get_value() [1/2]

template<class DataType , class SelectionType >

virtual data_type data_access::DataProvider< DataType, SelectionType >::get_value	(	const selection_type &	selector,
		ReSampleMethod	m = SUM )

pure virtualinherited

Get the value of a forcing property for an arbitrary time period, converting units if needed.

An std::out_of_range exception should be thrown if the data for the time period is not available.

Parameters

selector	Data required to establish what subset of the stored data should be accessed
m	How data is to be resampled if there is a mismatch in data alignment or repeat rate

Returns: The value of the forcing property for the described time period, with units converted if needed.

Exceptions

std::out_of_range If data for the time period is not available.

Referenced by data_access::WrappedDataProvider::get_value().

◆ get_value() [2/2]

double realization::Bmi_Module_Formulation::get_value	(	const CatchmentAggrDataSelector &	selector,
		data_access::ReSampleMethod	m )

override

Get the value of a forcing property for an arbitrary time period, converting units if needed.

This is part of the ForcingProvider interface. This interface must be implemented for items of this type to be usable as "forcing" providers for situations when some other object needs to receive as an input (i.e., one of its forcings) a data property output from this object.

An std::out_of_range exception should be thrown if the data for the time period is not available.

Parameters

output_name	The name of the forcing property of interest.
init_time_epoch	The epoch time (in seconds) of the start of the time period.
duration_seconds	The length of the time period, in seconds.
output_units	The expected units of the desired output value.

Returns: The value of the forcing property for the described time period, with units converted if needed.

Exceptions

std::out_of_range If data for the time period is not available.

See also: ForcingProvider::get_value

References get_available_variable_names(), get_bmi_model(), get_bmi_output_var_name(), UnitsHelper::get_converted_value(), realization::Formulation::get_formulation_type(), models::bmi::Bmi_Adapter::get_model_name(), CatchmentAggrDataSelector::get_output_units(), get_var_value_as_double(), CatchmentAggrDataSelector::get_variable_name(), bmi::Bmi::GetVarUnits(), UnitsHelper::unit_conversion_exception::provider_model_name, and UnitsHelper::unit_conversion_exception::provider_var_name.

Referenced by get_output_values_for_timestep(), and get_response().

◆ get_values() [1/2]

template<class DataType , class SelectionType >

virtual std::vector< data_type > data_access::DataProvider< DataType, SelectionType >::get_values	(	const selection_type &	selector,
		ReSampleMethod	m = SUM )

pure virtualinherited

Get the values of a forcing property for an arbitrary time period, converting units if needed.

An std::out_of_range exception should be thrown if the data for the time period is not available.

If a provider doesn't implement this function, then by default, get_values will be a simple proxy to get_value with the result wrapped in a std::vector<double>

Parameters

output_name	The name of the forcing property of interest.
init_time_epoch	The epoch time (in seconds) of the start of the time period.
duration_seconds	The length of the time period, in seconds.
output_units	The expected units of the desired output value.

Returns: std::vector<double> The vector of values of the forcing property for the described time period, with units converted if needed.

Exceptions

std::out_of_range If data for the time period is not available.

Referenced by data_access::WrappedDataProvider::get_values().

◆ get_values() [2/2]

std::vector< double > realization::Bmi_Module_Formulation::get_values	(	const CatchmentAggrDataSelector &	selector,
		data_access::ReSampleMethod	m = SUM )

override

Get the 1D values of a forcing property for an arbitrary time period, converting units if needed.

Parameters

output_name	The name of the forcing property of interest.
init_time	The epoch time (in seconds) of the start of the time period.
duration_s	The length of the time period, in seconds.
output_units	The expected units of the desired output value.

Returns: std::vector<double> The 1D values of the forcing property for the described time period, with units converted if needed.

Exceptions

std::out_of_range	If data for the time period is not available.
std::runtime_error	output_name is not one of the available outputs of this provider instance.

References UnitsHelper::convert_values(), get_available_variable_names(), get_bmi_model(), get_bmi_output_var_name(), realization::Formulation::get_formulation_type(), models::bmi::Bmi_Adapter::get_model_name(), CatchmentAggrDataSelector::get_output_units(), CatchmentAggrDataSelector::get_variable_name(), models::bmi::GetValue(), bmi::Bmi::GetVarUnits(), UnitsHelper::unit_conversion_exception::provider_model_name, UnitsHelper::unit_conversion_exception::provider_var_name, and UnitsHelper::unit_conversion_exception::unconverted_values.

◆ get_var_value_as_double()

virtual double realization::Bmi_Module_Formulation::get_var_value_as_double	(	const int &	index,
		const std::string &	var_name )

pure virtual

Get value for some BMI model variable at a specific index.

Function gets the value for a provided variable, returned from the backing model as an array, and returns the specific value at the desired index cast as a double type.

The function makes several assumptions:

1. `index` is within array bounds
2. `var_name` is in the set of valid variable names for the model
3. the type for output variable allows the value to be cast to a `double` appropriately

It falls to user (functions) of this function to ensure these assumptions hold before invoking.

Parameters

index
var_name

Returns

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

Referenced by get_value().

◆ get_variable_time_begin()

time_t realization::Bmi_Module_Formulation::get_variable_time_begin ( const std::string & variable_name )

Get the inclusive beginning of the period of time over which this instance can provide data for this forcing.

This is part of the ForcingProvider interface. This interface must be implemented for items of this type to be usable as "forcing" providers for situations when some other object needs to receive as an input (i.e., one of its forcings) a data property output from this object.

Returns: The inclusive beginning of the period of time over which this instance can provide this data.

◆ initialize_bmi_input_var_metadata()

void realization::Bmi_Module_Formulation::initialize_bmi_input_var_metadata ( )

private

Initialize the metadata as needed for do_bmi_sets_from_stored_metadata.

This will populate the bmi_input_var_details member. As metadata is gathered into Bmi_Var_Details objects, these will be inserted into to the known_bmi_input_vars static member. Pointers to the values in that set are then added to bmi_input_var_details.

References bmi_input_providers, bmi_input_var_details, get_bmi_model(), get_config_mapped_variable_name(), get_provider_for_input_var(), bmi::Bmi::GetVarItemsize(), and known_bmi_input_vars.

Referenced by do_bmi_sets_from_stored_metadata().

◆ inner_create_formulation()

void realization::Bmi_Module_Formulation::inner_create_formulation	(	geojson::PropertyMap	properties,
		bool	needs_param_validation )

protected

Universal logic applied when creating a BMI-backed formulation from NGen config.

This performs all the necessary steps to initialize this formulation from provided configuration properties. It is written in such a way that it can be used in appropriately crafted nested calls from both public create_formulation implementations, thus allowing the primary formulation initialization logic to be centralized and not duplicated.

Parameters

properties
needs_param_validation

References available_forcings, bmi_protocols, bmi_var_names_map, construct_model(), determine_model_time_offset(), get_bmi_model(), realization::Bmi_Formulation::get_output_variable_names(), models::bmi::Bmi_Adapter::is_model_initialized(), model_initialized, set_allow_model_exceed_end_time(), set_bmi_init_config(), realization::Bmi_Formulation::set_bmi_main_output_var(), set_bmi_model(), set_bmi_model_time_step_fixed(), set_cache_input_var_metadata(), set_initial_bmi_parameters(), realization::Bmi_Formulation::set_model_type_name(), realization::Bmi_Formulation::set_output_header_fields(), realization::Bmi_Formulation::set_output_precision(), realization::Bmi_Formulation::set_output_variable_names(), and realization::Formulation::validate_parameters().

Referenced by create_formulation(), and create_formulation().

◆ 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 create_formulation(), and realization::Bmi_Multi_Formulation::create_formulation().

◆ is_bmi_input_variable()

bool realization::Bmi_Module_Formulation::is_bmi_input_variable ( const std::string & var_name ) const

overridevirtual

Implements realization::Bmi_Formulation.

References get_bmi_input_variables(), and realization::is_var_name_in_collection().

◆ is_bmi_model_time_step_fixed()

bool realization::Bmi_Module_Formulation::is_bmi_model_time_step_fixed ( ) const

overrideprotectedvirtual

Test whether backing model has fixed time step size.

Returns: Whether backing model has fixed time step size.

Implements realization::Bmi_Formulation.

References bmi_model_time_step_fixed.

Referenced by realization::Bmi_C_Formulation::construct_model(), and realization::Bmi_Cpp_Formulation::construct_model().

◆ is_bmi_output_variable()

bool realization::Bmi_Module_Formulation::is_bmi_output_variable ( const std::string & var_name ) const

overridevirtual

Implements realization::Bmi_Formulation.

References get_bmi_output_variables(), and realization::is_var_name_in_collection().

◆ is_input_variable_metadata_cached()

bool realization::Bmi_Module_Formulation::is_input_variable_metadata_cached ( ) const

Test whether set_model_inputs_prior_to_update caches and reuses input variable metadata.

See cache_input_variable_metadata and set_cache_input_var_metadata for details.

Returns: Whether input variable metadata is cached and reused across time steps, rather than re-fetched.

References cache_input_variable_metadata.

◆ is_model_initialized()

bool realization::Bmi_Module_Formulation::is_model_initialized ( ) const

overrideprotectedvirtual

Test whether the backing model object has been initialize using the BMI standard Initialize function.

Returns: Whether backing model object has been initialize using the BMI standard Initialize function.

Implements realization::Bmi_Formulation.

References model_initialized.

◆ is_property_sum_over_time_step()

bool realization::Bmi_Module_Formulation::is_property_sum_over_time_step ( const std::string & name ) const

overridevirtual

Get whether a property's per-time-step values are each an aggregate sum over the entire time step.

This is part of the ForcingProvider interface. This interface must be implemented for items of this type to be usable as "forcing" providers for situations when some other object needs to receive as an input (i.e., one of its forcings) a data property output from this object.

Certain properties, like rain fall, are aggregated sums over an entire time step. Others, such as pressure, are not such sums and instead something else like an instantaneous reading or an average value.

It may be the case that forcing data is needed for some discretization different than the forcing time step. This aspect must be known in such cases to perform the appropriate value interpolation.

For instances of this type, all output forcings fall under this category.

Parameters

name	The name of the forcing property for which the current value is desired.

Returns: Whether the property's value is an aggregate sum, which is always true for this type.

Reimplemented from data_access::DataProvider< DataType, SelectionType >.

◆ perform_set()

void realization::Bmi_Module_Formulation::perform_set	(	const time_t &	src_data_start,
		const time_step_t &	t_delta,
		const std::shared_ptr< data_access::GenericDataProvider > &	provider,
		const Bmi_Var_Details *	var_details ) const

private

Do the action of retrieving data and setting values for an input variable ahead of advancing the model.

Parameters

src_data_start	The start time (in seconds) to use when retrieving data from the appropriate provider to use for setting the model's variables.
t_delta	The size of the time step over which the formulation is going to update the model, which might be different than the model's internal time step.
provider	The data provider from which to source the data to use to set the variable.
var_details	Variable details struct containing the remainder of information required (e.g., var name).

References get_bmi_model(), realization::Catchment_Formulation::get_catchment_id(), realization::Bmi_Var_Details::get_cpp_type(), realization::Bmi_Var_Details::get_mapped_alias(), models::bmi::Bmi_Adapter::get_model_name(), realization::Bmi_Var_Details::get_name(), realization::Bmi_Var_Details::get_num_items(), realization::Bmi_Var_Details::get_units(), realization::get_value_as_type(), realization::get_values_as_type(), UnitsHelper::unit_conversion_exception::provider_model_name, UnitsHelper::unit_conversion_exception::provider_var_name, UnitsHelper::record_unit_conversion_fault(), bmi::Bmi::SetValue(), UnitsHelper::unit_conversion_exception::unconverted_values, and logging::warning().

Referenced by do_bmi_sets_from_stored_metadata(), and do_bmi_sets_with_full_refetch().

◆ record_duration()

long realization::Bmi_Module_Formulation::record_duration ( ) const

overridevirtual

Return the stride in the time dimension.

Implements data_access::DataProvider< DataType, SelectionType >.

◆ set_allow_model_exceed_end_time()

void realization::Bmi_Module_Formulation::set_allow_model_exceed_end_time ( bool allow_exceed_end )

protected

References allow_model_exceed_end_time.

Referenced by inner_create_formulation().

◆ set_bmi_init_config()

void realization::Bmi_Module_Formulation::set_bmi_init_config ( const std::string & init_config )

protected

References bmi_init_config.

Referenced by inner_create_formulation().

◆ set_bmi_main_output_var()

void realization::Bmi_Formulation::set_bmi_main_output_var ( const std::string & main_output_var )

inlineprotectedinherited

References realization::Bmi_Formulation::bmi_main_output_var.

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

◆ set_bmi_model()

void realization::Bmi_Module_Formulation::set_bmi_model ( std::shared_ptr< models::bmi::Bmi_Adapter > model )

protected

Set the backing model object implementing the BMI.

Parameters

model Shared pointer to the BMI model.

References bmi_model.

Referenced by inner_create_formulation().

◆ set_bmi_model_start_time_forcing_offset_s()

void realization::Bmi_Module_Formulation::set_bmi_model_start_time_forcing_offset_s ( const time_t & offset_s )

protected

References bmi_model_start_time_forcing_offset_s.

Referenced by determine_model_time_offset().

◆ set_bmi_model_time_step_fixed()

void realization::Bmi_Module_Formulation::set_bmi_model_time_step_fixed ( bool is_fix_time_step )

protected

References bmi_model_time_step_fixed.

Referenced by inner_create_formulation().

◆ set_cache_input_var_metadata()

void realization::Bmi_Module_Formulation::set_cache_input_var_metadata ( bool cache_input_var_metadata )

protected

Set member variable indicating whether set_model_inputs_prior_to_update should store and reuse metadata.

Set the cache_input_variable_metadata member variable, which indicates whether set_model_inputs_prior_to_update should store and reuse metadata, as opposed to refreshing such data each time set_model_inputs_prior_to_update is called.

Parameters

cache_input_var_metadata Whether set_model_inputs_prior_to_update should store and reuse metadata

References cache_input_variable_metadata.

Referenced by inner_create_formulation().

◆ set_catchment_id()

void realization::Catchment_Formulation::set_catchment_id ( std::string cat_id )

inlineoverrideprotectedvirtualinherited

Implements HY_CatchmentRealization.

References realization::Catchment_Formulation::cat_id.

Referenced by realization::Catchment_Formulation::Catchment_Formulation(), and realization::Catchment_Formulation::Catchment_Formulation().

◆ set_initial_bmi_parameters()

void realization::Bmi_Module_Formulation::set_initial_bmi_parameters ( geojson::PropertyMap properties )

protected

Check configuration properties for model_params and attempt to set them in the bmi model.

This checks for a key named model_params in the parsed properties, and for each property it will attempt to call SetValue using the property's key as the BMI variable and the property's value as the value to set.

This function should only be called once bmi_model is properly constructed. If bmi_model is a nullptr, this function becomes a no-op.

References models::bmi::Bmi_Adapter::get_analogous_cxx_type(), get_bmi_model(), geojson::get_propertytype_name(), realization::get_values_as_type(), bmi::Bmi::GetVarItemsize(), bmi::Bmi::GetVarNbytes(), geojson::List, geojson::Natural, geojson::Real, bmi::Bmi::SetValue(), and logging::warning().

Referenced by inner_create_formulation().

◆ set_model_initialized()

void realization::Bmi_Module_Formulation::set_model_initialized ( bool is_initialized )

protectedvirtual

Set whether the backing model object has been initialize using the BMI standard Initialize function.

Parameters

is_initialized Whether model object has been initialize using the BMI standard Initialize.

References model_initialized.

◆ set_model_inputs_prior_to_update()

void realization::Bmi_Module_Formulation::set_model_inputs_prior_to_update	(	const double &	model_time,
		time_step_t	t_delta )

protected

Set BMI input variable values for the model appropriately prior to calling its BMIupdate()``.

Depending on the value of cache_input_variable_metadata (false by default, but which can be controlled using set_cache_input_var_metadata), this will defer most of its execution to a call either to do_bmi_sets_from_stored_metadata or do_bmi_sets_with_full_refetch.

Parameters

model_time	The model's time prior to the update, in its internal units and representation.
t_delta	The size of the time step over which the formulation is going to update the model, which might be different than the model's internal time step.

References cache_input_variable_metadata, realization::Bmi_Formulation::convert_model_time(), do_bmi_sets_from_stored_metadata(), do_bmi_sets_with_full_refetch(), and get_bmi_model_start_time_forcing_offset_s().

Referenced by update().

◆ set_model_type_name()

virtual void realization::Bmi_Formulation::set_model_type_name ( std::string type_name )

inlineprotectedvirtualinherited

Set the name of the specific type of the backing model object.

Parameters

type_name The name of the backing model object's type.

References realization::Bmi_Formulation::model_type_name.

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

◆ set_output_header_fields()

void realization::Bmi_Formulation::set_output_header_fields ( const std::vector< std::string > & output_headers )

inlineprotectedinherited

References realization::Bmi_Formulation::output_header_fields.

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

◆ set_output_precision()

void realization::Bmi_Formulation::set_output_precision ( int precision )

inlineinherited

Set the precision of output values when converted to text.

Parameters

precision The desired precision, as a number of decimal places.

References realization::Bmi_Formulation::output_precision, and realization::Bmi_Formulation::output_text_stream.

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

◆ set_output_variable_names()

void realization::Bmi_Formulation::set_output_variable_names ( const std::vector< std::string > & out_var_names )

inlineprotectedinherited

Set the names of variables in formulation output.

Set the names of the variables to include in the output from this formulation, which should be some ordered subset of the output variables from the model.

Parameters

out_var_names the names of variables in formulation output, in the order they should appear.

References realization::Bmi_Formulation::output_variable_names.

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

◆ update()

void realization::Bmi_Module_Formulation::update	(	time_step_t	t_index,
		time_step_t	t_delta )

overridevirtual

Implements realization::Bmi_Formulation.

References models::bmi::Bmi_Adapter::convert_seconds_to_model_time(), get_allow_model_exceed_end_time(), get_bmi_model(), realization::Formulation::get_formulation_type(), bmi::Bmi::GetCurrentTime(), next_time_step_index, set_model_inputs_prior_to_update(), bmi::Bmi::Update(), and bmi::Bmi::UpdateUntil().

Referenced by get_response().

◆ 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(), inner_create_formulation(), and realization::Formulation::interpret_parameters().

Friends And Related Symbol Documentation

◆ ::Bmi_C_Formulation_Test

friend class ::Bmi_C_Formulation_Test

friend

◆ ::Bmi_Cpp_Formulation_Test

friend class ::Bmi_Cpp_Formulation_Test

friend

◆ ::Bmi_Cpp_Multi_Array_Test

friend class ::Bmi_Cpp_Multi_Array_Test

friend

◆ ::Bmi_Formulation_Test

friend class ::Bmi_Formulation_Test

friend

◆ ::Bmi_Multi_Formulation_Test

friend class ::Bmi_Multi_Formulation_Test

friend

◆ Bmi_Multi_Formulation

friend class Bmi_Multi_Formulation

friend

Member Data Documentation

◆ allow_model_exceed_end_time

bool realization::Bmi_Module_Formulation::allow_model_exceed_end_time = false

private

Whether model Update calls are allowed and handled in some way by the backing model for time steps after the model's end_time.

Referenced by get_allow_model_exceed_end_time(), and set_allow_model_exceed_end_time().

◆ available_forcings

std::vector<std::string> realization::Bmi_Module_Formulation::available_forcings

private

The set of available "forcings" (output variables, plus their mapped aliases) that the model can provide.

Referenced by get_available_variable_names(), and inner_create_formulation().

◆ bmi_init_config

std::string realization::Bmi_Module_Formulation::bmi_init_config

private

Referenced by get_bmi_init_config(), and set_bmi_init_config().

◆ bmi_input_providers

std::unique_ptr<std::vector<std::shared_ptr<data_access::GenericDataProvider> > > realization::Bmi_Module_Formulation::bmi_input_providers

private

Vector of data providers for BMI input vars, with the provider at an index corresponding to the var in bmi_input_var_details at the same index.

As with bmi_input_var_details, these should be populated during the first call to do_bmi_sets_from_stored_metadata via a nested call to initialize_bmi_input_var_metadata.

Referenced by do_bmi_sets_from_stored_metadata(), and initialize_bmi_input_var_metadata().

◆ bmi_input_var_details

std::unique_ptr<std::vector<Bmi_Var_Details*> > realization::Bmi_Module_Formulation::bmi_input_var_details

private

BMI input variables details for this instance, cached to improve compute performance when setting values prior to updates.

This will hold cached details on input variables needed by this instance during do_bmi_sets_from_stored_metadata at each time step. It will be populated lazily on the first time step, via a nested call to initialize_bmi_input_var_metadata.

These should be pointers to Bmi_Var_Details instances in known_bmi_input_vars.

Referenced by do_bmi_sets_from_stored_metadata(), and initialize_bmi_input_var_metadata().

◆ bmi_main_output_var

std::string realization::Bmi_Formulation::bmi_main_output_var

privateinherited

Referenced by realization::Bmi_Formulation::get_bmi_main_output_var(), and realization::Bmi_Formulation::set_bmi_main_output_var().

◆ bmi_model

std::shared_ptr<models::bmi::Bmi_Adapter> realization::Bmi_Module_Formulation::bmi_model

private

Referenced by get_bmi_model(), and set_bmi_model().

◆ bmi_model_start_time_forcing_offset_s

time_t realization::Bmi_Module_Formulation::bmi_model_start_time_forcing_offset_s

private

The offset, converted to seconds, from the model's start time to the start time of the initial forcing time step.

Referenced by get_bmi_model_start_time_forcing_offset_s(), and set_bmi_model_start_time_forcing_offset_s().

◆ bmi_model_time_step_fixed

bool realization::Bmi_Module_Formulation::bmi_model_time_step_fixed = true

private

Whether backing model has fixed time step size.

Referenced by is_bmi_model_time_step_fixed(), and set_bmi_model_time_step_fixed().

◆ bmi_protocols

models::bmi::protocols::NgenBmiProtocols realization::Bmi_Module_Formulation::bmi_protocols

private

Referenced by check_mass_balance(), and inner_create_formulation().

◆ bmi_var_names_map

std::map<std::string, std::string> realization::Bmi_Module_Formulation::bmi_var_names_map

private

A configured mapping of BMI model variable names to standard names for use inside the framework.

Referenced by get_bmi_output_var_name(), get_config_mapped_variable_name(), and inner_create_formulation().

◆ bounds

polygon_t HY_CatchmentArea::bounds

protectedinherited

◆ cache_input_variable_metadata

bool realization::Bmi_Module_Formulation::cache_input_variable_metadata = false

private

Whether set_model_inputs_prior_to_update should store and reuse metadata.

Referenced by is_input_variable_metadata_cached(), set_cache_input_var_metadata(), and set_model_inputs_prior_to_update().

◆ cat_id

std::string realization::Catchment_Formulation::cat_id

privateinherited

Referenced by realization::Catchment_Formulation::get_catchment_id(), and realization::Catchment_Formulation::set_catchment_id().

◆ forcing

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

protectedinherited

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

◆ id

std::string realization::Formulation::id

protectedinherited

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

◆ id_number

unsigned long HY_CatchmentRealization::id_number

protectedinherited

◆ input_forcing_providers

std::map<std::string, std::shared_ptr<data_access::GenericDataProvider> > realization::Bmi_Module_Formulation::input_forcing_providers

protected

Referenced by get_provider_for_input_var().

◆ known_bmi_input_vars

std::set< Bmi_Var_Details > realization::Bmi_Module_Formulation::known_bmi_input_vars

staticprivate

BMI input variables details for all instances, cached to improve compute performance when setting values prior to updates.

Referenced by initialize_bmi_input_var_metadata().

◆ last_model_response_delta

time_step_t realization::Bmi_Module_Formulation::last_model_response_delta = 0

protected

The delta of the last model update execution (typically, this is time step size).

◆ last_model_response_start_time

time_t realization::Bmi_Module_Formulation::last_model_response_start_time = 0

protected

The epoch time of the model at the beginning of its last update.

◆ model_initialized

bool realization::Bmi_Module_Formulation::model_initialized = false

private

Referenced by inner_create_formulation(), is_model_initialized(), and set_model_initialized().

◆ model_type_name

std::string realization::Bmi_Formulation::model_type_name

privateinherited

Referenced by realization::Bmi_Formulation::get_model_type_name(), and realization::Bmi_Formulation::set_model_type_name().

◆ next_time_step_index

int realization::Bmi_Module_Formulation::next_time_step_index = 0

protected

Index value (0-based) of the time step that will be processed by the next update of the model.

A formulation time step for BMI types can be thought of as the execution of a call to any of the functions of the underlying BMI model that advance the model (either update or update_until). This member stores the ordinal index of the next time step to be executed. Except in the initial formulation state, this will be one greater than the index of the last executed time step.

E.g., on initialization, before any calls to get_response, this value will be 0. After a call to get_response (assuming 0 as the passed t_index argument), time step 0 will be processed, and this member would be incremented by 1, thus making it 1.

The member serves as an implicit marker of how many time steps have been processed so far. Knowing this is required to maintain valid behavior in certain things, such as get_response (we may want to process multiple time steps forward to a particular index other than the next, but it would not be valid to receive a t_index earlier than the last processed time step) and get_output_values_for_timestep (because formulations do not save results from previous time steps, only the results from the last processed time step can be used to generate output).

Referenced by get_output_values_for_timestep(), and update().

◆ OPTIONAL_PARAMETERS

std::vector<std::string> realization::Bmi_Module_Formulation::OPTIONAL_PARAMETERS

private

Initial value:

= {
                BMI_REALIZATION_CFG_PARAM_OPT__USES_FORCINGS
                BMI_REALIZATION_CFG_PARAM_OPT__FORCING_FILE,
                BMI_REALIZATION_CFG_PARAM_OPT__VAR_STD_NAMES,
                BMI_REALIZATION_CFG_PARAM_OPT__OUT_VARS,
                BMI_REALIZATION_CFG_PARAM_OPT__OUT_HEADER_FIELDS,
                BMI_REALIZATION_CFG_PARAM_OPT__OUTPUT_PRECISION,
                BMI_REALIZATION_CFG_PARAM_OPT__ALLOW_EXCEED_END,
                BMI_REALIZATION_CFG_PARAM_OPT__FIXED_TIME_STEP,
                BMI_REALIZATION_CFG_PARAM_OPT__LIB_FILE
        }

◆ output

utils::StreamHandler HY_CatchmentArea::output

protectedinherited

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

◆ output_header_fields

std::vector<std::string> realization::Bmi_Formulation::output_header_fields

privateinherited

Output header field strings corresponding to the variables output by the realization, as defined in output_variable_names.

Referenced by realization::Bmi_Formulation::get_output_header_field_names(), and realization::Bmi_Formulation::set_output_header_fields().

◆ output_precision

int realization::Bmi_Formulation::output_precision

privateinherited

The degree of precision in output values when converting to text.

Referenced by realization::Bmi_Formulation::get_output_precision(), and realization::Bmi_Formulation::set_output_precision().

◆ output_text_stream

std::shared_ptr<std::ostringstream> realization::Bmi_Formulation::output_text_stream

protectedinherited

Object to help with converting numeric output values to text.

Referenced by realization::Bmi_Formulation::set_output_precision().

◆ output_variable_names

std::vector<std::string> realization::Bmi_Formulation::output_variable_names

privateinherited

Names of the variables to include in the output from this formulation, which will be some ordered subset of the BMI module output variables accessible to the instance.

Referenced by realization::Bmi_Formulation::get_output_variable_names(), and realization::Bmi_Formulation::set_output_variable_names().

◆ realized_catchment

std::shared_ptr<HY_Catchment> HY_CatchmentRealization::realized_catchment

protectedinherited

◆ REQUIRED_PARAMETERS

std::vector<std::string> realization::Bmi_Module_Formulation::REQUIRED_PARAMETERS

private

Initial value:

= {
                BMI_REALIZATION_CFG_PARAM_REQ__INIT_CONFIG,
                BMI_REALIZATION_CFG_PARAM_REQ__MAIN_OUT_VAR,
                BMI_REALIZATION_CFG_PARAM_REQ__MODEL_TYPE,
        }

Referenced by get_required_parameters().

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

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ data_type

◆ selection_type

◆ time_step_t

Constructor & Destructor Documentation

◆ Bmi_Module_Formulation()

◆ ~Bmi_Module_Formulation()

Member Function Documentation

◆ check_mass_balance()

◆ config_pattern_substitution()

◆ construct_model()

◆ convert_model_time()

◆ create_formulation() [1/2]

◆ create_formulation() [2/2]

◆ determine_model_time_offset()

◆ do_bmi_sets_from_stored_metadata()

◆ do_bmi_sets_with_full_refetch()

◆ finalize() [1/2]

◆ finalize() [2/2]

◆ get_allow_model_exceed_end_time()

◆ get_available_variable_names()

◆ get_bmi_init_config()

◆ get_bmi_input_variables()

◆ get_bmi_main_output_var()

◆ get_bmi_model()

◆ get_bmi_model_start_time_forcing_offset_s()

◆ get_bmi_output_var_name()

◆ get_bmi_output_variables()

◆ get_catchment_id()

◆ get_config_mapped_variable_name()

◆ get_data_start_time()

◆ get_data_stop_time()

◆ get_formulation_type()

◆ get_id()

◆ get_model_current_time()

◆ get_model_end_time()

◆ get_model_type_name()

◆ get_output_fields()

◆ get_output_header_field_names()

◆ get_output_precision()

◆ get_output_values_for_timestep()

◆ get_output_variable_names()

◆ get_provider_for_input_var()

◆ get_required_parameters()

◆ get_response()

◆ get_ts_index_for_time()

◆ get_value() [1/2]

◆ get_value() [2/2]

◆ get_values() [1/2]

◆ get_values() [2/2]

◆ get_var_value_as_double()

◆ get_variable_time_begin()

◆ initialize_bmi_input_var_metadata()

◆ inner_create_formulation()

◆ interpret_parameters()

◆ is_bmi_input_variable()

◆ is_bmi_model_time_step_fixed()

◆ is_bmi_output_variable()

◆ is_input_variable_metadata_cached()

◆ is_model_initialized()

◆ is_property_sum_over_time_step()

◆ perform_set()

◆ record_duration()

◆ set_allow_model_exceed_end_time()

◆ set_bmi_init_config()

◆ set_bmi_main_output_var()

◆ set_bmi_model()

◆ set_bmi_model_start_time_forcing_offset_s()

◆ set_bmi_model_time_step_fixed()

◆ set_cache_input_var_metadata()