models::bmi::Bmi_C_Adapter Class Reference

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

#include <Bmi_C_Adapter.hpp>

Inheritance diagram for models::bmi::Bmi_C_Adapter:

Collaboration diagram for models::bmi::Bmi_C_Adapter:

Public Member Functions
	Bmi_C_Adapter (const std::string &type_name, std::string library_file_path, bool has_fixed_time_step, const std::string &registration_func)
	Public constructor without path to BMI initialization config file.
	Bmi_C_Adapter (const std::string &type_name, std::string library_file_path, std::string bmi_init_config, bool has_fixed_time_step, std::string registration_func)
	Main public constructor.
	Bmi_C_Adapter (Bmi_C_Adapter &adapter)=delete
	Bmi_C_Adapter (Bmi_C_Adapter &&adapter) noexcept=delete
	~Bmi_C_Adapter () override
	Class destructor.
void	Finalize () override
	Perform tear-down task for this object and its backing model.
std::string	GetComponentName () override
double	GetCurrentTime () override
	Get the backing model's current time.
double	GetEndTime () override
int	GetInputItemCount () override
	The number of input variables the model can use.
std::vector< std::string >	GetInputVarNames () override
	Get input variable names for the backing model.
int	GetOutputItemCount () override
std::vector< std::string >	GetOutputVarNames () override
double	GetStartTime () override
	Get the backing model's starting time.
double	GetTimeStep () override
	Get the time step used in the model.
std::string	GetTimeUnits () override
	Get the units of time for the backing model.
void	GetValue (std::string name, void *dest) override
	Get value(s) for a variable.
void	GetValueAtIndices (std::string name, void *dest, int *inds, int count) override
void	GetGridShape (const int grid, int *shape) override
void	GetGridSpacing (const int grid, double *spacing) override
void	GetGridOrigin (const int grid, double *origin) override
void	GetGridX (const int grid, double *x) override
void	GetGridY (const int grid, double *y) override
void	GetGridZ (const int grid, double *z) override
int	GetGridNodeCount (const int grid) override
int	GetGridEdgeCount (const int grid) override
int	GetGridFaceCount (const int grid) override
void	GetGridEdgeNodes (const int grid, int *edge_nodes) override
void	GetGridFaceEdges (const int grid, int *face_edges) override
void	GetGridFaceNodes (const int grid, int *face_nodes) override
void	GetGridNodesPerFace (const int grid, int *nodes_per_face) override
void *	GetValuePtr (std::string name) override
template<class T >
T *	GetValuePtr (const std::string &name)
	Get a reference to the value(s) of a given variable.
int	GetVarItemsize (std::string name) override
	Get the size (in bytes) of one item of a variable.
int	GetVarNbytes (std::string name) override
	Get the total size (in bytes) of a variable.
int	GetVarGrid (std::string name) override
	Get the data type of a variable.
std::string	GetVarType (std::string name) override
	Get the grid (id) of a variable.
std::string	GetVarUnits (std::string name) override
	Get the units for a variable.
std::string	GetVarLocation (std::string name) override
	Get location for a variable.
std::string	GetGridType (int grid_id) override
	Get grid type for a grid-id.
int	GetGridRank (int grid_id) override
	Get grid rank for a grid-id.
int	GetGridSize (int grid_id) override
	Get grid size for a grid-id.
const std::string	get_analogous_cxx_type (const std::string &external_type_name, const size_t item_size) override
	Get the name string for the C++ type analogous to the described type in the backing model.
bool	is_model_initialized () override
	Whether the backing model has been initialized yet.
void	SetValue (std::string name, void *src) override
template<class T >
void	SetValue (std::string name, std::vector< T > src)
void	SetValueAtIndices (std::string name, int *inds, int count, void *src) override
template<class T >
void	SetValueAtIndices (const std::string &name, std::vector< int > inds, std::vector< T > src)
void	Update () override
	Have the backing model update to next time step.
void	UpdateUntil (double time) override
	Have the backing BMI model update to the specified time.
double	get_time_convert_factor ()
	Determine backing model's time units and return an appropriate conversion factor.
double	convert_model_time_to_seconds (const double &model_time_val)
	Convert model time value to value in seconds.
double	convert_seconds_to_model_time (const double &seconds_val)
	Convert a given number of seconds to equivalent in model time units.
void	Initialize ()
	Initialize the wrapped BMI model functionality using the value from the bmi_init_config member variable and the API's Initialize function.
void	Initialize (std::string config_file) override
	Initialize the wrapped BMI model object using the given config file and the object's Initialize function.
bool	isInitialized ()
	Get whether this instance has been initialized properly.
std::string	get_model_name ()
	Get the model name.

Protected Member Functions
	Bmi_C_Adapter (const std::string &type_name, std::string library_file_path, std::string bmi_init_config, bool has_fixed_time_step, std::string registration_func, bool do_initialization)
	Protected constructor that allows control over whether initialization steps are done during construction.
void	construct_and_init_backing_model () override
	Construct the backing BMI model object, then call its BMI-native Initialize() function.
void	execModuleRegistration ()
	Load and execute the "registration" function for the backing BMI module.
std::shared_ptr< double >	get_bmi_model_time_step_size_ptr ()
	Get model time step size pointer, using lazy loading when fixed.
void	get_value (const std::string &name, void *dest)
	Internal implementation of logic used for.
std::shared_ptr< double >	retrieve_bmi_model_time_step_size ()
	Retrieve time step size directly from model.
void	dynamic_library_load ()
	Dynamically load and obtain this instance's handle to the shared library.
void *	dynamic_load_symbol (const std::string &symbol_name, bool is_null_valid)
	Load and return the address of the given symbol from the loaded dynamic model shared library.
