Extension of DeferredWrappedProvider, where default values can be used instead of a backing provider. More...

#include <OptionalWrappedDataProvider.hpp>

Inheritance diagram for data_access::OptionalWrappedDataProvider:

Collaboration diagram for data_access::OptionalWrappedDataProvider:

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

using	selection_type = SelectionType

Public Member Functions
	OptionalWrappedDataProvider (std::vector< std::string > providedOuts, std::map< std::string, double > defaultVals)
	Constructor for instance.

	OptionalWrappedDataProvider (std::vector< std::string > providedOuts, std::map< std::string, double > defaultVals, std::map< std::string, int > defaultWaits)
	Constructor for instance including defaults and default wait counts.

	OptionalWrappedDataProvider (std::vector< std::string > providedOutputs)
	Convenience constructor for instance when default values are not provided.

	OptionalWrappedDataProvider (const std::string &outputName)
	Convenience constructor for when there is only one provided output name, which does not have a default.

	OptionalWrappedDataProvider (const std::string &outputName, double defaultValue, int defaultUsageWait)
	Convenience constructor for instance with one output and default that must be used a minimum number of times.

	OptionalWrappedDataProvider (const std::string &outputName, double defaultValue)
	Convenience constructor for when there is only one provided output name, which has a default value.

	OptionalWrappedDataProvider (OptionalWrappedDataProvider &&provider_to_move) noexcept
	Move constructor.

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.

bool	isDefaultOverride (const std::string &output_name)
	Test whether an available default should override an available backing provider output value.

bool	isReadyToProvideData () override
	Get whether the instance is initialized such that it can handle requests to provide data.

bool	isSuppliedWithDefault (const std::string &outputName)
	Test whether the instance was supplied with default values that can be returned for this output.

bool	setWrappedProvider (GenericDataProvider *provider) override
	Set the wrapped provider, if the given arg is valid for doing so.

boost::span< const std::string >	get_available_variable_names () const override
	Get the names of the outputs that this instance is (or will be) able to provide.

const std::string &	getSetMessage ()
	Get the message string for the last call to setWrappedProvider.

bool	isWrappedProviderSet ()
	Get whether the backing provider this instance wraps has been set yet.

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

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
	Get the exclusive ending of the period of time over which this instance can provide data for this forcing.

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

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.

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.

std::vector< double >	get_values (const CatchmentAggrDataSelector &selector, ReSampleMethod m) override

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.

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.

Protected Member Functions
virtual void	recordUsingDefault (const std::string &output_name)
	Record that there was an instance of a default value being used and manage the default usage "waits.".

Protected Attributes
std::vector< std::string >	providedOutputs
	The collection of names of the outputs this type can/will be able to provide from its wrapped source.

std::string	setMessage
	A message providing information from the last setWrappedProvider call.

GenericDataProvider *	wrapped_provider

Private Member Functions
bool	isSuppliedByWrappedProvider (const std::string &outputName)

Static Private Member Functions
static bool	isSuppliedByProvider (const std::string &outputName, GenericDataProvider *provider)

Private Attributes
std::map< std::string, double >	defaultValues
	A collection of mapped default values for some or all of the provided outputs.

std::map< std::string, int >	defaultUsageWaits
	The number of times a default value should still be used before beginning to proxy a backing provider value.

Detailed Description

Extension of DeferredWrappedProvider, where default values can be used instead of a backing provider.

Default Values

This type supports receiving at construction a collection of default values. A default value can be supplied for one or more of the outputs the instance is create to provide.

When a default is available for an output, an instance can use this default as the return value for calls to get_value instead of proxying a value from a backing provider.

Valid Wrapped Providers And Readiness

The potential of default values has implications on what constitutes a valid wrapped provider. In this type's parent, setWrappedProvider will only set the member variable if the would-be-wrapped-provider provides all outputs required by the instance. For this type, that restriction is loosened, and the wrapped provider need not provide all the outputs required by the instance.

