BMI
From CSDMS
Revision as of 16:43, 5 September 2012 by Peckhams (talk | contribs) (→CSDMS Basic Modeling Interface (version 1.0))
CSDMS Basic Modeling Interface (version 1.0)
Fine-grained Control Functions
- These BMI functions are critical to plug-and-play modeling because they allow a calling component to bypass a model's own time loop. They also provide the caller with fine-grained control over the model, similar to a TV remote control.
void initialize (in string config_file)
void update (in double dt) // Advance model variables by time interval, dt (dt=-1 means use model time step)
void finalize ()
void run_model (in string config_file) // Do a complete model run. Not needed for CMI.
Model Information Functions
- These BMI functions are called by the CSDMS framework in order to determine what input variables each model component needs and what output variables it can provide to other components.
- Note that "long variable name" and "long_var_name" refer to standardized variable names from the CSDMS Standard Names.
array<string> get_input_var_names()
Return a string array of the model's input variable names as "long variable names".
array<string> get_output_var_names()
Return a string array of the model's output variable names as "long variable names".
string get_attribute( in string att_name ) // (for model_name, mesh_type, time_step_type, etc.)
if (att_name == 'model_name'), return the name of the model.
If (att_name == 'mesh_type'), return either "uniform", "rectilinear", "s_mesh" or "u_mesh"
as defined below.
Variable Information Functions
- These BMI functions are called by the CSDMS framework to obtain information about a particular input or output variable. Based on this information, the framework can apply type or unit conversion when necessary.
- Note that "long variable name" and "long_var_name" refer to standardized variable names from the CSDMS Standard Names.
string get_var_type( in string long_var_name ) // ( returns type_string, e.g. ‘double’)
string get_var_units( in string long_var_name ) // ( returns unit_string, e.g. ‘meters’ )
int get_var_rank( in string long_var_name ) // ( returns array rank or 0 for scalar)
string get_var_name( in string long_var_name ) // ( returns model’s internal, short name )
double get_time_step() // (returns the model’s current timestep; adaptive or fixed.)
string get_time_units() // (returns unit string for model time, e.g. ‘seconds’, ‘years’)
double get_start_time()
double get_current_time()
double get_end_time()
GET_VAR_TYPE: Return data type of a variable as a string. Some possible values are given in the following table.
BMI datatype | C datatype |
---|---|
BMI_CHAR | char |
BMI_UNSIGNED_CHAR | unsigned char |
BMI_INT | signed int |
BMI_LONG | signed long int |
BMI_UNSIGNED | unsigned int |
BMI_UNSIGNED_LONG | unsigned long int |
BMI_FLOAT | float |
BMI_DOUBLE | double |
Variable Getter and Setter Functions
double get_0d_double( in string long_var_name )
array<double> get_1d_double( in string long_var_name )
array<double,2> get_2d_double( in string long_var_name )
array<double> get_2d_double_at_indices( in string long_var_name, array<int> indices )
void set_0d_double( in string long_var_name, in double scalar )
void set_1d_double( in string long_var_name, in array<double> array)
void set_2d_double( in string long_var_name, in array<double,2> array)
void set_2d_double_at_indices( in string long_var_name, in array<int> indices, in array<double,2> array)
Grid Information Functions
- The BMI function call get_attribute( 'mesh_type' ) should return one of the following strings:
uniform (for uniform rectilinear) rectilinear s_mesh (for structured mesh)
u_mesh (for unstructured mesh)
- Each of these strings corresponds to a particular type of model grid or mesh. In order to provide a complete and standardized description of a model's grid, there is a different set of BMI functions that are required for each model "mesh_type" as described in this section.
- Note that an "orthogonal curvilinear" coordinate system is a special case of a "structured mesh".
- Note that "uniform rectilinear", "rectilinear" and "structured mesh" all have the topology of a two-dimensional array.
Uniform Rectilinear
array<double, 1> get_grid_spacing (in string long_var_name)
array<double, 1> get_grid_lower_left_corner (in string long_var_name)
array<int, 1> get_grid_shape (in string long_var_name)
Rectilinear
array<double, 1> get_grid_x (in string long_var_name)
array<double, 1> get_grid_y (in string long_var_name)
array<double, 1> get_grid_z (in string long_var_name)
array<int, 1> get_grid_shape (in string long_var_name)
Structured Mesh
array<double, 1> get_grid_x (in string long_var_name)
array<double, 1> get_grid_y (in string long_var_name)
array<int, 1> get_grid_shape (in string long_var_name)
Unstructured Mesh
array<double, 1> get_grid_x (in string long_var_name)
array<double, 1> get_grid_y (in string long_var_name)
array<int, 1> get_grid_connectivity (in string long_var_name)
array<int, 1> get_grid_offset (in string long_var_name)