void *	dynamic_load_symbol (const std::string &symbol_name)
	Convenience for.
const std::string &	get_bmi_registration_function ()
const void *	get_dyn_lib_handle ()

Protected Attributes
std::string	model_name = "BMI C model"
std::string	bmi_init_config
	Path (as a string) to the BMI config file for initializing the backing model (empty if none).
bool	bmi_model_has_fixed_time_step = true
	Whether this particular model has a time step size that cannot be changed internally or externally.
double	bmi_model_time_convert_factor
	Conversion factor for converting values for model time in model's unit type to equivalent in seconds.
std::shared_ptr< double >	bmi_model_time_step_size = nullptr
	Pointer to stored time step size value of backing model, if it is fixed and has been retrieved.
std::string	init_exception_msg
	Message from an exception (if encountered) on the first attempt to initialize the backing model.
std::shared_ptr< std::vector< std::string > >	input_var_names
	Pointer to collection of input variable names for backing model, used by GetInputVarNames().
bool	model_initialized = false
	Whether the backing model has been initialized yet, which is always initially false.
std::shared_ptr< std::vector< std::string > >	output_var_names
	Pointer to collection of output variable names for backing model, used by GetOutputVarNames().

Private Member Functions
void	construct_and_init_backing_model_for_type ()
	Construct the backing BMI model object, then call its BMI-native Initialize() function.
void	finalizeForCAdapter ()
	A non-virtual equivalent for the virtual.
int	inner_get_input_item_count ()
	Internal implementation of logic used for.
int	inner_get_output_item_count ()
	Internal implementation of logic used for.
std::shared_ptr< std::vector< std::string > >	inner_get_variable_names (bool is_input_variables)
	Helper method for getting either input or output variable names.
void	finalizeForLibAbstraction ()
	A non-virtual equivalent for the virtual.

Private Attributes
std::unique_ptr< C_Bmi >	bmi_model = nullptr
	Pointer to backing BMI model instance.
std::string	bmi_lib_file
	Path to the BMI shared library file, for dynamic linking.
const std::string	bmi_registration_function
	Name of the function that registers BMI struct's function pointers to the right module functions.
void *	dyn_lib_handle = nullptr
	Handle for dynamically loaded library file.

Friends
class	::Bmi_C_Adapter_Test

Detailed Description

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.

Constructor & Destructor Documentation

Bmi_C_Adapter() [1/5]

Bmi_C_Adapter::Bmi_C_Adapter ( const std::string & type_name, std::string library_file_path, bool has_fixed_time_step, const std::string & registration_func )

explicit

Public constructor without path to BMI initialization config file.

Parameters

type_name	The name of the backing BMI module/model type.
library_file_path	The string path to the shared library file for external module.
has_fixed_time_step	Whether the model has a fixed time step size.
registration_func	The name for the

See also

bmi_registration_function.

Bmi_C_Adapter() [2/5]

Bmi_C_Adapter::Bmi_C_Adapter	(	const std::string &	type_name,
		std::string	library_file_path,
		std::string	bmi_init_config,
		bool	has_fixed_time_step,
		std::string	registration_func )

Main public constructor.

Parameters

type_name	The name of the backing BMI module/model type.
library_file_path	The string path to the shared library file for external module.
bmi_init_config	The string path to the BMI initialization config file for the module.
has_fixed_time_step	Whether the model has a fixed time step size.
registration_func	The name for the

See also

bmi_registration_function.

Bmi_C_Adapter() [3/5]

Bmi_C_Adapter::Bmi_C_Adapter ( const std::string & type_name, std::string library_file_path, std::string bmi_init_config, bool has_fixed_time_step, std::string registration_func, bool do_initialization )

protected

Protected constructor that allows control over whether initialization steps are done during construction.

Constructor that has parameter to control whether initialization steps - i.e., steps that would be performed in the BMI

See also

Initialize(std::string) function if not already done - are done when constructing the object.

In general, it is assumed that an object of this type will be initialized on construction. However, a subtype may wish to utilize the constructor while deferring initialization (usually so it can perform that internally as a later step).

Parameters

type_name	The name of the backing BMI module/model type.
library_file_path	The string path to the shared library file for external module.
bmi_init_config	The string path to the BMI initialization config file for the module.
has_fixed_time_step	Whether the model has a fixed time step size.
registration_func	The name for the

See also

bmi_registration_function.

Parameters

do_initialization

Whether initialization should be performed during construction or deferred.

References models::bmi::Bmi_Adapter::bmi_model_time_convert_factor, construct_and_init_backing_model_for_type(), models::bmi::Bmi_Adapter::get_time_convert_factor(), and models::bmi::Bmi_Adapter::model_initialized.

Bmi_C_Adapter() [4/5]

models::bmi::Bmi_C_Adapter::Bmi_C_Adapter ( Bmi_C_Adapter & adapter )

delete

Bmi_C_Adapter() [5/5]

models::bmi::Bmi_C_Adapter::Bmi_C_Adapter ( Bmi_C_Adapter && adapter )

deletenoexcept

~Bmi_C_Adapter()

models::bmi::Bmi_C_Adapter::~Bmi_C_Adapter ( )

inlineoverride

Class destructor.

Note that this calls the Finalize() function for cleaning up this object and its backing BMI model.

References finalizeForCAdapter().

Member Function Documentation

construct_and_init_backing_model()

void models::bmi::Bmi_C_Adapter::construct_and_init_backing_model ( )

inlineoverrideprotectedvirtual

Construct the backing BMI model object, then call its BMI-native Initialize() function.

