A specialized @WrappedDataProvider that is created without first knowing the backing source it wraps. More...

#include <DeferredWrappedProvider.hpp>

Inheritance diagram for data_access::DeferredWrappedProvider:

Collaboration diagram for data_access::DeferredWrappedProvider:

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

using	selection_type = SelectionType

Public Member Functions
	DeferredWrappedProvider (std::vector< std::string > providedOutputs)
	Constructor for instance.

	DeferredWrappedProvider (const std::string &outputName)
	Convenience constructor for when there is only one provided output name.

	DeferredWrappedProvider (DeferredWrappedProvider &&provider_to_move) noexcept
	Move constructor.

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.

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

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

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

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.

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

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

Detailed Description

A specialized @WrappedDataProvider that is created without first knowing the backing source it wraps.

This type wraps another GenericDataProvider, similarly to its parent. This is "optimistic," however, in that it is constructed without the backing data source it will wrap. It only requires the data output names it expects to eventually be able to provide.

This type allows for deferring reconciling of whether a provider for some data output is available. This is useful for situations when a required provider is not currently known, but is expected, and there will be ample time to validate the expectation and make the necessary associations before the data must be provided.

The runtime behavior of inherited functions depends on the type of the wrapped object. I.e., nested calls to the analogous function of the wrapped provider object are made, with those results returned. The one exception to this is get_available_forcing_outputs. A particular effect of this is that the type of the wrapped provider object will dictate how an instance behaves in cases when an unrecognized output name is supplied as a parameter to get_value.

As noted above, the get_available_forcing_outputs virtual function is overridden here. Instead of directly returning results from a nested call to the wrapped provider, this type's implementation ensures only the outputs set as provideable in this instance (i.e., the outer wrapper) are returned.

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

◆ DeferredWrappedProvider() [1/3]

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

inlineexplicit

Constructor for instance.

Parameters

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

◆ DeferredWrappedProvider() [2/3]

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

inlineexplicit

Convenience constructor for when there is only one provided output name.

Parameters

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

References providedOutputs.

◆ DeferredWrappedProvider() [3/3]

data_access::DeferredWrappedProvider::DeferredWrappedProvider ( DeferredWrappedProvider && provider_to_move )

inlinenoexcept

Move constructor.

Parameters

provider_to_move

References data_access::WrappedDataProvider::wrapped_provider.

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

inlineoverridevirtual

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 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::WrappedDataProvider::get_value	(	const CatchmentAggrDataSelector &	selector,
		ReSampleMethod	m )

inlineoverrideinherited

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

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.

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

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

inline

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

◆ isReadyToProvideData()

virtual bool data_access::DeferredWrappedProvider::isReadyToProvideData ( )

inlinevirtual

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

For this type, this is equivalent to whether the wrapped provider member has been set.

Note that readiness 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 in data_access::OptionalWrappedDataProvider.

References isWrappedProviderSet().

◆ isWrappedProviderSet()

bool data_access::DeferredWrappedProvider::isWrappedProviderSet ( )

inline

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 isReadyToProvideData(), and 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.

◆ setWrappedProvider()

virtual bool data_access::DeferredWrappedProvider::setWrappedProvider ( GenericDataProvider * provider )

inlinevirtual

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:

an arg that is actually a null pointer
an arg that points to a provider that does not itself provide all the required outputs this must provide
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 in data_access::OptionalWrappedDataProvider.

References data_access::DataProvider< DataType, SelectionType >::get_available_variable_names(), isWrappedProviderSet(), providedOutputs, setMessage, and data_access::WrappedDataProvider::wrapped_provider.

Member Data Documentation

◆ providedOutputs

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

protected

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

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

◆ setMessage

std::string data_access::DeferredWrappedProvider::setMessage

protected

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 getSetMessage(), and setWrappedProvider().

◆ wrapped_provider

GenericDataProvider* data_access::WrappedDataProvider::wrapped_provider

protectedinherited

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

include/forcing/DeferredWrappedProvider.hpp

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ data_type

◆ selection_type

Constructor & Destructor Documentation

◆ DeferredWrappedProvider() [1/3]

◆ DeferredWrappedProvider() [2/3]

◆ DeferredWrappedProvider() [3/3]

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

◆ isReadyToProvideData()

◆ isWrappedProviderSet()

◆ record_duration()

◆ setWrappedProvider()

Member Data Documentation

◆ providedOutputs

◆ setMessage

◆ wrapped_provider