If the instance has a default value for an output, then a would-be-wrapped-provider is not required to provide that output. It must still provide all outputs for which the instance does not have a default value.

The addition of default values also introduces an interesting edge case: when default values are provided for all an instance's outputs. There are two important implications of this. First, an instance requires a valid wrapped provider to provide at least one of the instance's outputs. Second, an instance does not necessarily need a wrapped provider to be set in order to be ready.

When The Default Is Used

A default value will be used any time one is available for an output and a valid cannot be obtained from a wrapped provider.

Additionally, an instance can created to override a backing provider in certain situations. One or more "wait" counts can be supplied to the constructor. These "wait" counts represent the number of times an instance should wait to proxy the corresponding output's value from a wrapped provider and instead return the default value.

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

Constructor & Destructor Documentation

◆ OptionalWrappedDataProvider() [1/7]

data_access::OptionalWrappedDataProvider::OptionalWrappedDataProvider	(	std::vector< std::string >	providedOuts,
		std::map< std::string, double >	defaultVals )

inline

Constructor for instance.

Also validates that given defaults only contain keys that are in given provided outputs.

Parameters

providedOuts	The collection of the names of outputs this instance will need to provide.
defaultVals	Mapping of some or all provided output defaults, keyed by output name.

References defaultValues, and data_access::DeferredWrappedProvider::providedOutputs.

◆ OptionalWrappedDataProvider() [2/7]

data_access::OptionalWrappedDataProvider::OptionalWrappedDataProvider	(	std::vector< std::string >	providedOuts,
		std::map< std::string, double >	defaultVals,
		std::map< std::string, int >	defaultWaits )

inline

Constructor for instance including defaults and default wait counts.

Also validates that given defaults only contain keys that are in given provided outputs.

Parameters

providedOuts	The collection of the names of outputs this instance will need to provide.
defaultVals	Mapping of some or all provided output defaults, keyed by output name.
defaultWaits	Map of the number of default usages for each provided output that the instance must wait before using values from the backing provider.

◆ OptionalWrappedDataProvider() [3/7]

data_access::OptionalWrappedDataProvider::OptionalWrappedDataProvider ( std::vector< std::string > providedOutputs )

inlineexplicit

Convenience constructor for instance when default values are not provided.

Parameters

providedOutputs The collection of the names of outputs this instance will need to provide.

◆ OptionalWrappedDataProvider() [4/7]

data_access::OptionalWrappedDataProvider::OptionalWrappedDataProvider ( const std::string & outputName )

inlineexplicit

Convenience constructor for when there is only one provided output name, which does not have a default.

Parameters

outputName The name of the single output this instance will need to provide.

◆ OptionalWrappedDataProvider() [5/7]

data_access::OptionalWrappedDataProvider::OptionalWrappedDataProvider	(	const std::string &	outputName,
		double	defaultValue,
		int	defaultUsageWait )

inline

Convenience constructor for instance with one output and default that must be used a minimum number of times.

This constructor sets up the instance to provide an output and be able to supply a default value if the backing provider is not set. It also sets a minimum number of forced usages of the default value. This will result in the default being used even if the backing provider has been set, according to the implementations of isDefaultOverride and recordUsingDefault.

Parameters

outputName	The name of the single output this instance will need to provide.
defaultValue	The default to associate with the given output.
defaultUsageWait	The number of default usages that the instance must wait before using values from the backing provider.

◆ OptionalWrappedDataProvider() [6/7]

data_access::OptionalWrappedDataProvider::OptionalWrappedDataProvider	(	const std::string &	outputName,
		double	defaultValue )

inline

Convenience constructor for when there is only one provided output name, which has a default value.

Parameters

outputName	The name of the single output this instance will need to provide.
defaultValue	The default to associate with the given output.

◆ OptionalWrappedDataProvider() [7/7]