Implementations should return immediately without taking any further action if model_initialized is already true.

The call to the BMI native Initialize(string) should pass the value stored in bmi_init_config.

See also

construct_and_init_backing_model_for_type

Implements models::bmi::Bmi_Adapter.

References construct_and_init_backing_model_for_type().

construct_and_init_backing_model_for_type()

void models::bmi::Bmi_C_Adapter::construct_and_init_backing_model_for_type ( )

inlineprivate

Construct the backing BMI model object, then call its BMI-native Initialize() function.

The essentially provides the functionality for

See also

construct_and_init_backing_model without being a virtual function.

Implementations should return immediately without taking any further action if model_initialized is already true.

The call to the BMI native Initialize(string) should pass the value stored in bmi_init_config.

References models::bmi::Bmi_Adapter::bmi_init_config, bmi_model, execModuleRegistration(), models::bmi::Bmi_Adapter::init_exception_msg, models::bmi::Bmi_Adapter::model_initialized, and model_name.

Referenced by Bmi_C_Adapter(), and construct_and_init_backing_model().

convert_model_time_to_seconds()

double models::bmi::Bmi_Adapter::convert_model_time_to_seconds ( const double & model_time_val )

inherited

Convert model time value to value in seconds.

Performs necessary lookup and conversion of some given model time value - as from GetCurrentTime() or GetStartTime() - and returns the equivalent value when represented in seconds.

Parameters

model_time_val

Arbitrary model time value in units provided by GetTimeUnits()

Returns

Equivalent model time value to value in seconds.

References models::bmi::Bmi_Adapter::bmi_model_time_convert_factor.

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

convert_seconds_to_model_time()

double models::bmi::Bmi_Adapter::convert_seconds_to_model_time ( const double & seconds_val )

inherited

Convert a given number of seconds to equivalent in model time units.

Parameters

seconds_val

Returns

References models::bmi::Bmi_Adapter::bmi_model_time_convert_factor.

Referenced by realization::Bmi_Module_Formulation::get_response().

dynamic_library_load()

void models::bmi::AbstractCLibBmiAdapter::dynamic_library_load ( )

protectedinherited

Dynamically load and obtain this instance's handle to the shared library.

References models::bmi::AbstractCLibBmiAdapter::bmi_lib_file, models::bmi::AbstractCLibBmiAdapter::bmi_registration_function, models::bmi::AbstractCLibBmiAdapter::dyn_lib_handle, utils::FileChecker::file_is_readable(), models::bmi::Bmi_Adapter::init_exception_msg, models::bmi::Bmi_Adapter::model_name, and logging::warning().

Referenced by models::bmi::Bmi_Cpp_Adapter::execModuleCreation(), and execModuleRegistration().

dynamic_load_symbol() [1/2]

void * models::bmi::AbstractCLibBmiAdapter::dynamic_load_symbol ( const std::string & symbol_name )

inlineprotectedinherited

Convenience for.

See also

dynamic_load_symbol(std::string, bool) where the symbol address must be found.

This serves as a convenience overload for the function of the same name, in cases when a sought symbol must be found and the return of a null address is not valid.

Parameters

symbol_name

The name of the symbol to load.

Returns

A void pointer to the address of the desired symbol in memory.

Exceptions

``std::runtime_error``	If there is not a valid handle already to the shared library.
``::external::ExternalIntegrationException``	If symbol could not be found for the shared library.

See also

dynamic_load_symbol(std::string, bool)

References models::bmi::AbstractCLibBmiAdapter::dynamic_load_symbol().

dynamic_load_symbol() [2/2]

void * models::bmi::AbstractCLibBmiAdapter::dynamic_load_symbol ( const std::string & symbol_name, bool is_null_valid )

protectedinherited

Load and return the address of the given symbol from the loaded dynamic model shared library.

The initial primary purpose for this is to obtain a function pointer for accessing the registration function for a dynamically loaded library, as done in

See also

dynamic_library_load. Other function pointers (or pointers to other valid symbols) can also be returned.

It is possible for a symbol pointer to actually be null in some cases. However, this may not be valid in the context in which a call to this function was made. To control whether this is treated as a valid case, and thus whether null should be returned (instead of an exception thrown), there is the is_null_valid parameter. When true, a null symbol will be returned by the function.

Typically, a call to

See also

dynamic_library_load must happen (though not necessarily have completed) before a call to this function to ensure

dyn_lib_handle is set. If it is not set, an exception is thrown.

Parameters

symbol_name	The name of the symbol to load.
is_null_valid	Whether a null address for the symbol is valid, as opposed to implying there was simply a failure finding it.

Returns

A void pointer to the address of the desired symbol in memory.

Exceptions

``std::runtime_error``	If there is not a valid handle already to the shared library.
``::external::ExternalIntegrationException``	If symbol could not be found for the shared library.

References models::bmi::AbstractCLibBmiAdapter::bmi_lib_file, models::bmi::AbstractCLibBmiAdapter::dyn_lib_handle, models::bmi::Bmi_Adapter::init_exception_msg, and models::bmi::Bmi_Adapter::model_name.

Referenced by models::bmi::AbstractCLibBmiAdapter::dynamic_load_symbol(), models::bmi::Bmi_Cpp_Adapter::execModuleCreation(), execModuleRegistration(), and models::bmi::Bmi_Cpp_Adapter::finalizeForCppAdapter().

execModuleRegistration()

void models::bmi::Bmi_C_Adapter::execModuleRegistration ( )

inlineprotected

Load and execute the "registration" function for the backing BMI module.

