diff --git a/bmi.sidl b/bmi.sidl index 9c3b0fb..fc1f7bb 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -1,7 +1,7 @@ // // The Basic Model Interface (BMI) // -package csdms version 2.1-dev.0 { +package csdms version 3.0-alpha1 { interface bmi { // Model and BMI metadata @@ -15,10 +15,10 @@ package csdms version 2.1-dev.0 { // Model information int get_component_name(out string name); - int get_input_item_count(out int count); - int get_output_item_count(out int count); - int get_input_var_names(out array names); - int get_output_var_names(out array names); + + // Variable set information + int get_varset_member_count(in string set_name, out int count); + int get_varset_members(in string set_name, out array names); // Variable information int get_var_grid(in string name, out int grid); diff --git a/docs/source/bmi.info_funcs.md b/docs/source/bmi.info_funcs.md index 31efc1a..79281f9 100644 --- a/docs/source/bmi.info_funcs.md +++ b/docs/source/bmi.info_funcs.md @@ -46,121 +46,82 @@ but it should be unique to prevent conflicts with other components. - In C++, Java, and Python, this argument is omitted, and a string -- a basic type in these languages -- is returned from the function. -(get-input-item-count)= +(get-varset-member-count)= -## *get_input_item_count* +## *get_varset_member_count* ::::{tab-set} :sync-group: lang :::{tab-item} SIDL :sync: sidl -```java -int get_input_item_count(out int count); -``` -::: -:::{tab-item} Python -:sync: python -```python -def get_input_item_count(self) -> int: -``` -::: -:::{tab-item} c -:sync: c -```c -int get_input_item_count(void *self, int *count); -``` -::: -:::: - -The number of variables the model can use from other models -implementing a BMI. -Also the number of variables that can be set with {ref}`set-value`. - -**Implementation notes** - -- In C++, Java, and Python, the argument is omitted and the count is returned - from the function. -- In C and Fortran, an integer status code indicating success (zero) or failure - (nonzero) is returned. - -(get-output-item-count)= - -## *get_output_item_count* - -::::{tab-set} -:sync-group: lang - -:::{tab-item} SIDL -:sync: sidl ```java -int get_output_item_count(out int count); +int get_varset_member_count(in string set_name, out int count); ``` ::: - :::{tab-item} Python :sync: python ```python -def get_output_item_count(self) -> int: +def get_varset_member_count(self, set_name: str) -> int: ``` ::: :::{tab-item} c :sync: c ```c -int get_output_item_count(void *self, int *count); +int get_varset_member_count(void *self, const char *name, int *count); ``` ::: :::: -The number of variables the model can provide other models -implementing a BMI. -Also the number of variables that can be retrieved with {ref}`get-value`. +Gets the number of exchange items in a particular set exposed by the model. **Implementation notes** -- In C++, Java, and Python, the argument is omitted and the count is - returned from the function. -- In C and Fortran, an integer status code indicating success (zero) or failure - (nonzero) is returned. +- In C++, Java, and Python, the *count* argument is omitted and the count + is returned from the function. +- In C and Fortran, an integer status code indicating success (BMI_SUCCESS) or + failure (BMI_FAILURE) is returned. -(get-input-var-names)= +(get-varset-members)= -## *get_input_var_names* +## *get_varset_members* ::::{tab-set} :sync-group: lang :::{tab-item} SIDL :sync: sidl + ```java -int get_input_var_names(out array names); +int get_varset_members(in string set_name, out array names); ``` ::: :::{tab-item} Python :sync: python ```python -def get_input_var_names(self) -> tuple[str, ...]: +def get_varset_members(self, set_name: str) -> tuple[str, ...]: ``` ::: :::{tab-item} c :sync: c ```c -int get_input_var_names(void *self, char **names); +int get_varset_members(void *self, const char *name, char const* const* members); ``` ::: :::: -Gets an array of names for the variables the model can use from other -models implementing a BMI. -The length of the array is given by {ref}`get-input-item-count`. +Gets an array of names for the variables the model publishes in the requested set. +The length of the array is given by {ref}`get-varset-member-count`. The names are preferably in the form of CSDMS {term}`Standard Names`. -Standard Names enable a modeling framework to determine whether an -input variable in one model is equivalent to, or compatible with, -an output variable in another model. +Standard Names enable a modeling framework to determine whether a +variable in one model is equivalent to, or compatible with, +a corresponding variable in another model. This allows the framework to automatically connect components. Standard Names do not have to be used within the model. +Available variable sets are defined by this spec, extensions, ... + **Implementation notes** - In C and Fortran, the names are passed back as an array of character @@ -174,53 +135,5 @@ Standard Names do not have to be used within the model. function in a tuple, a standard container in the language. - A model might have no input variables. -(get-output-var-names)= - -## *get_output_var_names* - -::::{tab-set} -:sync-group: lang - -:::{tab-item} SIDL -:sync: sidl -```java -int get_output_var_names(out array names); -``` +:::{include} links.md ::: - -:::{tab-item} Python -:sync: python -```python -def get_output_var_names(self) -> tuple[str, ...]: -``` -::: -:::{tab-item} c -:sync: c -```c -int get_output_var_names(void *self, char **names); -``` -::: -:::: - -Gets an array of names for the variables the model can provide to other -models implementing a BMI. -The length of the array is given by {ref}`get-output-item-count`. -The names are preferably in the form of CSDMS {term}`Standard Names`. -Standard Names enable a modeling framework to determine whether an -input variable in one model is equivalent to, or compatible with, -an output variable in another model. -This allows the framework to automatically connect components. -Standard Names do not have to be used within the model. - -**Implementation notes** - -- In C and Fortran, the names are passed back as an array of character - pointers (because the variable names could have differing lengths), and an - integer status code indicating success (zero) or failure (nonzero) is returned. -- In C++, the argument is omitted and the names are returned from the - function in a vector, a standard container in the language. -- In Java, the argument is omitted and the names are returned from the - function in a string array, a standard container in the language. -- In Python, the argument is omitted and the names are returned from the - function in a tuple, a standard container in the language. -- A model may have no output variables. diff --git a/docs/source/bmi.spec.md b/docs/source/bmi.spec.md index c94eace..8f01edc 100644 --- a/docs/source/bmi.spec.md +++ b/docs/source/bmi.spec.md @@ -35,10 +35,8 @@ grouped by functional category. | {ref}`update-until` | Advance model state until the given time. | | {ref}`finalize` | Perform tear-down tasks for the model. | | {ref}`get-component-name` | Name of the model. | -| {ref}`get-input-item-count` | Count of a model's input variables. | -| {ref}`get-output-item-count` | Count of a model's output variables. | -| {ref}`get-input-var-names` | List of a model's input variables. | -| {ref}`get-output-var-names` | List of a model's output variables. | +| {ref}`get-varset-item-count` | Count of a model's variables in a set. | +| {ref}`get-varset-members` | List of a model's variables in a set. | | {ref}`get-var-grid` | Get the grid identifier for a variable. | | {ref}`get-var-type` | Get the data type of a variable. | | {ref}`get-var-units` | Get the units of a variable. |