data_access::OptionalWrappedDataProvider::OptionalWrappedDataProvider ( OptionalWrappedDataProvider && provider_to_move )

inlinenoexcept

Move constructor.

Parameters

provider_to_move

Member Function Documentation

◆ finalize()

void data_access::WrappedDataProvider::finalize ( )

inlineoverridevirtualinherited

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

In particular, this should be called before MPI_Finalize()

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

◆ get_available_variable_names()

boost::span< const std::string > data_access::DeferredWrappedProvider::get_available_variable_names ( ) const

inlineoverridevirtualinherited

Get the names of the outputs that this instance is (or will be) able to provide.

Note that this function behaves the same regardless of whether the wrapped provider has been set.

Returns: The names of the outputs for which this instance is (or will be) able to provide values.

Implements data_access::DataProvider< DataType, SelectionType >.

References data_access::DeferredWrappedProvider::providedOutputs.

◆ get_data_start_time()

long data_access::WrappedDataProvider::get_data_start_time ( ) const

inlineoverridevirtualinherited

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

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

Implements data_access::DataProvider< DataType, SelectionType >.

References data_access::DataProvider< DataType, SelectionType >::get_data_start_time(), and data_access::WrappedDataProvider::wrapped_provider.

◆ get_data_stop_time()

long data_access::WrappedDataProvider::get_data_stop_time ( ) const

inlineoverridevirtualinherited

Get the exclusive ending of the period of time over which this instance can provide data for this forcing.

Returns: The exclusive ending of the period of time over which this instance can provide this data.

Implements data_access::DataProvider< DataType, SelectionType >.

References data_access::DataProvider< DataType, SelectionType >::get_data_stop_time(), and data_access::WrappedDataProvider::wrapped_provider.

◆ get_ts_index_for_time()

size_t data_access::WrappedDataProvider::get_ts_index_for_time ( const time_t & epoch_time ) const

inlineoverridevirtualinherited

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

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

References data_access::DataProvider< DataType, SelectionType >::get_ts_index_for_time(), and data_access::WrappedDataProvider::wrapped_provider.

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

◆ get_value() [2/2]

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

inlineoverride

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

This implementation can supply a default value in certain cases. Otherwise, it defers to the wrapped, backing object.

An 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

out_of_range If data for the time period is not available.

References CatchmentAggrDataSelector::get_duration_secs(), CatchmentAggrDataSelector::get_init_time(), CatchmentAggrDataSelector::get_output_units(), and CatchmentAggrDataSelector::get_variable_name().

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

◆ get_values() [2/2]

std::vector< double > data_access::WrappedDataProvider::get_values	(	const CatchmentAggrDataSelector &	selector,
		ReSampleMethod	m )

inlineoverrideinherited

References data_access::DataProvider< DataType, SelectionType >::get_values(), and data_access::WrappedDataProvider::wrapped_provider.

◆ getSetMessage()

const std::string & data_access::DeferredWrappedProvider::getSetMessage ( )

inlineinherited

Get the message string for the last call to setWrappedProvider.

The value of the backing member for this function will be empty if the last call to setWrappedProvider returned true (or has not been called yet). If setWrappedProvider it returned false, then an info message will be saved in the member returned by this function, explaining more detail on the failure.

Returns: The message string for the last call to setWrappedProvider.

References data_access::DeferredWrappedProvider::setMessage.

◆ is_property_sum_over_time_step()

bool data_access::WrappedDataProvider::is_property_sum_over_time_step ( const std::string & name ) const

inlineoverridevirtualinherited

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

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.

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.

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

References data_access::DataProvider< DataType, SelectionType >::is_property_sum_over_time_step(), and data_access::WrappedDataProvider::wrapped_provider.

◆ isDefaultOverride()

bool data_access::OptionalWrappedDataProvider::isDefaultOverride ( const std::string & output_name )

inline

Test whether an available default should override an available backing provider output value.