Integrated BMI module libraries are expected to provide an additional register_bmi function. This essentially works like a constructor (or factory) for the model struct. It accepts a pointer to a BMI C struct and then sets the appropriate function pointer member values of the struct.

References bmi_model, models::bmi::AbstractCLibBmiAdapter::dynamic_library_load(), models::bmi::AbstractCLibBmiAdapter::dynamic_load_symbol(), models::bmi::AbstractCLibBmiAdapter::get_bmi_registration_function(), models::bmi::AbstractCLibBmiAdapter::get_dyn_lib_handle(), and models::bmi::Bmi_Adapter::init_exception_msg.

Referenced by construct_and_init_backing_model_for_type().

Finalize()

void models::bmi::Bmi_C_Adapter::Finalize ( )

inlineoverridevirtual

Perform tear-down task for this object and its backing model.

The function will simply return if either the pointer to the backing model is nullptr (e.g., after use in a move constructor) or if the model has not been initialized. Otherwise, it will execute its internal tear-down logic, including a nested call to finalize() for the backing model.

Note that because of how model initialization state is determined, regardless of whether the call to the model's finalize() function is successful (i.e., according to the function's return code value), the model will subsequently be consider not initialized. This essentially means that if backing model tear-down fails, it cannot be retried.

Exceptions

models::external::State_Exception

Thrown if nested model finalize() call is not successful.

Reimplemented from models::bmi::AbstractCLibBmiAdapter.

References finalizeForCAdapter().

finalizeForCAdapter()

void models::bmi::Bmi_C_Adapter::finalizeForCAdapter ( )

inlineprivate

A non-virtual equivalent for the virtual.

See also

Finalize.

This function should be kept private. If its logic needs to be invoked externally, that should be done via the destructor or via the public interface

See also

Finalize function.

Primarily, this exists to contain the functionality appropriate for

See also

Finalize in a function that is non-virtual, and can therefore be called by a destructor.

References bmi_model, models::bmi::Bmi_Adapter::model_initialized, and model_name.

Referenced by ~Bmi_C_Adapter(), and Finalize().

finalizeForLibAbstraction()

void models::bmi::AbstractCLibBmiAdapter::finalizeForLibAbstraction ( )

privateinherited

A non-virtual equivalent for the virtual.

See also

Finalize.

This function should be kept private. If its logic needs to be invoked externally, that should be done via the destructor or via the public interface

See also

Finalize function.

Primarily, this exists to contain the functionality appropriate for

See also

Finalize in a function that is non-virtual, and can therefore be called by a destructor.

References models::bmi::AbstractCLibBmiAdapter::dyn_lib_handle.

Referenced by models::bmi::AbstractCLibBmiAdapter::~AbstractCLibBmiAdapter(), and models::bmi::AbstractCLibBmiAdapter::Finalize().

get_analogous_cxx_type()

const std::string models::bmi::Bmi_C_Adapter::get_analogous_cxx_type ( const std::string & external_type_name, const size_t item_size )

inlineoverridevirtual

Get the name string for the C++ type analogous to the described type in the backing model.

The supported languages for BMI modules support different types than C++ in general, so it is necessary to map "external" types to the appropriate C++ type for certain interactions; e.g., setting a variable value.

However, for C language models, the types in C can be used directly, so this simply returns the original string for the external name.

Note that the size of an individual item is also required, as this can vary in certain situations depending on the implementation language of a backing model.

Parameters

external_type_name	The string name of some C type.
item_size	The particular size in bytes for items of the involved analogous types.

Returns

The name string for the analogous C++ type, which is the same as given arg for C modules.

Implements models::bmi::Bmi_Adapter.

get_bmi_model_time_step_size_ptr()

std::shared_ptr< double > models::bmi::Bmi_C_Adapter::get_bmi_model_time_step_size_ptr ( )

inlineprotected

Get model time step size pointer, using lazy loading when fixed.

Get a pointer to the value of the backing model's time step size. If the model is configured to have fixed time step size, return the pointer from bmi_model_time_step_size, potentially after it is lazily loaded. If the model's time step is not fixed, retrieve it directly from the model in real time, and do not set bmi_model_time_step_size.

Returns

A pointer to the value of the backing model's time step size.

See also

retrieve_bmi_model_time_step_size

References models::bmi::Bmi_Adapter::bmi_model_has_fixed_time_step, models::bmi::Bmi_Adapter::bmi_model_time_step_size, and retrieve_bmi_model_time_step_size().

Referenced by GetTimeStep().

get_bmi_registration_function()

const std::string & models::bmi::AbstractCLibBmiAdapter::get_bmi_registration_function ( )

inlineprotectedinherited

References models::bmi::AbstractCLibBmiAdapter::bmi_registration_function.

Referenced by execModuleRegistration().

get_dyn_lib_handle()

const void * models::bmi::AbstractCLibBmiAdapter::get_dyn_lib_handle ( )

inlineprotectedinherited

References models::bmi::AbstractCLibBmiAdapter::dyn_lib_handle.

Referenced by models::bmi::Bmi_Cpp_Adapter::execModuleCreation(), and execModuleRegistration().

get_model_name()

std::string models::bmi::Bmi_Adapter::get_model_name ( )

inherited

Get the model name.

Returns

The name of the model connected to the adapter.

References models::bmi::Bmi_Adapter::model_name.

Referenced by models::bmi::GetValue().

get_time_convert_factor()

double models::bmi::Bmi_Adapter::get_time_convert_factor ( )

inherited

Determine backing model's time units and return an appropriate conversion factor.

A backing BMI model may use arbitrary units for time, but it will expose what those units are via the BMI GetTimeUnits function. This function retrieves (and interprets) its model's units and return an appropriate factor for converting its internal time values to equivalent representations within the model, and vice versa. This function complies with the BMI get_time_units standard

