models::bmi Namespace Reference

Namespaces
namespace	helper
namespace	protocols

Classes
class	AbstractCLibBmiAdapter
class	Bmi_Adapter
	Abstract adapter interface for C++ classes to interact with the essential aspects of external models that implement the BMI spec but that are written in some other programming language. More...
class	Bmi_C_Adapter
	An adapter class to serve as a C++ interface to the essential aspects of external models written in the C language that implement the BMI. More...
class	Bmi_Cpp_Adapter
	A thin wrapper class to provide convenience functions around raw BMI models written in C++, especially those loaded dynamically from libraries. More...
struct	unknown_bmi_type
	Thrown when a BMI type name has no C++ type behind it. More...

Functions
template<typename F >
auto	with_bmi_type (const std::string &type, F &&f)
	Call f with the C++ type that a BMI type name denotes.
void	require_item_size (const std::string &type, size_t item_size, const std::string &described)
	Throw unless type names a C++ type of exactly item_size bytes.
template<typename T , typename Iterator >
std::shared_ptr< T >	as_c_array (Iterator begin, Iterator end)
	Template function for copying iterator range into contiguous array.
template<typename Iterator >
std::shared_ptr< void >	get_values_as_type (std::string type, Iterator begin, Iterator end)
	Gets values in iterator range, casted based on type then returned as typeless (void) pointer.
template<typename T >
std::shared_ptr< void >	get_value_as_type (std::string type, T value)
	Gets a single value, casted based on type then returned as a typeless (void) pointer.
template<typename T >
T *	GetValuePtr (Bmi_Adapter &model, const std::string &name)
	Get a pointer to a model variable's own storage, addressed as.
template<typename T >
std::vector< T >	GetValue (Bmi_Adapter &model, const std::string &name)
	Copy values from a BMI model adapter and box them into a vector.

Function Documentation

as_c_array()

template<typename T , typename Iterator >

std::shared_ptr< T > models::bmi::as_c_array	(	Iterator	begin,
		Iterator	end )

Template function for copying iterator range into contiguous array.

This function will iterate the range and cast the iterator value to type T and copy that value into a C-like array of contiguous, dynamically allocated memory. This array is stored in a smart pointer with a custom array deleter.

Template Parameters

T
Iterator

Parameters

begin
end

Returns

std::shared_ptr<T>

Referenced by get_values_as_type().

get_value_as_type()

template<typename T >

std::shared_ptr< void > models::bmi::get_value_as_type	(	std::string	type,
		T	value )

Gets a single value, casted based on type then returned as a typeless (void) pointer.

Template Parameters

T

Parameters

type
value

Returns

std::shared_ptr<void>

References with_bmi_type().

get_values_as_type()

template<typename Iterator >

std::shared_ptr< void > models::bmi::get_values_as_type	(	std::string	type,
		Iterator	begin,
		Iterator	end )

Gets values in iterator range, casted based on type then returned as typeless (void) pointer.

Template Parameters

Iterator

Parameters

type
begin
end

Returns

std::shared_ptr<void>

References as_c_array(), and with_bmi_type().

GetValue()

template<typename T >

std::vector< T > models::bmi::GetValue	(	Bmi_Adapter &	model,
		const std::string &	name )

Copy values from a BMI model adapter and box them into a vector.

Template Parameters

T	Type to cast data from the BMI model to
A	Bmi model type

Parameters

model

Bmi model adapter that interfaces to

Template Parameters

A

bmi

Parameters

name	Bmi variable name to query the model for

Returns

std::vector<T> Copy of data from the BMI model for variable

Parameters

name

References models::bmi::Bmi_Adapter::get_analogous_cxx_type(), models::bmi::Bmi_Adapter::get_model_name(), bmi::Bmi::GetValue(), bmi::Bmi::GetVarItemsize(), bmi::Bmi::GetVarNbytes(), bmi::Bmi::GetVarType(), models::bmi::helper::make_vector(), require_item_size(), and with_bmi_type().

Referenced by models::bmi::protocols::NgenMassBalance::check_support(), realization::Bmi_Module_Formulation::get_values(), realization::Bmi_C_Formulation::get_var_value_as(), realization::Bmi_Cpp_Formulation::get_var_value_as(), and models::bmi::protocols::NgenMassBalance::run().