This method returns whether an default value is available and, despite there being a wrapped backing provider that can provide the given output, that the default value should be used instead of the backing value.

When constructed, this instance may have been provided with a number of default usage "waits" for one or more outputs; i.e., a number of times it should wait to proxy a particular output value from the backing provider and instead allow a default value to override the aforementioned backing value. This function tests whether the object is in a state in which such an override applies, with respect to the given output.

The rules for transitioning through default usage "waits" are implemented in recordUsingDefault.

Note that the intent of the function is not the same as "should use default." As such, the function will return false in cases when there is not a backing provider or the backing provider cannot provide the given output, even if there is a suitable default available.

Parameters

output_name The name of the output in question.

Returns: Whether an available default should override an available backing provider output value.

See also: get_value; recordUsingDefault

◆ isReadyToProvideData()

bool data_access::OptionalWrappedDataProvider::isReadyToProvideData ( )

inlineoverridevirtual

Get whether the instance is initialized such that it can handle requests to provide data.

For this type, return whether the instance is ready to provide data. The primary satisfying condition is when the wrapped provider member has been set, as determined by isWrappedProviderSet. Secondarily, "readiness" is also satisfied if there are default values set up for all outputs that must be provided.

Note that the primary condition is subject only to the result of isWrappedProviderSet, which for this type (and generally) does not reflect the readiness state of the inner, wrapped provider. This effectively assumes it is ready prior to or immediately upon being set.

Returns: Whether the instance is initialized such that it can handle requests to provide data.

Reimplemented from data_access::DeferredWrappedProvider.

◆ isSuppliedByProvider()

static bool data_access::OptionalWrappedDataProvider::isSuppliedByProvider	(	const std::string &	outputName,
		GenericDataProvider *	provider )

inlinestaticprivate

References data_access::DataProvider< DataType, SelectionType >::get_available_variable_names().

◆ isSuppliedByWrappedProvider()

bool data_access::OptionalWrappedDataProvider::isSuppliedByWrappedProvider ( const std::string & outputName )

inlineprivate

◆ isSuppliedWithDefault()

bool data_access::OptionalWrappedDataProvider::isSuppliedWithDefault ( const std::string & outputName )

inline

Test whether the instance was supplied with default values that can be returned for this output.

Parameters

outputName The output in question.

Returns: Whether a default value is available for this output.

◆ isWrappedProviderSet()

bool data_access::DeferredWrappedProvider::isWrappedProviderSet ( )

inlineinherited

Get whether the backing provider this instance wraps has been set yet.

Returns: Whether the backing provider this instance wraps has been set yet.

References data_access::WrappedDataProvider::wrapped_provider.

Referenced by data_access::DeferredWrappedProvider::isReadyToProvideData(), and data_access::DeferredWrappedProvider::setWrappedProvider().

◆ record_duration()

long data_access::WrappedDataProvider::record_duration ( ) const

inlineoverridevirtualinherited

Return the stride in the time dimension.

Implements data_access::DataProvider< DataType, SelectionType >.

References data_access::DataProvider< DataType, SelectionType >::record_duration(), and data_access::WrappedDataProvider::wrapped_provider.

◆ recordUsingDefault()

virtual void data_access::OptionalWrappedDataProvider::recordUsingDefault ( const std::string & output_name )

inlineprotectedvirtual

Record that there was an instance of a default value being used and manage the default usage "waits.".

When constructed, this instance may have been provided with a number of default usage "waits" for one or more outputs; i.e., a number of times it should wait to proxy a particular output value from the backing provider and instead allow a default value to override the aforementioned backing value. This function, which should be called by get_value any time a default is used, performs any modifications to the object's state that are necessary when a default is used, in particular with respect to managing "waits."

In this base implementation, a recorded default usage does not count against the required number of "waits" for an output unless/until there is a wrapped backing provider set that can provide the given output. Otherwise, positive wait counts for this output be reduced by 1. This allows negative wait counts to be used to represent that some output should always have the default used, even if the backing provider could supply a value for it.