Exceptions

runtime_error

If the delegated BMI functions to query time throw an exception, the exception is caught and wrapped in a runtime_error

References UnitsHelper::get_converted_value(), and bmi::Bmi::GetTimeUnits().

Referenced by Bmi_C_Adapter(), models::bmi::Bmi_Cpp_Adapter::Bmi_Cpp_Adapter(), and models::bmi::Bmi_Adapter::Initialize().

get_value()

void models::bmi::Bmi_C_Adapter::get_value ( const std::string & name, void * dest )

inlineprotected

Internal implementation of logic used for.

See also

GetValue.

Essentially, function exists as inner implementation. This allows it to be inlined, which may lead to optimization in certain situations.

Parameters

name	The name of the variable for which to get values.
dest	An array pointer into which the values will be written.

References bmi_model, and model_name.

Referenced by GetValue().

GetComponentName()

std::string Bmi_C_Adapter::GetComponentName ( )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetCurrentTime()

double Bmi_C_Adapter::GetCurrentTime ( )

overridevirtual

Get the backing model's current time.

Get the backing model's current time, relative to the start time, in the units expressed by GetTimeUnits().

Returns

The backing model's current time.

Implements bmi::Bmi.

References bmi_model, and model_name.

GetEndTime()

double Bmi_C_Adapter::GetEndTime ( )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridEdgeCount()

int Bmi_C_Adapter::GetGridEdgeCount ( const int grid )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridEdgeNodes()

void Bmi_C_Adapter::GetGridEdgeNodes ( const int grid, int * edge_nodes )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridFaceCount()

int Bmi_C_Adapter::GetGridFaceCount ( const int grid )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridFaceEdges()

void Bmi_C_Adapter::GetGridFaceEdges ( const int grid, int * face_edges )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridFaceNodes()

void Bmi_C_Adapter::GetGridFaceNodes ( const int grid, int * face_nodes )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridNodeCount()

int Bmi_C_Adapter::GetGridNodeCount ( const int grid )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridNodesPerFace()

void Bmi_C_Adapter::GetGridNodesPerFace ( const int grid, int * nodes_per_face )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridOrigin()

void Bmi_C_Adapter::GetGridOrigin ( const int grid, double * origin )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridRank()

int Bmi_C_Adapter::GetGridRank ( int grid_id )

overridevirtual

Get grid rank for a grid-id.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridShape()

void Bmi_C_Adapter::GetGridShape ( const int grid, int * shape )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridSize()

int Bmi_C_Adapter::GetGridSize ( int grid_id )

overridevirtual

Get grid size for a grid-id.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridSpacing()

void Bmi_C_Adapter::GetGridSpacing ( const int grid, double * spacing )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridType()

std::string Bmi_C_Adapter::GetGridType ( int grid_id )

overridevirtual

Get grid type for a grid-id.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridX()

void Bmi_C_Adapter::GetGridX ( const int grid, double * x )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridY()

void Bmi_C_Adapter::GetGridY ( const int grid, double * y )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetGridZ()

void Bmi_C_Adapter::GetGridZ ( const int grid, double * z )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetInputItemCount()

int Bmi_C_Adapter::GetInputItemCount ( )

overridevirtual

The number of input variables the model can use.

The number of input variables the model can use from other models implementing a BMI.

Returns

The number of input variables the model can use from other models implementing a BMI.

Implements bmi::Bmi.

References GetInputVarNames().

GetInputVarNames()

std::vector< std::string > Bmi_C_Adapter::GetInputVarNames ( )

overridevirtual

Get input variable names for the backing model.

Gets a collection of names for the variables the model can use from other models implementing a BMI.

Returns

A vector of names for the variables the model can use from other models implementing a BMI.

Implements bmi::Bmi.

References inner_get_variable_names(), and models::bmi::Bmi_Adapter::input_var_names.

Referenced by GetInputItemCount().

GetOutputItemCount()

int Bmi_C_Adapter::GetOutputItemCount ( )

overridevirtual

Implements bmi::Bmi.

References GetOutputVarNames().

GetOutputVarNames()

std::vector< std::string > Bmi_C_Adapter::GetOutputVarNames ( )

overridevirtual

Implements bmi::Bmi.

References inner_get_variable_names(), and models::bmi::Bmi_Adapter::output_var_names.

Referenced by GetOutputItemCount().

GetStartTime()

double Bmi_C_Adapter::GetStartTime ( )

overridevirtual

Get the backing model's starting time.

Get the backing model's starting time, in the units expressed by GetTimeUnits().

The BMI standard start time is typically defined to be 0.0.

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

GetTimeStep()

double models::bmi::Bmi_C_Adapter::GetTimeStep ( )

inlineoverridevirtual

Get the time step used in the model.

Get the time step size used in the backing model, expressed as a double type value.

This function defers to the behavior of the analogous function get_time_step of the backing model. As such, the the model-specific documentation for this function should be consulted for utilized models.

Returns

The time step size of the model.

Implements bmi::Bmi.

References get_bmi_model_time_step_size_ptr().

GetTimeUnits()

std::string Bmi_C_Adapter::GetTimeUnits ( )

overridevirtual

Get the units of time for the backing model.

Get the units of time for the backing model, as a standard convention string representing the unit obtained directly from the model.

Returns

A conventional string representing the time units for the model.

Implements bmi::Bmi.

References bmi_model, and model_name.

GetValue()

void models::bmi::Bmi_C_Adapter::GetValue ( std::string name, void * dest )

inlineoverridevirtual

Get value(s) for a variable.

