Reference variables by number rather than name strings

bmi.sidl

@@ -1,8 +1,8 @@
 //
 // The Basic Model Interface (BMI)
 //
-package csdms version 2.1-dev.0 {
-  interface bmi {
+package csdms version 3.0-alpha1 {
+  interface bmi3 {
 
     // Model and BMI metadata
     int get_bmi_version(out string version);
@@ -21,12 +21,13 @@ package csdms version 2.1-dev.0 {
     int get_output_var_names(out array<string, 1> names);
 
     // Variable information
-    int get_var_grid(in string name, out int grid);
-    int get_var_type(in string name, out string type);
-    int get_var_units(in string name, out string units);
-    int get_var_itemsize(in string name, out int size);
-    int get_var_nbytes(in string name, out int nbytes);
-    int get_var_location(in string name, out string location);
+    int get_var_index(in string name, out int index);
+    int get_var_grid(in int index, out int grid);
+    int get_var_type(in int index, out string type);
+    int get_var_units(in int index, out string units);
+    int get_var_itemsize(in int index, out int size);
+    int get_var_nbytes(in int index, out int nbytes);
+    int get_var_location(in int index, out string location);
 
     // Time information
     int get_current_time(out double time);
@@ -36,14 +37,14 @@ package csdms version 2.1-dev.0 {
     int get_time_step(out double time_step);
 
     // Getters
-    int get_value(in string name, in array<> dest);
-    int get_value_ptr(in string name, out array<> dest_ptr);
-    int get_value_at_indices(in string name, in array<> dest,
+    int get_value(in int index, in array<> dest);
+    int get_value_ptr(in int index, out array<> dest_ptr);
+    int get_value_at_indices(in int index, in array<> dest,
         in array<int, 1> inds);
 
     // Setters
-    int set_value(in string name, in array<> src);
-    int set_value_at_indices(in string name, in array<int, 1> inds,
+    int set_value(in int index, in array<> src);
+    int set_value_at_indices(in int index, in array<int, 1> inds,
         in array<> src);
 
     // Grid information

docs/source/bmi.getter_setter.md

@@ -24,25 +24,25 @@ state variable can be changed or check the new data for validity.
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int get_value(in string name, in array<> dest);
+int get_value(in int index, in array<> dest);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
-def get_value(self, name: str, dest: NDArray[Any]) -> NDArray[Any]:
+def get_value(self, index: int, dest: NDArray[Any]) -> NDArray[Any]:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int get_value(void *self, const char *name, void *dest);
+int get_value(void *self, int index, void *dest);
 ```
 :::
 ::::
 
-The `get_value` function takes a variable name and copies values into a
+The `get_value` function takes a variable index and copies values into a
 provided array parameter.
 The type and size of the array parameter depend on the variable,
 and can be determined through
@@ -75,25 +75,25 @@ even if the model uses dimensional variables.
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int get_value_ptr(in string name, out array<> dest_ptr);
+int get_value_ptr(in int index, out array<> dest_ptr);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
-def get_value_ptr(self, name: str) -> NDArray[Any]:
+def get_value_ptr(self, index: int) -> NDArray[Any]:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int get_value_ptr(void *self, const char *name, void **dest_ptr);
+int get_value_ptr(void *self, int index, void **dest_ptr);
 ```
 :::
 ::::
 
-The `get_value_ptr` function takes a variable name and returns a reference
+The `get_value_ptr` function takes a variable index and returns a reference
 to a variable.
 Unlike the array parameter returned from {ref}`get-value`,
 the reference always points to the current values of the variable,
@@ -119,23 +119,23 @@ even if the model's state has changed.
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int get_value_at_indices(in string name, in array<> dest, in array<int, 1> inds);
+int get_value_at_indices(in int index, in array<> dest, in array<int, 1> inds);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
 def get_value_at_indices(
-    self, name: str, dest: NDArray[Any], inds: NDArray[np.int_]
+    self, index: int, dest: NDArray[Any], inds: NDArray[np.int_]
 ) -> NDArray[Any]:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
 int get_value_at_indices(
-    void *self, const char *name, void *dest, int *inds, int count
+    void *self, int index, void *dest, int *inds, int count
 );
 ```
 :::
@@ -164,25 +164,25 @@ Additionally,
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int set_value(in string name, in array<> src);
+int set_value(in int index, in array<> src);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
-def set_value(self, name: str, src: NDArray[Any]) -> None:
+def set_value(self, index: int, src: NDArray[Any]) -> None:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int set_value(void *self, const char *name, void *src);
+int set_value(void *self, int index, void *src);
 ```
 :::
 ::::
 
-The `set_value` function takes a variable name and an array of values,
+The `set_value` function takes a variable index and an array of values,
 *src*,
 and copies those values into the model's internal array of values,
 overwriting the current contents.
@@ -214,23 +214,23 @@ even if the model uses dimensional variables.
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int set_value_at_indices(in string name, in array<int, 1> inds, in array<> src);
+int set_value_at_indices(in int index, in array<int, 1> inds, in array<> src);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
 def set_value_at_indices(
-    self, name: str, inds: NDArray[np.int_], src: NDArray[Any]
+    self, index: int, inds: NDArray[np.int_], src: NDArray[Any]
 ) -> None:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
 int set_value_at_indices(
-    void *self, const char *name, int *inds, int count, void *src
+    void *self, int index, int *inds, int count, void *src
 );
 ```
 :::

docs/source/bmi.var_funcs.md

@@ -6,9 +6,44 @@ These BMI functions provide information
 about a particular input or output variable.
 They must accommodate any variable returned from the
 {ref}`get-input-var-names` or {ref}`get-output-var-names` functions --
-the variable name is used as an argument in each function.
-Based on the information returned,
-type or unit conversions can be applied when necessary.
+the variable index as obtained from {ref}`get-var-index` is used as an argument in each function.
+Based on the information returned, type or unit conversions can be applied when necessary.
+
+(get-var-index)=
+
+## *get_var_index*
+
+::::{tab-set}
+:sync-group: lang
+
+:::{tab-item} SIDL
+:sync: sidl
+
+```java
+int get_var_index(in string name, out int index);
+```
+:::
+:::{tab-item} Python
+:sync: python
+```python
+def get_var_index(self, name: str) -> int:
+```
+:::
+:::{tab-item} c
+:sync: c
+```c
+int get_var_index(void *self, const char *name, int *index);
+```
+:::
+::::
+
+Each input and output variable is associated with a numerical index.
+The `get_var_index` function provides the value for this index.
+These index values need not be in any particular order or range.
+The identifier can be passed to the BMI
+{ref}`variable information <var-funcs>` functions
+to get the details of a particular variable;
+e.g., size, type, units, grid, etc.
 
 (get-var-grid)=
 
@@ -21,19 +56,19 @@ type or unit conversions can be applied when necessary.
 :sync: sidl
 
 ```java
-int get_var_grid(in string name, out int grid);
+int get_var_grid(in int index, out int grid);
 ```
 :::
 :::{tab-item} Python
 :sync: python
 ```python
-def get_var_grid(self, name: str) -> int:
+def get_var_grid(self, index: int) -> int:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int get_var_grid(void *self, const char *name, int *grid);
+int get_var_grid(void *self, int index, int *grid);
 ```
 :::
 ::::
@@ -65,20 +100,20 @@ A model can have one or more grids.
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int get_var_type(in string name, out string type);
+int get_var_type(in int index, out string type);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
-def get_var_type(self, name: str) -> str:
+def get_var_type(self, index: int) -> str:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int get_var_type(void *self, const char *name, char *type);
+int get_var_type(void *self, int index, char *type);
 ```
 :::
 ::::
@@ -110,19 +145,19 @@ while in Fortran, use `integer`, `real`, and `double precision`.
 :sync: sidl
 
 ```java
-int get_var_units(in string name, out string units);
+int get_var_units(in int index, out string units);
 ```
 :::
 :::{tab-item} Python
 :sync: python
 ```python
-def get_var_units(self, name: str) -> str:
+def get_var_units(self, index: int) -> str:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int get_var_units(void *self, const char *name, char *units);
+int get_var_units(void *self, int index, char *units);
 ```
 :::
 ::::
@@ -159,20 +194,20 @@ full description of valid unit names and a list of supported units.
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int get_var_itemsize(in string name, out int size);
+int get_var_itemsize(in int index, out int size);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
-def get_var_itemsize(self, name: str) -> int:
+def get_var_itemsize(self, index: int) -> int:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int get_var_itemsize(void *self, const char *name, int *size);
+int get_var_itemsize(void *self, int index, int *size);
 ```
 :::
 ::::
@@ -199,20 +234,20 @@ For example, if data for a variable are stored as 64-bit integers,
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int get_var_nbytes(in string name, out int nbytes);
+int get_var_nbytes(in int index, out int nbytes);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
-def get_var_nbytes(self, name: str) -> int:
+def get_var_nbytes(self, index: int) -> int:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int get_var_nbytes(void *self, const char *name, int *nbytes);
+int get_var_nbytes(void *self, int index, int *nbytes);
 ```
 :::
 ::::
@@ -237,26 +272,26 @@ a variable; i.e., the number of items multiplied by the size of each item.
 :::{tab-item} SIDL
 :sync: sidl
 ```java
-int get_var_location(in string name, out string location);
+int get_var_location(in int index, out string location);
 ```
 :::
 
 :::{tab-item} Python
 :sync: python
 ```python
-def get_var_location(self, name: str) -> str:
+def get_var_location(self, index: int) -> str:
 ```
 :::
 :::{tab-item} c
 :sync: c
 ```c
-int get_var_location(void *self, const char *name, char *location);
+int get_var_location(void *self, int index, char *location);
 ```
 :::
 ::::
 
 The `get_var_location` function,
-given a variable name, returns a string that indicates on what grid
+given a variable index, returns a string that indicates on what grid
 element the variable is defined. Valid return values are:
 
 - `node`