Add function to get node coordinate units

bmi.sidl

@@ -1,7 +1,7 @@
 //
 // The Basic Model Interface (BMI)
 //
-package csdms version 2.0 {
+package csdms version 2.1-beta {
   interface bmi {
 
     // Initialize, run, finalize (IRF)
@@ -36,17 +36,19 @@ package csdms version 2.0 {
     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,
-        in array<int, 1> inds);
+      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,
-        in array<> src);
+      in array<> src);
 
     // Grid information
     int get_grid_rank(in int grid, out int rank);
     int get_grid_size(in int grid, out int size);
     int get_grid_type(in int grid, out string type);
+    int get_grid_coordinate_units(in int grid, in string name,
+      out string units);
 
     // Uniform rectilinear
     int get_grid_shape(in int grid, in array<int, 1> shape);

docs/source/bmi.grid_funcs.rst

@@ -117,6 +117,44 @@ for :ref:`unstructured <unstructured_grids>` and
 [:ref:`grid_funcs` | :ref:`basic_model_interface`]
 
 
+.. _get_grid_coordinate_units:
+
+*get_grid_coordinate_units*
+...........................
+
+.. code-block:: java
+
+   /* SIDL */
+   int get_grid_coordinate_units(in int grid, in string name, out string units);
+
+Given a :term:`grid identifier`
+and a grid coordinate name---currently ``"x"``, ``"y"``, or ``"z"``---get
+the units of the coordinate.
+
+Standard unit names in lower case,
+such as ``"meters"`` or ``"millibars"``,
+should be used.
+Standard abbreviations,
+such as ``"m"`` or ``"mb"``, are also supported.
+The abbreviations used in the BMI are derived from
+Unidata's `UDUNITS`_ package.
+See, for example, `The Units Database`_ for a
+full description of valid unit names and a list of supported units.
+
+**Implementation notes**
+
+* This function is used for describing all :ref:`grid types <model_grids>`.
+* Dimensionless quantities (such as sigma coordinates)
+  should use ``""`` or ``"1"`` as the unit.
+* Grids without units should use ``"none"``.
+* In C++, Java, and Python, the *units* argument is omitted and the grid
+  units name is returned from the function.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
+
+[:ref:`grid_funcs` | :ref:`basic_model_interface`]
+
+
 .. _get_grid_shape:
 
 *get_grid_shape*

docs/source/bmi.spec.rst

@@ -89,51 +89,52 @@ grouped by functional category.
    :align: center
    :widths: 30, 70
 
-   ==============================  =========================================
-   Function                        Description 
-   ==============================  =========================================
-   :ref:`initialize`               Perform startup tasks for the model.
-   :ref:`update`                   Advance model state by one time step.
-   :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_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.
-   :ref:`get_var_itemsize`         Get the size (in bytes) of one element of a variable.
-   :ref:`get_var_nbytes`           Get the total size (in bytes) of a variable.
-   :ref:`get_var_location`         Get the grid element type of a variable.
-   :ref:`get_current_time`         Current time of the model.
-   :ref:`get_start_time`           Start time of the model.
-   :ref:`get_end_time`             End time of the model.
-   :ref:`get_time_units`           Time units used in the model.
-   :ref:`get_time_step`            Time step used in the model.
-   :ref:`get_value`                Get a copy of values of a given variable.
-   :ref:`get_value_ptr`            Get a reference to the values of a given variable.
-   :ref:`get_value_at_indices`     Get variable values at specific locations.
-   :ref:`set_value`                Set the values of a given variable.
-   :ref:`set_value_at_indices`     Set the values of a variable at specific locations.
-   :ref:`get_grid_rank`            Get the number of dimensions of a computational grid.
-   :ref:`get_grid_size`            Get the total number of elements of a computational grid.
-   :ref:`get_grid_type`            Get the grid type as a string.
-   :ref:`get_grid_shape`           Get the dimensions of a computational grid.
-   :ref:`get_grid_spacing`         Get the spacing between grid nodes.
-   :ref:`get_grid_origin`          Get the origin of a grid.
-   :ref:`get_grid_x`               Get the locations of a grid's nodes in dimension 1.
-   :ref:`get_grid_y`               Get the locations of a grid's nodes in dimension 2.
-   :ref:`get_grid_z`               Get the locations of a grid's nodes in dimension 3.
-   :ref:`get_grid_node_count`      Get the number of nodes in the grid.
-   :ref:`get_grid_edge_count`      Get the number of edges in the grid.
-   :ref:`get_grid_face_count`      Get the number of faces in the grid.
-   :ref:`get_grid_edge_nodes`      Get the edge-node connectivity.
-   :ref:`get_grid_face_edges`      Get the face-edge connectivity.
-   :ref:`get_grid_face_nodes`      Get the face-node connectivity.
-   :ref:`get_grid_nodes_per_face`  Get the number of nodes for each face.
-   ==============================  =========================================
+   ================================ =========================================
+   Function                         Description 
+   ================================ =========================================
+   :ref:`initialize`                Perform startup tasks for the model.
+   :ref:`update`                    Advance model state by one time step.
+   :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_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.
+   :ref:`get_var_itemsize`          Get the size (in bytes) of one element of a variable.
+   :ref:`get_var_nbytes`            Get the total size (in bytes) of a variable.
+   :ref:`get_var_location`          Get the grid element type of a variable.
+   :ref:`get_current_time`          Current time of the model.
+   :ref:`get_start_time`            Start time of the model.
+   :ref:`get_end_time`              End time of the model.
+   :ref:`get_time_units`            Time units used in the model.
+   :ref:`get_time_step`             Time step used in the model.
+   :ref:`get_value`                 Get a copy of values of a given variable.
+   :ref:`get_value_ptr`             Get a reference to the values of a given variable.
+   :ref:`get_value_at_indices`      Get variable values at specific locations.
+   :ref:`set_value`                 Set the values of a given variable.
+   :ref:`set_value_at_indices`      Set the values of a variable at specific locations.
+   :ref:`get_grid_rank`             Get the number of dimensions of a computational grid.
+   :ref:`get_grid_size`             Get the total number of elements of a computational grid.
+   :ref:`get_grid_type`             Get the grid type as a string.
+   :ref:`get_grid_coordinate_units` Get the units of each node coordinate of a grid.
+   :ref:`get_grid_shape`            Get the dimensions of a computational grid.
+   :ref:`get_grid_spacing`          Get the spacing between grid nodes.
+   :ref:`get_grid_origin`           Get the origin of a grid.
+   :ref:`get_grid_x`                Get the locations of a grid's nodes in dimension 1.
+   :ref:`get_grid_y`                Get the locations of a grid's nodes in dimension 2.
+   :ref:`get_grid_z`                Get the locations of a grid's nodes in dimension 3.
+   :ref:`get_grid_node_count`       Get the number of nodes in the grid.
+   :ref:`get_grid_edge_count`       Get the number of edges in the grid.
+   :ref:`get_grid_face_count`       Get the number of faces in the grid.
+   :ref:`get_grid_edge_nodes`       Get the edge-node connectivity.
+   :ref:`get_grid_face_edges`       Get the face-edge connectivity.
+   :ref:`get_grid_face_nodes`       Get the face-node connectivity.
+   :ref:`get_grid_nodes_per_face`   Get the number of nodes for each face.
+   ================================ =========================================
 
 .. include:: bmi.control_funcs.rst
 .. include:: bmi.info_funcs.rst

docs/source/conf.py

@@ -52,17 +52,17 @@
 
 # General information about the project.
 project = u'bmi'
-copyright = u'2021, Community Surface Dynamics Modeling System'
+copyright = u'2022, Community Surface Dynamics Modeling System'
 author = u'Community Surface Dynamics Modeling System'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '2.0'
+version = '2.1'
 # The full version, including alpha/beta/rc tags.
-release = '2.0'
+release = '2.1-beta'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/model_grids.rst

@@ -64,6 +64,7 @@ Uniform rectilinear grids use the following BMI functions:
 
 * :ref:`get_grid_rank`
 * :ref:`get_grid_size`
+* :ref:`get_grid_coordinate_units`
 * :ref:`get_grid_shape`
 * :ref:`get_grid_spacing`
 * :ref:`get_grid_origin`
@@ -93,6 +94,7 @@ Rectilinear grids use the following BMI functions:
 
 * :ref:`get_grid_rank`
 * :ref:`get_grid_size`
+* :ref:`get_grid_coordinate_units`
 * :ref:`get_grid_shape`
 * :ref:`get_grid_x`
 * :ref:`get_grid_y`
@@ -123,6 +125,7 @@ Structured quadrilateral grids use the following BMI functions:
 
 * :ref:`get_grid_rank`
 * :ref:`get_grid_size`
+* :ref:`get_grid_coordinate_units`
 * :ref:`get_grid_shape`
 * :ref:`get_grid_x`
 * :ref:`get_grid_y`
@@ -159,6 +162,7 @@ BMI uses the `ugrid conventions`_ to define unstructured grids.
 Unstructured grids use the following BMI functions:
 
 * :ref:`get_grid_rank`
+* :ref:`get_grid_coordinate_units`
 * :ref:`get_grid_x`
 * :ref:`get_grid_y`
 * :ref:`get_grid_z`