Implementation of virtual function in BMI interface.

Parameters

name
dest

See also

get_value

Implements bmi::Bmi.

References get_value().

GetValueAtIndices()

void Bmi_C_Adapter::GetValueAtIndices ( std::string name, void * dest, int * inds, int count )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

GetValuePtr() [1/2]

template<class T >

T * models::bmi::Bmi_C_Adapter::GetValuePtr ( const std::string & name )

inline

Get a reference to the value(s) of a given variable.

This function gets and returns the reference (i.e., pointer) to the backing model's variable with the given name. Unlike what is returned by GetValue(), this will point to the current value(s) of the variable, even if the model's state has changed.

Because of how C-based BMI models are implemented, raw pointers are returned. The pointers are "owned" by the model implementation, though, so there should be no risk of memory leaks (i.e., strictly as a result of obtaining a reference via this function.)

Template Parameters

T	The type of the variable to which a reference will be returned.

Parameters

name	The name of the variable to which a reference will be returned.

Returns

A reference to the value(s) of a given variable

References bmi_model, GetValuePtr(), and model_name.

GetValuePtr() [2/2]

void * models::bmi::Bmi_C_Adapter::GetValuePtr ( std::string name )

inlineoverridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

Referenced by GetValuePtr().

GetVarGrid()

int Bmi_C_Adapter::GetVarGrid ( std::string name )

overridevirtual

Get the data type of a variable.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

GetVarItemsize()

int Bmi_C_Adapter::GetVarItemsize ( std::string name )

overridevirtual

Get the size (in bytes) of one item of a variable.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

Referenced by SetValue(), and SetValueAtIndices().

GetVarLocation()

std::string Bmi_C_Adapter::GetVarLocation ( std::string name )

overridevirtual

Get location for a variable.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

GetVarNbytes()

int Bmi_C_Adapter::GetVarNbytes ( std::string name )

overridevirtual

Get the total size (in bytes) of a variable.

This function provides the total amount of memory used to store a variable; i.e., the number of items multiplied by the size of each item.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

GetVarType()

std::string Bmi_C_Adapter::GetVarType ( std::string name )

overridevirtual

Get the grid (id) of a variable.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

GetVarUnits()

std::string Bmi_C_Adapter::GetVarUnits ( std::string name )

overridevirtual

Get the units for a variable.

Parameters

name

Returns

Implements bmi::Bmi.

References bmi_model, and model_name.

Initialize() [1/2]

void models::bmi::Bmi_Adapter::Initialize ( )

inherited

Initialize the wrapped BMI model functionality using the value from the bmi_init_config member variable and the API's Initialize function.

If no attempt to initialize the model has yet been made (i.e., model_initialized is false when this function is called), then an initialization is attempted for the model. This is handled by a nested call to the construct_and_init_backing_model function. If initialization fails, an exception will be raised, with it's message saved as part of this object's state. However, regardless of the success of initialization, model_initialized is set to true after the attempt.

Additionally, if a successful model initialization is performed, bmi_model_time_convert_factor is immediately thereafter set by passing it by reference in a call to acquire_time_conversion_factor.

If an attempt to initialize the model has already been made (i.e., model_initialized is true), this function will either simply return or will throw a runtime_error, with its message including the message of the exception from the earlier attempt.

Exceptions

runtime_error	If called again after earlier call that resulted in an exception, or if BMI config file could not be read.
models::external::State_Exception	If initialize() in nested model does not return successful.

References models::bmi::Bmi_Adapter::bmi_init_config, models::bmi::Bmi_Adapter::bmi_model_time_convert_factor, models::bmi::Bmi_Adapter::construct_and_init_backing_model(), utils::FileChecker::file_is_readable(), models::bmi::Bmi_Adapter::get_time_convert_factor(), models::bmi::Bmi_Adapter::init_exception_msg, models::bmi::Bmi_Adapter::model_initialized, and models::bmi::Bmi_Adapter::model_name.

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

Initialize() [2/2]

void models::bmi::Bmi_Adapter::Initialize ( std::string config_file )

overridevirtualinherited

Initialize the wrapped BMI model object using the given config file and the object's Initialize function.

If the given file is not the same as what is in bmi_init_configand the model object has not already been initialized, this function will produce a warning message about the difference, then subsequently updatebmi_init_config`` to the given file. It will then proceed with initialization.

