NGen
Loading...
Searching...
No Matches
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...
 
struct  unsupported_primitive_type
 Thrown when a primitive_type has no C++ type on this platform. More...
 

Enumerations

enum class  primitive_type : std::uint8_t {
  i8 ,
  u8 ,
  i16 ,
  u16 ,
  i32 ,
  u32 ,
  i64 ,
  u64 ,
  f32 ,
  f64 ,
  long_double ,
  f128
}
 The type of one item of a BMI variable, independent of how any language spells it. More...
 

Functions

constexpr const char * to_string (primitive_type type)
 The enumerator's name, e.g.
 
constexpr size_t size_of (primitive_type type)
 The size in bytes of one item of type.
 
template<typename T >
constexpr primitive_type primitive_type_of ()
 The primitive_type of the C++ arithmetic type.
 
template<typename F >
auto with_primitive_type (primitive_type type, F &&f)
 Call f with the C++ type that type denotes.
 
primitive_type parse_bmi_type (std::string_view type)
 The primitive_type a BMI type name denotes.
 
primitive_type resolve_var_type (Bmi_Adapter &model, std::string_view name)
 Resolve the type to address a model's variable as, checked against its item size.
 
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 (primitive_type 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 (primitive_type 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.
 
template<typename T >
T GetValue (Bmi_Adapter &model, const std::string &name, int index)
 Read one item of a variable from a BMI model adapter, converted to.
 

Variables

constexpr bool long_double_is_float128 = std::numeric_limits<long double>::digits == 113
 Whether long double is IEEE binary128, the one format with a 113-bit significand.
 

Enumeration Type Documentation

◆ primitive_type

enum class models::bmi::primitive_type : std::uint8_t
strong

The type of one item of a BMI variable, independent of how any language spells it.

BMI reports a variable's type as a name in the model's language, and some names – Fortran's "real", Python's "int" – need the item size to settle which type they mean. The name is resolved to one of these once, and the framework passes this around thereafter rather than the name.

The fixed-width enumerators mean exactly that width and representation. Two do not:

  • long_double is the platform's C++ long double, whatever that is: IEEE binary128 on aarch64 Linux, x87 80-bit extended precision padded to 12 or 16 bytes on x86, or the same as double on others. It is what a model means by naming "long double".
  • f128 is IEEE binary128, whatever C++ type holds it. It is supported only where long double is binary128; see with_primitive_type() for the path elsewhere.
Enumerator
i8 
u8 
i16 
u16 
i32 
u32 
i64 
u64 
f32 
f64 
long_double 
f128 

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 ( primitive_type 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_primitive_type().

◆ get_values_as_type()

template<typename Iterator >
std::shared_ptr< void > models::bmi::get_values_as_type ( primitive_type 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_primitive_type().

◆ GetValue() [1/2]

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
TType to cast data from the BMI model to
ABmi model type
Parameters
modelBmi model adapter that interfaces to
Template Parameters
Abmi
Parameters
nameBmi 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_model_name(), bmi::Bmi::GetValue(), bmi::Bmi::GetVarItemsize(), bmi::Bmi::GetVarNbytes(), models::bmi::helper::make_vector(), resolve_var_type(), models::bmi::unknown_bmi_type::type_name, and with_primitive_type().

Referenced by models::bmi::protocols::NgenMassBalance::check_support(), realization::Bmi_Module_Formulation::get_value(), 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().

◆ GetValue() [2/2]

template<typename T >
T models::bmi::GetValue ( Bmi_Adapter & model,
const std::string & name,
int index )

Read one item of a variable from a BMI model adapter, converted to.

Template Parameters
T.

The single-item counterpart of the GetValue() above, for callers wanting one value of a variable that may hold many: the model is asked for that item alone, through its adapter's GetValueAtIndices(), rather than for a copy of the whole variable.

Template Parameters
TType to convert the item to
Parameters
modelBmi model adapter holding the variable
nameBmi variable name to query the model for
indexIndex of the item within the variable
Returns
T The item of variable name at index
Exceptions
std::out_of_rangeIf index is outside the variable.

References models::bmi::Bmi_Adapter::get_model_name(), bmi::Bmi::GetValueAtIndices(), bmi::Bmi::GetVarItemsize(), bmi::Bmi::GetVarNbytes(), resolve_var_type(), models::bmi::unknown_bmi_type::type_name, and with_primitive_type().

◆ 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
TThe type to address the variable's storage as.
Parameters
modelThe adapter holding the variable.
nameThe name of the variable.
Returns
A pointer to the model's own storage, which the model continues to own.
Exceptions
std::runtime_errorIf the model's items are not
Template Parameters
Twide, or it cannot give a pointer.

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

◆ parse_bmi_type()

primitive_type models::bmi::parse_bmi_type ( std::string_view type)
inline

The primitive_type a BMI type name denotes.

This is the one table of type spellings. Several may denote one type – "real" and "float", "integer" and "int" – and C spellings resolve to the width they have on this platform. A name whose width depends on more than the name, as Fortran's "real" under -fdefault-real-8 does, is for an adapter's Bmi_Adapter::get_primitive_type() to settle first.

Parameters
typeThe BMI type name.
Returns
The primitive_type it denotes.
Exceptions
unknown_bmi_typeIf type is not a name this knows.

References f32, f64, i16, i32, i64, i8, long_double, primitive_type_of(), u16, u32, u64, and u8.

Referenced by models::bmi::Bmi_Adapter::get_primitive_type().

◆ primitive_type_of()

template<typename T >
primitive_type models::bmi::primitive_type_of ( )
constexpr

The primitive_type of the C++ arithmetic type.

Template Parameters
T.

Integer types map by signedness and size, so that a C spelling such as "long" resolves to the width it has on this platform.

References f32, f64, i16, i32, i64, i8, long_double, u16, u32, u64, and u8.

Referenced by parse_bmi_type().

◆ resolve_var_type()

primitive_type models::bmi::resolve_var_type ( Bmi_Adapter & model,
std::string_view name )
inline

Resolve the type to address a model's variable as, checked against its item size.

The model's own type name is resolved by its adapter's get_primitive_type(), which may need the item size to settle it, and the result must then describe that item size exactly.

Parameters
modelThe adapter holding the variable.
nameThe name of the variable.
Returns
The variable's primitive_type, which is as wide as its items.
Exceptions
unknown_bmi_typeIf no C++ type corresponds to the resolved name.
std::runtime_errorIf that type is not as wide as the model says the items are.

References models::bmi::Bmi_Adapter::get_model_name(), models::bmi::Bmi_Adapter::get_primitive_type(), bmi::Bmi::GetVarItemsize(), bmi::Bmi::GetVarType(), and size_of().

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

◆ size_of()

size_t models::bmi::size_of ( primitive_type type)
constexpr

The size in bytes of one item of type.

References f128, f32, f64, i16, i32, i64, i8, long_double, u16, u32, u64, and u8.

Referenced by realization::Bmi_Var_Details::Bmi_Var_Details(), and resolve_var_type().

◆ to_string()

const char * models::bmi::to_string ( primitive_type type)
constexpr

The enumerator's name, e.g.

"i32", for messages.

References f128, f32, f64, i16, i32, i64, i8, long_double, u16, u32, u64, and u8.

Referenced by realization::Bmi_Var_Details::Bmi_Var_Details().

◆ with_primitive_type()

template<typename F >
auto models::bmi::with_primitive_type ( primitive_type type,
F && f )

Call f with the C++ type that type denotes.

Every operation on a variable has to pick the matching C++ type before it can do anything, and this is where that happens: f is a callable with a template parameter, invoked as f.template operator()<T>(), and this picks the T.

// "Give me this value as whatever the variable declares." The target type is only known at run
// time, so the cast cannot be written directly: capture the value, and let this supply the type.
std::shared_ptr<void> as_declared_type(primitive_type type, double value)
{
return with_primitive_type(type, [&]<typename T>() -> std::shared_ptr<void> {
return std::make_shared<T>(static_cast<T>(value));
});
}
auto with_primitive_type(primitive_type type, F &&f)
Call f with the C++ type that type denotes.
Definition bmi_primitive_type.hpp:172
primitive_type
The type of one item of a BMI variable, independent of how any language spells it.
Definition bmi_primitive_type.hpp:50

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 dispatch 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
typeThe primitive type to dispatch on.
fA callable templated on the type to use.
Returns
Whatever f returns.
Exceptions
unsupported_primitive_typeIf type has no C++ type on this platform.

References f128, f32, f64, i16, i32, i64, i8, long_double, long_double_is_float128, u16, u32, u64, and u8.

Referenced by get_value_as_type(), get_values_as_type(), GetValue(), and GetValue().

Variable Documentation

◆ long_double_is_float128

bool models::bmi::long_double_is_float128 = std::numeric_limits<long double>::digits == 113
inlineconstexpr

Whether long double is IEEE binary128, the one format with a 113-bit significand.

x87's 80-bit type has 64, and PowerPC's double-double 106.

Referenced by with_primitive_type().