GetValuePtr()

template<typename T >

T * models::bmi::GetValuePtr	(	Bmi_Adapter &	model,
		const std::string &	name )

Get a pointer to a model variable's own storage, addressed as.

Template Parameters

T.

The sibling of GetValue() for callers that want the model's memory rather than a copy of it. Bmi_Adapter exposes the pointer untyped, because BMI has no way to describe what is behind it; every caller therefore has to supply the type, and nothing in BMI obliges that type to be the width the model allocated. Indexing with the wrong stride walks off the variable, so the item size is checked here rather than at each call site.

An adapter whose language cannot hand out pointers says so from GetValuePtr() itself; this does not need to know which those are.

Template Parameters

T	The type to address the variable's storage as.

Parameters

model	The adapter holding the variable.
name	The name of the variable.

Returns

A pointer to the model's own storage, which the model continues to own.

Exceptions

std::runtime_error

If the model's items are not

Template Parameters

T	wide, or it cannot give a pointer.

References models::bmi::Bmi_Adapter::get_model_name(), bmi::Bmi::GetValuePtr(), and bmi::Bmi::GetVarItemsize().

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

require_item_size()

void models::bmi::require_item_size ( const std::string & type, size_t item_size, const std::string & described )

inline

Throw unless type names a C++ type of exactly item_size bytes.

A model reports a variable's type name and the size of one item separately, and nothing in BMI makes the two agree. Every buffer here is sized from one and addressed as the other, so a disagreement reads or writes past the end – on a read, out of the buffer; on a write, out of it by whatever the model takes. Neither is detectable afterwards, so refuse up front.

Parameters

type	A BMI type name.
item_size	The size in bytes of one item, as the model reports it.
described	What is being resolved, for the message; e.g. "variable 'X' of model 'Y'".

Exceptions

unknown_bmi_type	If type has no C++ type behind it.
std::runtime_error	If that type is not item_size bytes.

References with_bmi_type().

Referenced by realization::Bmi_Var_Details::Bmi_Var_Details(), GetValue(), and realization::Bmi_Module_Formulation::set_initial_bmi_parameters().

with_bmi_type()

template<typename F >

auto models::bmi::with_bmi_type	(	const std::string &	type,
		F &&	f )

Call f with the C++ type that a BMI type name denotes.

BMI reports a variable's type as a string, and every operation on that variable has to pick the matching C++ type before it can do anything. This is the one place that mapping lives: f is a callable with a template parameter, invoked as f.template operator()<T>(), and this picks the T.

Several spellings may denote one type – "real" and "float", "integer" and "int" – and the table resolves them alike. Which spelling a given model reports is not this function's concern.

// "Give me this value as whatever the variable declares." The target type is a string, so the
// cast cannot be written directly: capture the value, and let the table supply the type.
std::shared_ptr<void> as_declared_type(const std::string &type, double value)
{
    return with_bmi_type(type, [&]<typename T>() -> std::shared_ptr<void> {
        return std::make_shared<T>(static_cast<T>(value));
    });
}

Two things there are easy to get wrong.

The lambda takes no arguments. value arrives by capture, which leaves the parameter list free for the one thing this function supplies – f.template operator()<T>() passes a type and nothing else. That is what lets one table serve callers whose data is a scalar, an iterator pair, or a pointer and a count: each seals its own data into the closure.

The -> std::shared_ptr<void> is load-bearing. make_shared<T> yields a shared_ptr<T>, a different type in every branch, and the branches have to agree on one return type. Converting there is the only place T is still known. Omitting it is a compile error rather than a silent conversion – as is a body that does not compile for every type below, even one no caller ever asks for, since all of them are instantiated.

Parameters

type	The BMI type name to resolve.
f	A callable templated on the type to use.

Returns

Whatever f returns.

Exceptions

unknown_bmi_type

If no C++ type corresponds to type.

Referenced by get_value_as_type(), get_values_as_type(), realization::Bmi_C_Formulation::get_var_value_as_double(), realization::Bmi_Cpp_Formulation::get_var_value_as_double(), GetValue(), and require_item_size().