However, if the given file is not the same as what is in bmi_init_config`, but the model has already been initialized, a runtime_error exception is thrown.

This otherwise operates using the logic of Initialize().

Parameters

config_file

See also

Initialize()

Exceptions

models::external::State_Exception	If initialize() in nested model is not successful.
runtime_error	If already initialized but using a different file than the passed argument.

Implements bmi::Bmi.

References models::bmi::Bmi_Adapter::bmi_init_config, models::bmi::Bmi_Adapter::Initialize(), models::bmi::Bmi_Adapter::model_initialized, logging::warning(), and models::external::State_Exception::what().

inner_get_input_item_count()

int models::bmi::Bmi_C_Adapter::inner_get_input_item_count ( )

inlineprivate

Internal implementation of logic used for.

See also

GetInputItemCount.

"Inner" functions such as this should not contain nested function calls to any other member functions for the type.

Returns

The count of input BMI variables.

See also

GetInputItemCount

References bmi_model, and model_name.

Referenced by inner_get_variable_names().

inner_get_output_item_count()

int models::bmi::Bmi_C_Adapter::inner_get_output_item_count ( )

inlineprivate

Internal implementation of logic used for.

See also

GetOutputItemCount.

"Inner" functions such as this should not contain nested function calls to any other member functions for the type.

Returns

The count of output BMI variables.

See also

GetOutputItemCount

References bmi_model, and model_name.

Referenced by inner_get_variable_names().

inner_get_variable_names()

std::shared_ptr< std::vector< std::string > > Bmi_C_Adapter::inner_get_variable_names ( bool is_input_variables )

private

Helper method for getting either input or output variable names.

"Inner" functions such as this should not contain nested function calls to any other member functions for the type.

This should be used for

See also

GetInputVarNames and

GetOutputVarNames.

Parameters

is_input_variable

Whether input variable names should be retrieved (as opposed to output).

Returns

A shared pointer to a vector of input or output variable name strings.

See also

GetInputVarNames

GetOutputVarNames

References bmi_model, inner_get_input_item_count(), inner_get_output_item_count(), and model_name.

Referenced by GetInputVarNames(), and GetOutputVarNames().

is_model_initialized()

bool Bmi_C_Adapter::is_model_initialized ( )

overridevirtual

Whether the backing model has been initialized yet.

Returns

Whether the backing model has been initialized yet.

Implements models::bmi::Bmi_Adapter.

References models::bmi::Bmi_Adapter::model_initialized.

isInitialized()

bool models::bmi::Bmi_Adapter::isInitialized ( )

inherited

Get whether this instance has been initialized properly.

Returns

Whether this instance has been initialized properly.

References models::bmi::Bmi_Adapter::model_initialized.

retrieve_bmi_model_time_step_size()

std::shared_ptr< double > models::bmi::Bmi_C_Adapter::retrieve_bmi_model_time_step_size ( )

inlineprotected

Retrieve time step size directly from model.

Retrieve the time step size from the backing model and return in a shared pointer.

Returns

Shared pointer to just-retrieved time step size

References bmi_model, and model_name.

Referenced by get_bmi_model_time_step_size_ptr().

SetValue() [1/2]

template<class T >

void models::bmi::Bmi_C_Adapter::SetValue ( std::string name, std::vector< T > src )

inline

References GetVarItemsize(), model_name, and SetValue().

SetValue() [2/2]

void Bmi_C_Adapter::SetValue ( std::string name, void * src )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

Referenced by SetValue().

SetValueAtIndices() [1/2]

template<class T >

void models::bmi::Bmi_C_Adapter::SetValueAtIndices ( const std::string & name, std::vector< int > inds, std::vector< T > src )

inline

Template Parameters

T

Parameters

name
inds	Collection of indexes within the model for which this variable should have a value set.
src	Values that should be set for this variable at the corresponding index in inds.

References GetVarItemsize(), model_name, and SetValueAtIndices().

SetValueAtIndices() [2/2]

void Bmi_C_Adapter::SetValueAtIndices ( std::string name, int * inds, int count, void * src )

overridevirtual

Implements bmi::Bmi.

References bmi_model, and model_name.

Referenced by SetValueAtIndices().

Update()

void Bmi_C_Adapter::Update ( )

overridevirtual

Have the backing model update to next time step.

Have the backing BMI model perform an update to the next time step according to its own internal time keeping.

Implements bmi::Bmi.

References bmi_model, and model_name.

UpdateUntil()

void Bmi_C_Adapter::UpdateUntil ( double time )

overridevirtual

Have the backing BMI model update to the specified time.

Update the backing BMI model to some desired model time, specified either explicitly or implicitly as a non-integral multiple of time steps. Note that the former is supported, but not required, by the BMI specification. The same is true for negative argument values.

This function does not attempt to determine whether the particular backing model will consider the provided parameter valid.

Parameters

time	Time to update model to, either as literal model time or non-integral multiple of time steps.

Implements bmi::Bmi.

References bmi_model, and model_name.

Friends And Related Symbol Documentation

::Bmi_C_Adapter_Test

friend class ::Bmi_C_Adapter_Test

friend

Member Data Documentation

bmi_init_config

std::string models::bmi::Bmi_Adapter::bmi_init_config

protectedinherited

Path (as a string) to the BMI config file for initializing the backing model (empty if none).

Referenced by construct_and_init_backing_model_for_type(), models::bmi::Bmi_Cpp_Adapter::construct_and_init_backing_model_for_type(), models::bmi::Bmi_Adapter::Initialize(), and models::bmi::Bmi_Adapter::Initialize().

bmi_lib_file

std::string models::bmi::AbstractCLibBmiAdapter::bmi_lib_file

privateinherited

Path to the BMI shared library file, for dynamic linking.

Referenced by models::bmi::AbstractCLibBmiAdapter::dynamic_library_load(), and models::bmi::AbstractCLibBmiAdapter::dynamic_load_symbol().

bmi_model

std::unique_ptr<C_Bmi> models::bmi::Bmi_C_Adapter::bmi_model = nullptr

private

Pointer to backing BMI model instance.

Referenced by construct_and_init_backing_model_for_type(), execModuleRegistration(), finalizeForCAdapter(), get_value(), GetComponentName(), GetCurrentTime(), GetEndTime(), GetGridEdgeCount(), GetGridEdgeNodes(), GetGridFaceCount(), GetGridFaceEdges(), GetGridFaceNodes(), GetGridNodeCount(), GetGridNodesPerFace(), GetGridOrigin(), GetGridRank(), GetGridShape(), GetGridSize(), GetGridSpacing(), GetGridType(), GetGridX(), GetGridY(), GetGridZ(), GetStartTime(), GetTimeUnits(), GetValueAtIndices(), GetValuePtr(), GetValuePtr(), GetVarGrid(), GetVarItemsize(), GetVarLocation(), GetVarNbytes(), GetVarType(), GetVarUnits(), inner_get_input_item_count(), inner_get_output_item_count(), inner_get_variable_names(), retrieve_bmi_model_time_step_size(), SetValue(), SetValueAtIndices(), Update(), and UpdateUntil().

bmi_model_has_fixed_time_step

bool models::bmi::Bmi_Adapter::bmi_model_has_fixed_time_step = true

protectedinherited

Whether this particular model has a time step size that cannot be changed internally or externally.

Referenced by get_bmi_model_time_step_size_ptr(), and models::bmi::Bmi_Cpp_Adapter::get_bmi_model_time_step_size_ptr().

bmi_model_time_convert_factor

double models::bmi::Bmi_Adapter::bmi_model_time_convert_factor

protectedinherited

Conversion factor for converting values for model time in model's unit type to equivalent in seconds.

Referenced by Bmi_C_Adapter(), models::bmi::Bmi_Cpp_Adapter::Bmi_Cpp_Adapter(), models::bmi::Bmi_Adapter::convert_model_time_to_seconds(), models::bmi::Bmi_Adapter::convert_seconds_to_model_time(), and models::bmi::Bmi_Adapter::Initialize().

bmi_model_time_step_size

std::shared_ptr<double> models::bmi::Bmi_Adapter::bmi_model_time_step_size = nullptr

protectedinherited

Pointer to stored time step size value of backing model, if it is fixed and has been retrieved.

Referenced by get_bmi_model_time_step_size_ptr(), and models::bmi::Bmi_Cpp_Adapter::get_bmi_model_time_step_size_ptr().

bmi_registration_function

const std::string models::bmi::AbstractCLibBmiAdapter::bmi_registration_function

privateinherited

Name of the function that registers BMI struct's function pointers to the right module functions.

Referenced by models::bmi::AbstractCLibBmiAdapter::dynamic_library_load(), and models::bmi::AbstractCLibBmiAdapter::get_bmi_registration_function().

dyn_lib_handle

void* models::bmi::AbstractCLibBmiAdapter::dyn_lib_handle = nullptr

privateinherited

Handle for dynamically loaded library file.

Referenced by models::bmi::AbstractCLibBmiAdapter::dynamic_library_load(), models::bmi::AbstractCLibBmiAdapter::dynamic_load_symbol(), models::bmi::AbstractCLibBmiAdapter::finalizeForLibAbstraction(), and models::bmi::AbstractCLibBmiAdapter::get_dyn_lib_handle().

init_exception_msg

std::string models::bmi::Bmi_Adapter::init_exception_msg

protectedinherited

Message from an exception (if encountered) on the first attempt to initialize the backing model.

Referenced by models::bmi::Bmi_Adapter::Bmi_Adapter(), construct_and_init_backing_model_for_type(), models::bmi::AbstractCLibBmiAdapter::dynamic_library_load(), models::bmi::AbstractCLibBmiAdapter::dynamic_load_symbol(), models::bmi::Bmi_Cpp_Adapter::execModuleCreation(), execModuleRegistration(), and models::bmi::Bmi_Adapter::Initialize().

input_var_names

std::shared_ptr<std::vector<std::string> > models::bmi::Bmi_Adapter::input_var_names

protectedinherited

Pointer to collection of input variable names for backing model, used by GetInputVarNames().

Referenced by GetInputVarNames().

model_initialized

bool models::bmi::Bmi_Adapter::model_initialized = false

protectedinherited

Whether the backing model has been initialized yet, which is always initially false.

Referenced by Bmi_C_Adapter(), models::bmi::Bmi_Cpp_Adapter::Bmi_Cpp_Adapter(), construct_and_init_backing_model_for_type(), models::bmi::Bmi_Cpp_Adapter::construct_and_init_backing_model_for_type(), finalizeForCAdapter(), models::bmi::Bmi_Cpp_Adapter::finalizeForCppAdapter(), models::bmi::Bmi_Adapter::Initialize(), models::bmi::Bmi_Adapter::Initialize(), is_model_initialized(), models::bmi::Bmi_Cpp_Adapter::is_model_initialized(), and models::bmi::Bmi_Adapter::isInitialized().

model_name

std::string models::bmi::Bmi_C_Adapter::model_name = "BMI C model"

protected

Referenced by construct_and_init_backing_model_for_type(), finalizeForCAdapter(), get_value(), GetComponentName(), GetCurrentTime(), GetEndTime(), GetGridEdgeCount(), GetGridEdgeNodes(), GetGridFaceCount(), GetGridFaceEdges(), GetGridFaceNodes(), GetGridNodeCount(), GetGridNodesPerFace(), GetGridOrigin(), GetGridRank(), GetGridShape(), GetGridSize(), GetGridSpacing(), GetGridType(), GetGridX(), GetGridY(), GetGridZ(), GetStartTime(), GetTimeUnits(), GetValueAtIndices(), GetValuePtr(), GetValuePtr(), GetVarGrid(), GetVarItemsize(), GetVarLocation(), GetVarNbytes(), GetVarType(), GetVarUnits(), inner_get_input_item_count(), inner_get_output_item_count(), inner_get_variable_names(), retrieve_bmi_model_time_step_size(), SetValue(), SetValue(), SetValueAtIndices(), SetValueAtIndices(), Update(), and UpdateUntil().

output_var_names

std::shared_ptr<std::vector<std::string> > models::bmi::Bmi_Adapter::output_var_names

protectedinherited

Pointer to collection of output variable names for backing model, used by GetOutputVarNames().

Referenced by GetOutputVarNames().

---

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

• include/bmi/Bmi_C_Adapter.hpp
• src/bmi/Bmi_C_Adapter.cpp