Parameters

output_name The name of the output for which a default was used.

◆ setWrappedProvider()

bool data_access::OptionalWrappedDataProvider::setWrappedProvider ( GenericDataProvider * provider )

inlineoverridevirtual

Set the wrapped provider, if the given arg is valid for doing so.

For a valid provider pointer argument, set the wrapped provider to it, clear the info message and return true. For an invalid arg, set the info message member to provide details on why it is invalid. Then return false without setting the wrapped provider.

There are several invalid argument cases:

a null pointer, except when all provided outputs have a default available
a pointer to a provider that cannot provide all the required outputs this instance must proxy
- only values that do not have a default available are considered required
any arg if there has already been a valid provider set

Parameters

provider A pointer for the wrapped provider.

Returns: Whether wrapped_provider was set to the given arg.

Reimplemented from data_access::DeferredWrappedProvider.

Member Data Documentation

◆ defaultUsageWaits

std::map<std::string, int> data_access::OptionalWrappedDataProvider::defaultUsageWaits

private

The number of times a default value should still be used before beginning to proxy a backing provider value.

Note than all elements should have values greater than zero. Any elements that would have their value reduced to zero should instead be removed.

◆ defaultValues

std::map<std::string, double> data_access::OptionalWrappedDataProvider::defaultValues

private

A collection of mapped default values for some or all of the provided outputs.

Referenced by OptionalWrappedDataProvider().

◆ providedOutputs

std::vector<std::string> data_access::DeferredWrappedProvider::providedOutputs

protectedinherited

The collection of names of the outputs this type can/will be able to provide from its wrapped source.

Referenced by data_access::DeferredWrappedProvider::DeferredWrappedProvider(), OptionalWrappedDataProvider(), data_access::DeferredWrappedProvider::get_available_variable_names(), and data_access::DeferredWrappedProvider::setWrappedProvider().

◆ setMessage

std::string data_access::DeferredWrappedProvider::setMessage

protectedinherited

A message providing information from the last setWrappedProvider call.

The value will be empty if the function returned true. If it returned false, this will have an info message set explaining more detail on the failure.

Referenced by data_access::DeferredWrappedProvider::getSetMessage(), and data_access::DeferredWrappedProvider::setWrappedProvider().

◆ wrapped_provider

GenericDataProvider* data_access::WrappedDataProvider::wrapped_provider

protectedinherited

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

include/forcing/OptionalWrappedDataProvider.hpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Default Values

Valid Wrapped Providers And Readiness

When The Default Is Used

Member Typedef Documentation

◆ data_type

◆ selection_type

Constructor & Destructor Documentation

◆ OptionalWrappedDataProvider() [1/7]

◆ OptionalWrappedDataProvider() [2/7]

◆ OptionalWrappedDataProvider() [3/7]

◆ OptionalWrappedDataProvider() [4/7]

◆ OptionalWrappedDataProvider() [5/7]

◆ OptionalWrappedDataProvider() [6/7]

◆ OptionalWrappedDataProvider() [7/7]

Member Function Documentation

◆ finalize()

◆ get_available_variable_names()

◆ get_data_start_time()

◆ get_data_stop_time()

◆ get_ts_index_for_time()

◆ get_value() [1/2]

◆ get_value() [2/2]

◆ get_values() [1/2]

◆ get_values() [2/2]

◆ getSetMessage()

◆ is_property_sum_over_time_step()

◆ isDefaultOverride()

◆ isReadyToProvideData()

◆ isSuppliedByProvider()

◆ isSuppliedByWrappedProvider()

◆ isSuppliedWithDefault()

◆ isWrappedProviderSet()

◆ record_duration()

◆ recordUsingDefault()

◆ setWrappedProvider()

Member Data Documentation

◆ defaultUsageWaits

◆ defaultValues

◆ providedOutputs

◆ setMessage

◆ wrapped_provider