BMI: Difference between revisions
From CSDMS
m (Add brief description of get_var_type) |
|||
Line 1: | Line 1: | ||
= CSDMS Basic Modeling Interface (version 1.0) = | = '''CSDMS Basic Modeling Interface (version 1.0)''' = | ||
<br/> | |||
<!-- ============================================= --> | |||
== {{ Bar Heading| text=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. | |||
<syntaxhighlight lang=sidl> | <syntaxhighlight lang=sidl> | ||
void initialize (in string config_file) | void initialize (in string config_file) | ||
Line 9: | Line 14: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== Model | <br/> | ||
<!-- ============================================= --> | |||
== {{ Bar Heading| text=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 | '''CSDMS Standard Names''']]. | |||
<syntaxhighlight lang=sidl> | <syntaxhighlight lang=sidl> | ||
array<string> get_input_var_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() | 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.) | 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. | |||
</syntaxhighlight> | </syntaxhighlight> | ||
== Variable | <br/> | ||
<!-- ============================================= --> | |||
== {{ Bar Heading| text=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 | '''CSDMS Standard Names''']]. | |||
<syntaxhighlight lang=sidl> | <syntaxhighlight lang=sidl> | ||
string get_var_type( in string long_var_name ) // ( returns type_string, e.g. ‘double’) | string get_var_type( in string long_var_name ) // ( returns type_string, e.g. ‘double’) | ||
Line 22: | Line 46: | ||
int get_var_rank( in string long_var_name ) // ( returns array rank or 0 for scalar) | 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 ) | 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.) | 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’) | string get_time_units() // (returns unit string for model time, e.g. ‘seconds’, ‘years’) | ||
Line 61: | Line 86: | ||
|} | |} | ||
== Variable | <br/> | ||
<!-- ============================================= --> | |||
== {{ Bar Heading| text=Variable Getter and Setter Functions}} == | |||
: | |||
<syntaxhighlight lang=sidl> | <syntaxhighlight lang=sidl> | ||
double get_0d_double( in string long_var_name ) | double get_0d_double( in string long_var_name ) | ||
Line 73: | Line 101: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== Grid | <br/> | ||
<!-- ============================================= --> | |||
== {{ Bar Heading| text=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 === | === Uniform Rectilinear === | ||
Line 109: | Line 152: | ||
array<int, 1> get_grid_offset (in string long_var_name) | array<int, 1> get_grid_offset (in string long_var_name) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
: | |||
: | |||
: |
Revision as of 16:43, 5 September 2012
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)