From 1ae9ff410cd41c29048c9c48e481e6e774af49ee Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Nov 2021 13:36:30 -0700 Subject: [PATCH 01/34] Add get_grid_units function --- bmi.sidl | 1 + 1 file changed, 1 insertion(+) diff --git a/bmi.sidl b/bmi.sidl index 950451a..8c9a163 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -47,6 +47,7 @@ package csdms version 2.0 { 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_units(in int grid, in string name, out string units); // Uniform rectilinear int get_grid_shape(in int grid, in array shape); From bff16c9e5e9e4742b17cd8342b08648ec3af577b Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Nov 2021 13:37:04 -0700 Subject: [PATCH 02/34] Update BMI version number --- bmi.sidl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bmi.sidl b/bmi.sidl index 8c9a163..e0b9c68 100644 --- a/bmi.sidl +++ b/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) From ab0e5f7ec6470a9be8c1302bb167e0901052ba52 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Nov 2021 15:40:51 -0700 Subject: [PATCH 03/34] Also update BMI version in docs --- docs/source/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b22fc0e..0278659 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,7 +52,7 @@ # General information about the project. project = u'bmi' -copyright = u'2020, Community Surface Dynamics Modeling System' +copyright = u'2021, 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 @@ -60,9 +60,9 @@ # 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. From 95380b4a6a148c6062d3b3892cac943c6898bbd2 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Nov 2021 15:41:32 -0700 Subject: [PATCH 04/34] Add docs entry for get_grid_units --- docs/source/bmi.grid_funcs.rst | 38 ++++++++++++++++++++++++++++++++++ docs/source/bmi.spec.rst | 1 + 2 files changed, 39 insertions(+) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 6b802bd..ecc3c20 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -220,6 +220,44 @@ the origin is given in the column dimension, followed by the row dimension, [:ref:`grid_funcs` | :ref:`basic_model_interface`] +.. _get_grid_units: + +*get_grid_units* +................. + +.. code-block:: java + + /* SIDL */ + int get_grid_units(in int grid, in string name, out string units); + +Given a :term:`grid identifier` +and a dimension name---currently ``"x"``, ``"y"``, or ``"z"``---get +the units of the grid dimension. + +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 `. +* Dimensionless quantities (such as sigma coordinates) + should use ``""`` or ``"1"`` as the unit. +* Grids without units should use ``"none"``. +* In C++ 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_x: *get_grid_x* diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index dbfe599..3e9163a 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -122,6 +122,7 @@ grouped by functional category. :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_units` Get the units of each dimension 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. From 570e2bb10a94368e6b3ab911b871b604fd517de1 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Nov 2021 15:51:27 -0700 Subject: [PATCH 05/34] List get_grid_units for each grid type --- docs/source/model_grids.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index 0e6b4dd..c57b5ab 100644 --- a/docs/source/model_grids.rst +++ b/docs/source/model_grids.rst @@ -67,6 +67,7 @@ Uniform rectilinear grids use the following BMI functions: * :ref:`get_grid_shape` * :ref:`get_grid_spacing` * :ref:`get_grid_origin` +* :ref:`get_grid_units` .. _rectilinear: @@ -94,6 +95,7 @@ Rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` * :ref:`get_grid_shape` +* :ref:`get_grid_units` * :ref:`get_grid_x` * :ref:`get_grid_y` * :ref:`get_grid_z` @@ -124,6 +126,7 @@ Structured quadrilateral grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` * :ref:`get_grid_shape` +* :ref:`get_grid_units` * :ref:`get_grid_x` * :ref:`get_grid_y` * :ref:`get_grid_z` @@ -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_units` * :ref:`get_grid_x` * :ref:`get_grid_y` * :ref:`get_grid_z` From 39f36a1254221f386746b8f5fef016840ff10055 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 14 Dec 2021 15:30:04 -0700 Subject: [PATCH 06/34] Rename get_grid_units to get_grid_node_coordinate_units --- bmi.sidl | 7 +-- docs/source/bmi.grid_funcs.rst | 76 ++++++++++++++-------------- docs/source/bmi.spec.rst | 92 +++++++++++++++++----------------- docs/source/model_grids.rst | 8 +-- 4 files changed, 92 insertions(+), 91 deletions(-) diff --git a/bmi.sidl b/bmi.sidl index e0b9c68..7a6f359 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -36,18 +36,19 @@ package csdms version 2.1-beta { 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 inds); + in array inds); // Setters int set_value(in string name, in array<> src); int set_value_at_indices(in string name, in array 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_units(in int grid, in string name, out string units); + int get_grid_node_coordinate_units(in int grid, in string name, + out string units); // Uniform rectilinear int get_grid_shape(in int grid, in array shape); diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 2db9279..c8f3243 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -117,6 +117,44 @@ for :ref:`unstructured ` and [:ref:`grid_funcs` | :ref:`basic_model_interface`] +.. _get_grid_node_coordinate_units: + +*get_grid_node_coordinate_units* +................. + +.. code-block:: java + + /* SIDL */ + int get_grid_node_coordinate_units(in int grid, in string name, out string units); + +Given a :term:`grid identifier` +and a node coordinate name---currently ``"x"``, ``"y"``, or ``"z"``---get +the units of the node 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 `. +* 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* @@ -220,44 +258,6 @@ the origin is given in the column dimension, followed by the row dimension, [:ref:`grid_funcs` | :ref:`basic_model_interface`] -.. _get_grid_units: - -*get_grid_units* -................. - -.. code-block:: java - - /* SIDL */ - int get_grid_units(in int grid, in string name, out string units); - -Given a :term:`grid identifier` -and a dimension name---currently ``"x"``, ``"y"``, or ``"z"``---get -the units of the grid dimension. - -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 `. -* Dimensionless quantities (such as sigma coordinates) - should use ``""`` or ``"1"`` as the unit. -* Grids without units should use ``"none"``. -* In C++ 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_x: *get_grid_x* diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index 443463c..2b0e27c 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -89,52 +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_units` Get the units of each dimension 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_node_coordinate_units` Get the units of each dimension 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 diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index c57b5ab..cebc310 100644 --- a/docs/source/model_grids.rst +++ b/docs/source/model_grids.rst @@ -64,10 +64,10 @@ Uniform rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` +* :ref:`get_grid_node_coordinate_units` * :ref:`get_grid_shape` * :ref:`get_grid_spacing` * :ref:`get_grid_origin` -* :ref:`get_grid_units` .. _rectilinear: @@ -94,8 +94,8 @@ Rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` +* :ref:`get_grid_node_coordinate_units` * :ref:`get_grid_shape` -* :ref:`get_grid_units` * :ref:`get_grid_x` * :ref:`get_grid_y` * :ref:`get_grid_z` @@ -125,8 +125,8 @@ Structured quadrilateral grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` +* :ref:`get_grid_node_coordinate_units` * :ref:`get_grid_shape` -* :ref:`get_grid_units` * :ref:`get_grid_x` * :ref:`get_grid_y` * :ref:`get_grid_z` @@ -162,7 +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_units` +* :ref:`get_grid_node_coordinate_units` * :ref:`get_grid_x` * :ref:`get_grid_y` * :ref:`get_grid_z` From 3381d5f3ab9d4a61c919733430f14864959c2028 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 14 Dec 2021 15:35:33 -0700 Subject: [PATCH 07/34] Update short description --- docs/source/bmi.grid_funcs.rst | 2 +- docs/source/bmi.spec.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index c8f3243..b481e14 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -120,7 +120,7 @@ for :ref:`unstructured ` and .. _get_grid_node_coordinate_units: *get_grid_node_coordinate_units* -................. +................................ .. code-block:: java diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index 2b0e27c..2f19b21 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -120,7 +120,7 @@ grouped by functional category. :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_node_coordinate_units` Get the units of each dimension of a grid. + :ref:`get_grid_node_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. From 2a3e3f0f385b9ef27a3e0330119b05c518071fa5 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 15 Dec 2021 11:21:36 -0700 Subject: [PATCH 08/34] Rename get_grid_node_coordinate_units to get_grid_coordinate_units --- bmi.sidl | 2 +- docs/source/bmi.grid_funcs.rst | 12 ++--- docs/source/bmi.spec.rst | 92 +++++++++++++++++----------------- docs/source/model_grids.rst | 8 +-- 4 files changed, 57 insertions(+), 57 deletions(-) diff --git a/bmi.sidl b/bmi.sidl index 7a6f359..3eab6c2 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -47,7 +47,7 @@ package csdms version 2.1-beta { 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_node_coordinate_units(in int grid, in string name, + int get_grid_coordinate_units(in int grid, in string name, out string units); // Uniform rectilinear diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index b481e14..90d7b42 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -117,19 +117,19 @@ for :ref:`unstructured ` and [:ref:`grid_funcs` | :ref:`basic_model_interface`] -.. _get_grid_node_coordinate_units: +.. _get_grid_coordinate_units: -*get_grid_node_coordinate_units* -................................ +*get_grid_coordinate_units* +........................... .. code-block:: java /* SIDL */ - int get_grid_node_coordinate_units(in int grid, in string name, out string units); + int get_grid_coordinate_units(in int grid, in string name, out string units); Given a :term:`grid identifier` -and a node coordinate name---currently ``"x"``, ``"y"``, or ``"z"``---get -the units of the node coordinate. +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"``, diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index 2f19b21..1a0e5ca 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -89,52 +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_node_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. - ===================================== ========================================= + ================================ ========================================= + 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 diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index cebc310..9c01237 100644 --- a/docs/source/model_grids.rst +++ b/docs/source/model_grids.rst @@ -64,7 +64,7 @@ Uniform rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` -* :ref:`get_grid_node_coordinate_units` +* :ref:`get_grid_coordinate_units` * :ref:`get_grid_shape` * :ref:`get_grid_spacing` * :ref:`get_grid_origin` @@ -94,7 +94,7 @@ Rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` -* :ref:`get_grid_node_coordinate_units` +* :ref:`get_grid_coordinate_units` * :ref:`get_grid_shape` * :ref:`get_grid_x` * :ref:`get_grid_y` @@ -125,7 +125,7 @@ Structured quadrilateral grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` -* :ref:`get_grid_node_coordinate_units` +* :ref:`get_grid_coordinate_units` * :ref:`get_grid_shape` * :ref:`get_grid_x` * :ref:`get_grid_y` @@ -162,7 +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_node_coordinate_units` +* :ref:`get_grid_coordinate_units` * :ref:`get_grid_x` * :ref:`get_grid_y` * :ref:`get_grid_z` From 710c59a107fa5ba64390c90ac77f29e2a16c9534 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 7 Mar 2022 14:36:57 -0700 Subject: [PATCH 09/34] Update copyright year --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0278659..c58b998 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,7 +52,7 @@ # 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 From 2e7f65afa08dae5ff6ef94285804c38a6d12882d Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Fri, 11 Mar 2022 16:32:17 -0700 Subject: [PATCH 10/34] Add SIDL for get_grid_coordinate_names --- bmi.sidl | 1 + 1 file changed, 1 insertion(+) diff --git a/bmi.sidl b/bmi.sidl index 3eab6c2..059fefd 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -47,6 +47,7 @@ package csdms version 2.1-beta { 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_names(in int grid, out array names); int get_grid_coordinate_units(in int grid, in string name, out string units); From ef2850ffaf67c7994984e5da1578d02ac03a3440 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Fri, 11 Mar 2022 16:37:00 -0700 Subject: [PATCH 11/34] Add docs entry for get_grid_coordinate_names --- docs/source/bmi.grid_funcs.rst | 32 ++++++++++++++++++++++++++++++++ docs/source/bmi.spec.rst | 1 + docs/source/model_grids.rst | 4 ++++ 3 files changed, 37 insertions(+) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 90d7b42..3107371 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -117,6 +117,38 @@ for :ref:`unstructured ` and [:ref:`grid_funcs` | :ref:`basic_model_interface`] +.. _get_grid_coordinate_names: + +*get_grid_coordinate_names* +........................... + +.. code-block:: java + + /* SIDL */ + int get_grid_coordinate_names(in int grid, out array names); + +Given a :term:`grid identifier`, +get an array of the names of the coordinates defined for the grid; +e.g., ``["x", "y", "z"]``. +The length of the array is given by :ref:`get_grid_rank`. + +**Implementation notes** + +* This function is used for describing all :ref:`grid types `. +* Grids without coordinates (e.g., ``scalar`` or ``none``) should use ``"none"``. +* In C and Fortran, the names are passed back as an array of character pointers + (because the coordinate 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. + +[:ref:`grid_funcs` | :ref:`basic_model_interface`] + + .. _get_grid_coordinate_units: *get_grid_coordinate_units* diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index 1a0e5ca..a3d2ba7 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -120,6 +120,7 @@ grouped by functional category. :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_names` Get the name of each node coordinate of a grid. :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. diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index 9c01237..2411281 100644 --- a/docs/source/model_grids.rst +++ b/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_names` * :ref:`get_grid_coordinate_units` * :ref:`get_grid_shape` * :ref:`get_grid_spacing` @@ -94,6 +95,7 @@ Rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` +* :ref:`get_grid_coordinate_names` * :ref:`get_grid_coordinate_units` * :ref:`get_grid_shape` * :ref:`get_grid_x` @@ -125,6 +127,7 @@ Structured quadrilateral grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` +* :ref:`get_grid_coordinate_names` * :ref:`get_grid_coordinate_units` * :ref:`get_grid_shape` * :ref:`get_grid_x` @@ -162,6 +165,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_names` * :ref:`get_grid_coordinate_units` * :ref:`get_grid_x` * :ref:`get_grid_y` From bd9191ee6b3ee4f349d0694dc5d449d3f0d0fc9a Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Fri, 11 Mar 2022 16:42:58 -0700 Subject: [PATCH 12/34] Note that some grids won't have coordinates --- docs/source/bmi.grid_funcs.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 3107371..4892373 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -135,7 +135,6 @@ The length of the array is given by :ref:`get_grid_rank`. **Implementation notes** * This function is used for describing all :ref:`grid types `. -* Grids without coordinates (e.g., ``scalar`` or ``none``) should use ``"none"``. * In C and Fortran, the names are passed back as an array of character pointers (because the coordinate names could have differing lengths), and an integer status code indicating success (zero) or failure (nonzero) is returned. @@ -145,6 +144,8 @@ The length of the array is given by :ref:`get_grid_rank`. 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. +* Some grids may not have coordinates (e.g., grids of type ``scalar`` or + ``none``). [:ref:`grid_funcs` | :ref:`basic_model_interface`] From ed82e8563e68bc27e84ad80d65e4f26e2e583458 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 14 Mar 2022 14:32:30 -0600 Subject: [PATCH 13/34] Add SIDL for get_grid_coordinate function Also arranged functions to match order in documentation + removed stale headers. --- bmi.sidl | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/bmi.sidl b/bmi.sidl index 059fefd..e1d125b 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -47,21 +47,14 @@ package csdms version 2.1-beta { 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_names(in int grid, out array names); - 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 shape); int get_grid_spacing(in int grid, in array spacing); int get_grid_origin(in int grid, in array origin); - - // Non-uniform rectilinear, curvilinear - int get_grid_x(in int grid, in array x); - int get_grid_y(in int grid, in array y); - int get_grid_z(in int grid, in array z); - - // Unstructured + int get_grid_coordinate_names(in int grid, out array names); + int get_grid_coordinate_units(in int grid, in string name, + out string units); + int get_grid_coordinate(in int grid, in string name, + in array coordinates); int get_grid_node_count(in int grid, out int count); int get_grid_edge_count(in int grid, out int count); int get_grid_face_count(in int grid, out int count); From 3081bd3b1b8246d66e5a71dcdfb60ef26c70066f Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 14 Mar 2022 14:34:53 -0600 Subject: [PATCH 14/34] Add get_grid_coordinate to table of BMI functions Also: * Updated ordering * Removed deprecated functions --- docs/source/bmi.spec.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index a3d2ba7..9c545c4 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -120,14 +120,12 @@ grouped by functional category. :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_names` Get the name of each node coordinate of a grid. - :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_coordinate_names` Get the name of each node coordinate of a grid. + :ref:`get_grid_coordinate_units` Get the units of each node coordinate of a grid. + :ref:`get_grid_coordinate` Get the location of each node of a single grid coordinate. :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. From 1521709a64a1d737f8effca8bbd0a63a1052953e Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 14 Mar 2022 14:51:48 -0600 Subject: [PATCH 15/34] Replace get_grid[xyz] functions with get_grid_coordinate --- docs/source/bmi.grid_funcs.rst | 81 ++++++---------------------------- 1 file changed, 13 insertions(+), 68 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 4892373..b8cd16b 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -291,81 +291,24 @@ the origin is given in the column dimension, followed by the row dimension, [:ref:`grid_funcs` | :ref:`basic_model_interface`] -.. _get_grid_x: +.. _get_grid_coordinate: -*get_grid_x* -............ - -.. code-block:: java - - /* SIDL */ - int get_grid_x(in int grid, in array x); - -Get the locations of the grid :term:`nodes ` in the first -coordinate direction. - -The length of the resulting one-dimensional array depends on the grid type. -(It will have either :ref:`get_grid_rank` or :ref:`get_grid_size` elements.) -See :ref:`model_grids` for more information. - -**Implementation notes** - -* This function is used for describing :ref:`rectilinear `, - :ref:`structured quadrilateral `, - and all :ref:`unstructured ` grids. -* In Python, the *x* argument is a :term:`numpy ` array. -* In C++ and Java, this is a void 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_y: - -*get_grid_y* -............ - -.. code-block:: java - - /* SIDL */ - int get_grid_y(in int grid, in array y); - -Get the locations of the grid :term:`nodes ` in the second -coordinate direction. - -The length of the resulting one-dimensional array depends on the grid type. -(It will have either :ref:`get_grid_rank` or :ref:`get_grid_size` elements.) -See :ref:`model_grids` for more information. - -**Implementation notes** - -* This function is used for describing :ref:`rectilinear `, - :ref:`structured quadrilateral `, - and all :ref:`unstructured ` grids. -* In Python, the *y* argument is a :term:`numpy ` array. -* In C++ and Java, this is a void 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_z: - -*get_grid_z* -............ +*get_grid_coordinate* +..................... .. code-block:: java /* SIDL */ - int get_grid_z(in int grid, in array z); + int get_grid_coordinate(in int grid, in string name, in array coordinates); -Get the locations of the grid :term:`nodes ` in the third +Given a :term:`grid identifier` +and a coordinate name returned from :ref:`get_grid_coordinate_names`, +get the locations of the grid :term:`nodes ` in a single coordinate direction. -The length of the resulting one-dimensional array depends on the grid type. -(It will have either :ref:`get_grid_rank` or :ref:`get_grid_size` elements.) +The length of the one-dimensional array of coordinates depends on the grid type +and the individual coordinate. +(It will be a value from either :ref:`get_grid_shape` or :ref:`get_grid_size`.) See :ref:`model_grids` for more information. **Implementation notes** @@ -373,10 +316,12 @@ See :ref:`model_grids` for more information. * This function is used for describing :ref:`rectilinear `, :ref:`structured quadrilateral `, and all :ref:`unstructured ` grids. -* In Python, the *z* argument is a :term:`numpy ` array. +* In Python, the *coordinates* argument is a :term:`numpy ` array. * In C++ and Java, this is a void function. * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned. +* This function was introduced in BMI 2.1. It replaces the deprecated + *get_grid_x*, *get_grid_y*, and *get_grid_z* functions. [:ref:`grid_funcs` | :ref:`basic_model_interface`] From cc16050a8ef755b3e1070c917e24068502c6bfde Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 14 Mar 2022 14:54:14 -0600 Subject: [PATCH 16/34] Group docs for get_grid_coordinate family of functions --- docs/source/bmi.grid_funcs.rst | 142 ++++++++++++++++----------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index b8cd16b..7fe967c 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -117,77 +117,6 @@ for :ref:`unstructured ` and [:ref:`grid_funcs` | :ref:`basic_model_interface`] -.. _get_grid_coordinate_names: - -*get_grid_coordinate_names* -........................... - -.. code-block:: java - - /* SIDL */ - int get_grid_coordinate_names(in int grid, out array names); - -Given a :term:`grid identifier`, -get an array of the names of the coordinates defined for the grid; -e.g., ``["x", "y", "z"]``. -The length of the array is given by :ref:`get_grid_rank`. - -**Implementation notes** - -* This function is used for describing all :ref:`grid types `. -* In C and Fortran, the names are passed back as an array of character pointers - (because the coordinate 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. -* Some grids may not have coordinates (e.g., grids of type ``scalar`` or - ``none``). - -[: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 `. -* 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* @@ -291,6 +220,77 @@ the origin is given in the column dimension, followed by the row dimension, [:ref:`grid_funcs` | :ref:`basic_model_interface`] +.. _get_grid_coordinate_names: + +*get_grid_coordinate_names* +........................... + +.. code-block:: java + + /* SIDL */ + int get_grid_coordinate_names(in int grid, out array names); + +Given a :term:`grid identifier`, +get an array of the names of the coordinates defined for the grid; +e.g., ``["x", "y", "z"]``. +The length of the array is given by :ref:`get_grid_rank`. + +**Implementation notes** + +* This function is used for describing all :ref:`grid types `. +* In C and Fortran, the names are passed back as an array of character pointers + (because the coordinate 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. +* Some grids may not have coordinates (e.g., grids of type ``scalar`` or + ``none``). + +[: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 `. +* 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_coordinate: *get_grid_coordinate* From 0aa8b54bfbcf4c4531d84e7f631423f78e7b05c6 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 14 Mar 2022 14:55:34 -0600 Subject: [PATCH 17/34] Note BMI version in new functions --- docs/source/bmi.grid_funcs.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 7fe967c..ceb3f64 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -249,6 +249,7 @@ The length of the array is given by :ref:`get_grid_rank`. function in a tuple, a standard container in the language. * Some grids may not have coordinates (e.g., grids of type ``scalar`` or ``none``). +* This function was introduced in BMI 2.1. [:ref:`grid_funcs` | :ref:`basic_model_interface`] @@ -287,6 +288,7 @@ full description of valid unit names and a list of supported units. units name is returned from the function. * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned. +* This function was introduced in BMI 2.1. [:ref:`grid_funcs` | :ref:`basic_model_interface`] From aed48048701753104793b2a4c1a2fddd04584c9f Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 14 Mar 2022 16:04:03 -0600 Subject: [PATCH 18/34] Enable numbered figures --- docs/source/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index c58b998..03f0241 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -116,6 +116,8 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True +# Enable numbered figures. +numfig = True # -- Options for HTML output ---------------------------------------------- From 84442629010cb910a79455e2206a751f14318ade Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 14 Mar 2022 16:26:03 -0600 Subject: [PATCH 19/34] Convert grid diagrams to sphinx figures --- docs/source/model_grids.rst | 47 ++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index 2411281..f8d0b4b 100644 --- a/docs/source/model_grids.rst +++ b/docs/source/model_grids.rst @@ -44,15 +44,19 @@ its length would be listed first. Uniform rectilinear ^^^^^^^^^^^^^^^^^^^ -.. image:: images/mesh_uniform_rectilinear.png +.. _fig-uniform-rectilinear: +.. figure:: images/mesh_uniform_rectilinear.png :scale: 20 % + :alt: Example uniform rectilinear grid, + + An example of a rank 2 uniform rectilinear grid. A uniform rectilinear grid is a special case of structured quadrilateral grid where the elements have equal width in each dimension. That is, for a two-dimensional grid, elements have a constant width of ``dx`` in the *x*-direction and ``dy`` in the *y*-direction. -The case of ``dx == dy`` is oftentimes called -a *raster* or *Catesian grid*. +The special case of ``dx == dy`` (as in :numref:`fig-uniform-rectilinear`) +is often called a *raster* or *Cartesian grid*. To completely specify a uniform rectilinear grid, only three pieces of information are needed: @@ -64,11 +68,11 @@ Uniform rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` -* :ref:`get_grid_coordinate_names` -* :ref:`get_grid_coordinate_units` * :ref:`get_grid_shape` * :ref:`get_grid_spacing` * :ref:`get_grid_origin` +* :ref:`get_grid_coordinate_names` +* :ref:`get_grid_coordinate_units` .. _rectilinear: @@ -76,11 +80,15 @@ Uniform rectilinear grids use the following BMI functions: Rectilinear ^^^^^^^^^^^ -.. image:: images/mesh_rectilinear.png +.. _fig-rectilinear: +.. figure:: images/mesh_rectilinear.png :scale: 20 % + :alt: Example rectilinear grid, + + An example of a rank 2 rectilinear grid. In a rectilinear grid, the spacing between nodes in each dimension varies, -as depicted above. +as depicted in :numref:`fig-rectilinear`. Therefore, an array of coordinates for each row and column (for the two-dimensional case) is required. @@ -95,12 +103,10 @@ Rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` +* :ref:`get_grid_shape` * :ref:`get_grid_coordinate_names` * :ref:`get_grid_coordinate_units` -* :ref:`get_grid_shape` -* :ref:`get_grid_x` -* :ref:`get_grid_y` -* :ref:`get_grid_z` +* :ref:`get_grid_coordinate` .. _structured_quad: @@ -108,12 +114,17 @@ Rectilinear grids use the following BMI functions: Structured quadrilateral ^^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: images/mesh_structured_quad.png +.. _fig-structured-quad: +.. figure:: images/mesh_structured_quad.png :scale: 20 % + :alt: Example structured quadrilateral grid, + + An example of a rank 2 structured quadrilateral grid. The most general structured quadrilateral grid is one where -the rows (and columns) do not share a common coordinate. In this -case, coordinates are required for each grid node. For this +the rows (and columns) do not share a common coordinate +(:numref:`fig-structured-quad`). +In this case, coordinates are required for each grid node. For this more general case, :ref:`get_grid_x` and :ref:`get_grid_y` are repurposed to provide this information. @@ -140,8 +151,12 @@ Structured quadrilateral grids use the following BMI functions: Unstructured grids ------------------ -.. image:: images/mesh_unstructured.png +.. _fig-unstructured: +.. figure:: images/mesh_unstructured.png :scale: 25 % + :alt: Example unstructured grid, + + An example of a rank 2 unstructured grid. This category includes the *unstructured* type, as well as the special cases @@ -179,7 +194,7 @@ Unstructured grids use the following BMI functions: * :ref:`get_grid_nodes_per_face` For a demonstration of how these BMI functions work, -let's use the unstructured grid in the annotated figure above. +let's use the unstructured grid in :numref:`fig-unstructured` above. The grid is two-dimensional, so the :ref:`get_grid_rank` function returns 2. From c571f2c99462a61d2c5c3d742cfbf897dd499242 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 14 Mar 2022 17:00:20 -0600 Subject: [PATCH 20/34] Use get_grid_coordinate_names in description of get_grid_coordinate_units --- docs/source/bmi.grid_funcs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index ceb3f64..cf874f8 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -265,8 +265,8 @@ The length of the array is given by :ref:`get_grid_rank`. 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. +and a coordinate name returned from :ref:`get_grid_coordinate_names`, +get the units of the coordinate. Standard unit names in lower case, such as ``"meters"`` or ``"millibars"``, From beb80c4965be1f10c1ee5d3c906a98263bf176e3 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 15 Mar 2022 12:28:15 -0600 Subject: [PATCH 21/34] Remove stale references to get_grid_[xyz] --- docs/source/bmi.grid_funcs.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index cf874f8..b932a7f 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -71,10 +71,10 @@ Given a :term:`grid identifier`, get the :term:`rank` (the number of dimensions) of that grid as an integer. A grid's rank determines the length of the return value -of many of the following grid functions. -For instance, :ref:`get_grid_shape` returns an array of length *rank*. -Similarly, a grid's rank determines which -of :ref:`get_grid_x`, :ref:`get_grid_y`, etc. are implemented. +of several grid functions. +For example, +both :ref:`get_grid_shape` and :ref:`get_grid_coordinate_names` +return an array of length *rank*. **Implementation notes** @@ -102,7 +102,7 @@ get the total number of elements (or :term:`nodes `) of that grid as an integer. The grid size is used for, among other things, the -length of arrays returned by :ref:`get_grid_x` and :ref:`get_grid_y` +length of arrays returned by :ref:`get_grid_coordinate` for :ref:`unstructured ` and :ref:`structured quad ` grids. From 64f01df421afaed3fe56d8bf87cbb2826cc0417a Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 15 Mar 2022 12:42:48 -0600 Subject: [PATCH 22/34] Update description of rectilinear grids --- docs/source/model_grids.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index f8d0b4b..09d9d51 100644 --- a/docs/source/model_grids.rst +++ b/docs/source/model_grids.rst @@ -26,7 +26,7 @@ In the BMI, dimensional information is ordered with "ij" indexing (as opposed to "xy"). For example, -for the uniform rectilinear grid shown below, +for the uniform rectilinear grid shown in :numref:`fig-uniform-rectilinear` below, the :ref:`get_grid_shape` function would return the array ``[4, 5]``. If there was a third dimension, its length would be listed first. @@ -93,12 +93,6 @@ Therefore, an array of coordinates for each row and column (for the two-dimensional case) is required. -The :ref:`get_grid_y` function provides an array (whose length is the number of -*rows*) that gives the *y*-coordinate for each row. - -The :ref:`get_grid_x` function provides an array (whose length is the number of -*columns*) that gives the *x*-coordinate for each column. - Rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` @@ -108,6 +102,18 @@ Rectilinear grids use the following BMI functions: * :ref:`get_grid_coordinate_units` * :ref:`get_grid_coordinate` +In :numref:`fig-rectilinear`, +if :ref:`get_grid_coordinate_names` returns ``["x","y"]`` +for the names of the dimensions, +then: + +* given ``"y"``, the :ref:`get_grid_coordinate` function provides an array, + whose length is the number of *rows*, + that gives the *y*-coordinate for each row; +* given ``"x"``, the :ref:`get_grid_coordinate` function provides an array, + whose length is the number of *columns*, + that gives the *x*-coordinate for each column. + .. _structured_quad: From 8ccf273071e456e426180ca8f01d8ea6357024de Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 15 Mar 2022 13:20:23 -0600 Subject: [PATCH 23/34] Update description of structured quad grids --- docs/source/model_grids.rst | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index 09d9d51..e218536 100644 --- a/docs/source/model_grids.rst +++ b/docs/source/model_grids.rst @@ -127,29 +127,33 @@ Structured quadrilateral An example of a rank 2 structured quadrilateral grid. -The most general structured quadrilateral grid is one where -the rows (and columns) do not share a common coordinate +The most general structured grid is one where +the rows and columns of nodes do not share a common coordinate (:numref:`fig-structured-quad`). -In this case, coordinates are required for each grid node. For this -more general case, :ref:`get_grid_x` and :ref:`get_grid_y` are -repurposed to provide this information. - -The :ref:`get_grid_y` function returns an array (whose length is the number -of total nodes returned by :ref:`get_grid_size`) of *y*-coordinates. - -The :ref:`get_grid_x` function returns an array (whose length is the number -of total nodes returned by :ref:`get_grid_size`) of *x*-coordinates. +In this case, +coordinates are required for each grid node, +and :ref:`get_grid_coordinate` is repurposed to provide this information: Structured quadrilateral grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` +* :ref:`get_grid_shape` * :ref:`get_grid_coordinate_names` * :ref:`get_grid_coordinate_units` -* :ref:`get_grid_shape` -* :ref:`get_grid_x` -* :ref:`get_grid_y` -* :ref:`get_grid_z` +* :ref:`get_grid_coordinate` + +In :numref:`fig-structured-quad`, +if :ref:`get_grid_coordinate_names` returns ``["x","y"]`` +for the names of the dimensions, +then: + +* given ``"y"``, the :ref:`get_grid_coordinate` function returns an array, + whose length is the total number of nodes from :ref:`get_grid_size`, + of *y*-coordinates. +* given ``"x"``, the :ref:`get_grid_coordinate` function returns an array, + whose length is the total number of nodes from :ref:`get_grid_size`, + of *x*-coordinates. .. _unstructured_grids: From 712cfabb8150ff1c26a0d1655b14b3ae8b2035d7 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 15 Mar 2022 13:37:19 -0600 Subject: [PATCH 24/34] Update unstructured grids section --- docs/source/model_grids.rst | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index e218536..cb36e63 100644 --- a/docs/source/model_grids.rst +++ b/docs/source/model_grids.rst @@ -174,27 +174,24 @@ as well as the special cases This is the most general grid type. It can be used for any type of grid. This grid type must be used if the grid consists of cells -that are not quadrilaterals; -this includes any grid of triangles (e.g. `Delaunay triangles`_ +that are not quadrilaterals, +including any grid of triangles (e.g. `Delaunay triangles`_ and `Voronoi tesselations`_). .. note:: - A grid of `equilateral triangles`_, while they are most certainly - *structured*, would need to be represented as an unstructured grid. + A grid of `equilateral triangles`_, while they are *structured*, + would need to be represented as an unstructured grid. The same is true for a grid of `hexagons`_. - -BMI uses the `ugrid conventions`_ to define unstructured grids. +BMI uses the `UGRID Conventions`_ to define unstructured grids. Unstructured grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_coordinate_names` * :ref:`get_grid_coordinate_units` -* :ref:`get_grid_x` -* :ref:`get_grid_y` -* :ref:`get_grid_z` +* :ref:`get_grid_coordinate` * :ref:`get_grid_node_count` * :ref:`get_grid_edge_count` * :ref:`get_grid_face_count` @@ -217,8 +214,7 @@ are given by coordinates x = [0, 1, 2, 1, 3, 4] y = [3, 1, 2, 4, 0, 3] -These will be the outputs of the :ref:`get_grid_x` and -:ref:`get_grid_y` functions, respectively. +These coordinates are found through the :ref:`get_grid_coordinate` function. The nodes are indexed, so node 0 is at *(x, y) = (0, 3)*, node 1 is at *(x, y) = (1, 1)*, etc. From c4afd304716ace98b6ff82c57a14ccb822bd1aff Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Tue, 15 Mar 2022 15:39:10 -0600 Subject: [PATCH 25/34] Touch up function descriptions --- docs/source/bmi.grid_funcs.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index b932a7f..62c007c 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -231,8 +231,10 @@ the origin is given in the column dimension, followed by the row dimension, int get_grid_coordinate_names(in int grid, out array names); Given a :term:`grid identifier`, -get an array of the names of the coordinates defined for the grid; -e.g., ``["x", "y", "z"]``. +get an array of the coordinate names defined for the grid; +e.g., ``["x", "y", "z"]``, +or ``["x1", "x2", "x3"]``, +or ``["lon", "lat", "hgt"]``, etc. The length of the array is given by :ref:`get_grid_rank`. **Implementation notes** @@ -309,7 +311,7 @@ get the locations of the grid :term:`nodes ` in a single coordinate direction. The length of the one-dimensional array of coordinates depends on the grid type -and the individual coordinate. +and the coordinate. (It will be a value from either :ref:`get_grid_shape` or :ref:`get_grid_size`.) See :ref:`model_grids` for more information. From f6b1b757206bcfaab6ba412ba68360d1a45ce263 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 16 Mar 2022 16:57:15 -0600 Subject: [PATCH 26/34] Add new function to get coordinate reference system --- bmi.sidl | 3 +++ 1 file changed, 3 insertions(+) diff --git a/bmi.sidl b/bmi.sidl index e1d125b..7a04d56 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -62,5 +62,8 @@ package csdms version 2.1-beta { int get_grid_face_edges(in int grid, in array face_edges); int get_grid_face_nodes(in int grid, in array face_nodes); int get_grid_nodes_per_face(in int grid, in array nodes_per_face); + + // Coordinate reference system information + int get_grid_crs(in int grid, out string name); } } From 3ee20c253043c74cc824d382761985c40888c9d0 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 16 Mar 2022 16:57:55 -0600 Subject: [PATCH 27/34] Add docs for get_grid_crs function --- docs/source/bmi.grid_funcs.rst | 30 ++++++++++++++++++++++++++++++ docs/source/bmi.spec.rst | 6 ++++++ 2 files changed, 36 insertions(+) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 62c007c..a852f7e 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -514,3 +514,33 @@ The number of edges per face is equal to the number of nodes per face. (nonzero) is returned. [:ref:`grid_funcs` | :ref:`basic_model_interface`] + + +.. _get_grid_crs: + +*get_grid_crs* +............... + +.. code-block:: java + + /* SIDL */ + int get_grid_crs(in int grid, out string crs); + +Given a :term:`grid identifier`, +get the `coordinate reference system`_ (CRS) of that grid as a string. + +Note that the BMI doesn't specify which standard to use +for the output of this function---that's left to the implementation. +We can, however, make recommendations; +e.g., OGC `Well-Known Text`_ (WKT), `PROJ`_, or `EPSG`_. + +**Implementation notes** + +* In C++, Java, and Python, the *crs* argument is omitted and the CRS + is returned from the function as a string. +* In C and Fortran, an integer status code indicating success (zero) or failure + (nonzero) is returned. +* A return string of ``""`` or ``"none"`` (but not the UDUNITS ``"1"``, which + could be taken as an `EPSG code`_) indicates no projection information. + +[:ref:`grid_funcs` | :ref:`basic_model_interface`] diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index 9c545c4..f148f95 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -133,6 +133,7 @@ grouped by functional category. :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. + :ref:`get_grid_crs` Get coordinate reference system (CRS) information for a grid. ================================ ========================================= .. include:: bmi.control_funcs.rst @@ -167,3 +168,8 @@ grouped by functional category. .. _time unit conventions: https://www.unidata.ucar.edu/software/udunits/udunits-current/udunits/udunits2-accepted.xml .. _primitive types: https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html .. _wrapper classes: https://docs.oracle.com/javase/tutorial/java/data/numberclasses.html +.. _coordinate reference system: https://www.earthdatascience.org/courses/earth-analytics/spatial-data-r/intro-to-coordinate-reference-systems/ +.. _Well-Known Text: https://www.ogc.org/standards/wkt-crs +.. _PROJ: https://proj.org/ +.. _EPSG: https://epsg.org/ +.. _EPSG code: https://spatialreference.org/ref/epsg/ From f47dab942d988430040b6fca8cc16c844fc75d8e Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 17 Mar 2022 11:12:32 -0600 Subject: [PATCH 28/34] Update a stray reference to get_grid_x --- docs/source/bmi.best_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/bmi.best_practices.rst b/docs/source/bmi.best_practices.rst index 5737310..5f14997 100644 --- a/docs/source/bmi.best_practices.rst +++ b/docs/source/bmi.best_practices.rst @@ -11,7 +11,7 @@ here are some tips to help when writing a BMI for a model. * All functions in the BMI must be implemented. For example, even if a model operates on a :ref:`uniform rectilinear ` - grid, a :ref:`get_grid_x` function has to be written. This function + grid, a :ref:`get_grid_coordinate` function has to be written. This function can be empty and simply return the ``BMI_FAILURE`` status code or raise a ``NotImplemented`` exception, depending on the language. From 686dbcd3dbd4a4d1709e0bae576f8509dafca8be Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 17 Mar 2022 12:07:10 -0600 Subject: [PATCH 29/34] Include example of suggested output from get_grid_crs --- docs/source/bmi.grid_funcs.rst | 41 ++++++++++++++++++++++++++++++++++ docs/source/bmi.spec.rst | 1 + 2 files changed, 42 insertions(+) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index a852f7e..b1410bd 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -534,6 +534,47 @@ for the output of this function---that's left to the implementation. We can, however, make recommendations; e.g., OGC `Well-Known Text`_ (WKT), `PROJ`_, or `EPSG`_. +As a small example, +if you have data in a projected CRS, +say, UTM zone 13 North with the WGS84 datum, +you could use `spatialreference.org`_ to find information about this projection +(`EPSG:32613 `_) +and return it from :ref:`get_grid_crs` +as (for example) a PROJ string: + +.. code-block:: + + +proj=utm +zone=13 +ellps=WGS84 +datum=WGS84 +units=m +no_defs + +or as WKT: + +.. code-block:: + + PROJCS["WGS 84 / UTM zone 13N", + GEOGCS["WGS 84", + DATUM["WGS_1984", + SPHEROID["WGS 84",6378137,298.257223563, + AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich",0, + AUTHORITY["EPSG","8901"]], + UNIT["degree",0.01745329251994328, + AUTHORITY["EPSG","9122"]], + AUTHORITY["EPSG","4326"]], + UNIT["metre",1, + AUTHORITY["EPSG","9001"]], + PROJECTION["Transverse_Mercator"], + PARAMETER["latitude_of_origin",0], + PARAMETER["central_meridian",-105], + PARAMETER["scale_factor",0.9996], + PARAMETER["false_easting",500000], + PARAMETER["false_northing",0], + AUTHORITY["EPSG","32613"], + AXIS["Easting",EAST], + AXIS["Northing",NORTH]] + +as you prefer. + **Implementation notes** * In C++, Java, and Python, the *crs* argument is omitted and the CRS diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index f148f95..b61992d 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -172,4 +172,5 @@ grouped by functional category. .. _Well-Known Text: https://www.ogc.org/standards/wkt-crs .. _PROJ: https://proj.org/ .. _EPSG: https://epsg.org/ +.. _spatialreference.org: https://www.spatialreference.org/ .. _EPSG code: https://spatialreference.org/ref/epsg/ From 649664bcf60ab956ce708edf9645266746d045bd Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 17 Mar 2022 14:32:39 -0600 Subject: [PATCH 30/34] Update get_grid_crs description --- docs/source/bmi.grid_funcs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index b1410bd..2a6a7ed 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -527,14 +527,14 @@ The number of edges per face is equal to the number of nodes per face. int get_grid_crs(in int grid, out string crs); Given a :term:`grid identifier`, -get the `coordinate reference system`_ (CRS) of that grid as a string. +get `coordinate reference system`_ (CRS) information for the grid as a string. Note that the BMI doesn't specify which standard to use for the output of this function---that's left to the implementation. We can, however, make recommendations; e.g., OGC `Well-Known Text`_ (WKT), `PROJ`_, or `EPSG`_. -As a small example, +A small example: if you have data in a projected CRS, say, UTM zone 13 North with the WGS84 datum, you could use `spatialreference.org`_ to find information about this projection From 05f98e9a0673c13579e990c2dfcbd42d7f5e2919 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 17 Mar 2022 14:41:07 -0600 Subject: [PATCH 31/34] Fix code block display on rtfd --- docs/source/bmi.grid_funcs.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 2a6a7ed..c19fc00 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -542,15 +542,15 @@ you could use `spatialreference.org`_ to find information about this projection and return it from :ref:`get_grid_crs` as (for example) a PROJ string: -.. code-block:: +.. code-block:: none +proj=utm +zone=13 +ellps=WGS84 +datum=WGS84 +units=m +no_defs or as WKT: -.. code-block:: +.. code-block:: none - PROJCS["WGS 84 / UTM zone 13N", + PROJCS["WGS 84 / UTM zone 13N", GEOGCS["WGS 84", DATUM["WGS_1984", SPHEROID["WGS 84",6378137,298.257223563, From f55ae9e6705d0826b2d541272fd4fd308ca55d8e Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 28 Mar 2022 15:30:24 -0600 Subject: [PATCH 32/34] Reintroduce get_grid_[xyz] with deprecation warning --- bmi.sidl | 3 + docs/source/bmi.grid_funcs.rst | 105 +++++++++++++++++++++++++++++++++ docs/source/bmi.spec.rst | 3 + 3 files changed, 111 insertions(+) diff --git a/bmi.sidl b/bmi.sidl index 7a04d56..cb4678c 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -50,6 +50,9 @@ package csdms version 2.1-beta { int get_grid_shape(in int grid, in array shape); int get_grid_spacing(in int grid, in array spacing); int get_grid_origin(in int grid, in array origin); + int get_grid_x(in int grid, in array x); // Deprecated, see documentation + int get_grid_y(in int grid, in array y); // Deprecated, see documentation + int get_grid_z(in int grid, in array z); // Deprecated, see documentation int get_grid_coordinate_names(in int grid, out array names); int get_grid_coordinate_units(in int grid, in string name, out string units); diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index c19fc00..f3f3bbe 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -220,6 +220,111 @@ the origin is given in the column dimension, followed by the row dimension, [:ref:`grid_funcs` | :ref:`basic_model_interface`] +.. _get_grid_x: + +*get_grid_x* +............ + +.. code-block:: java + + /* SIDL */ + int get_grid_x(in int grid, in array x); + +.. note:: + + This function is deprecated in BMI v2.1. + Please see :ref:`get_grid_coordinate` instead. + +Get the locations of the grid :term:`nodes ` in the first +coordinate direction. + +The length of the resulting one-dimensional array depends on the grid type. +(It will use a value from either :ref:`get_grid_shape` or :ref:`get_grid_size`.) +See :ref:`model_grids` for more information. + +**Implementation notes** + +* This function is used for describing :ref:`rectilinear `, + :ref:`structured quadrilateral `, + and all :ref:`unstructured ` grids. +* In Python, the *x* argument is a :term:`numpy ` array. +* In C++ and Java, this is a void 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_y: + +*get_grid_y* +............ + +.. code-block:: java + + /* SIDL */ + int get_grid_y(in int grid, in array y); + +.. note:: + + This function is deprecated in BMI v2.1. + Please see :ref:`get_grid_coordinate` instead. + +Get the locations of the grid :term:`nodes ` in the second +coordinate direction. + +The length of the resulting one-dimensional array depends on the grid type. +(It will use a value from either :ref:`get_grid_shape` or :ref:`get_grid_size`.) +See :ref:`model_grids` for more information. + +**Implementation notes** + +* This function is used for describing :ref:`rectilinear `, + :ref:`structured quadrilateral `, + and all :ref:`unstructured ` grids. +* In Python, the *y* argument is a :term:`numpy ` array. +* In C++ and Java, this is a void 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_z: + +*get_grid_z* +............ + +.. code-block:: java + + /* SIDL */ + int get_grid_z(in int grid, in array z); + +.. note:: + + This function is deprecated in BMI v2.1. + Please see :ref:`get_grid_coordinate` instead. + +Get the locations of the grid :term:`nodes ` in the third +coordinate direction. + +The length of the resulting one-dimensional array depends on the grid type. +(It will use a value from either :ref:`get_grid_shape` or :ref:`get_grid_size`.) +See :ref:`model_grids` for more information. + +**Implementation notes** + +* This function is used for describing :ref:`rectilinear `, + :ref:`structured quadrilateral `, + and all :ref:`unstructured ` grids. +* In Python, the *z* argument is a :term:`numpy ` array. +* In C++ and Java, this is a void 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_coordinate_names: *get_grid_coordinate_names* diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index b61992d..8242ba8 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -123,6 +123,9 @@ grouped by functional category. :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. (Deprecated, see :ref:`get_grid_coordinate`.) + :ref:`get_grid_y` Get the locations of a grid's nodes in dimension 2. (Deprecated, see :ref:`get_grid_coordinate`.) + :ref:`get_grid_z` Get the locations of a grid's nodes in dimension 3. (Deprecated, see :ref:`get_grid_coordinate`.) :ref:`get_grid_coordinate_names` Get the name of each node coordinate of a grid. :ref:`get_grid_coordinate_units` Get the units of each node coordinate of a grid. :ref:`get_grid_coordinate` Get the location of each node of a single grid coordinate. From 759f6e098f37eaafc15467d5e809ddf75812fe77 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 28 Mar 2022 15:54:51 -0600 Subject: [PATCH 33/34] Use :deprecated: directive instead of :note: --- docs/source/bmi.grid_funcs.rst | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index f3f3bbe..2639611 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -230,10 +230,8 @@ the origin is given in the column dimension, followed by the row dimension, /* SIDL */ int get_grid_x(in int grid, in array x); -.. note:: - - This function is deprecated in BMI v2.1. - Please see :ref:`get_grid_coordinate` instead. +.. deprecated:: 2.1 + Use :ref:`get_grid_coordinate` instead. Get the locations of the grid :term:`nodes ` in the first coordinate direction. @@ -265,10 +263,8 @@ See :ref:`model_grids` for more information. /* SIDL */ int get_grid_y(in int grid, in array y); -.. note:: - - This function is deprecated in BMI v2.1. - Please see :ref:`get_grid_coordinate` instead. +.. deprecated:: 2.1 + Use :ref:`get_grid_coordinate` instead. Get the locations of the grid :term:`nodes ` in the second coordinate direction. @@ -300,10 +296,8 @@ See :ref:`model_grids` for more information. /* SIDL */ int get_grid_z(in int grid, in array z); -.. note:: - - This function is deprecated in BMI v2.1. - Please see :ref:`get_grid_coordinate` instead. +.. deprecated:: 2.1 + Use :ref:`get_grid_coordinate` instead. Get the locations of the grid :term:`nodes ` in the third coordinate direction. From 57ceb8ec4c6c38e7f66bb50b1ee243abf40e33b5 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Mon, 28 Mar 2022 16:06:58 -0600 Subject: [PATCH 34/34] Use sphinx versionadded directive for new functions --- docs/source/bmi.grid_funcs.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 2639611..3385558 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -329,6 +329,8 @@ See :ref:`model_grids` for more information. /* SIDL */ int get_grid_coordinate_names(in int grid, out array names); +.. versionadded:: 2.1 + Given a :term:`grid identifier`, get an array of the coordinate names defined for the grid; e.g., ``["x", "y", "z"]``, @@ -350,7 +352,6 @@ The length of the array is given by :ref:`get_grid_rank`. function in a tuple, a standard container in the language. * Some grids may not have coordinates (e.g., grids of type ``scalar`` or ``none``). -* This function was introduced in BMI 2.1. [:ref:`grid_funcs` | :ref:`basic_model_interface`] @@ -365,6 +366,8 @@ The length of the array is given by :ref:`get_grid_rank`. /* SIDL */ int get_grid_coordinate_units(in int grid, in string name, out string units); +.. versionadded:: 2.1 + Given a :term:`grid identifier` and a coordinate name returned from :ref:`get_grid_coordinate_names`, get the units of the coordinate. @@ -389,7 +392,6 @@ full description of valid unit names and a list of supported units. units name is returned from the function. * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned. -* This function was introduced in BMI 2.1. [:ref:`grid_funcs` | :ref:`basic_model_interface`] @@ -404,6 +406,8 @@ full description of valid unit names and a list of supported units. /* SIDL */ int get_grid_coordinate(in int grid, in string name, in array coordinates); +.. versionadded:: 2.1 + Given a :term:`grid identifier` and a coordinate name returned from :ref:`get_grid_coordinate_names`, get the locations of the grid :term:`nodes ` in a single @@ -414,6 +418,9 @@ and the coordinate. (It will be a value from either :ref:`get_grid_shape` or :ref:`get_grid_size`.) See :ref:`model_grids` for more information. +This function replaces the deprecated *get_grid_x*, *get_grid_y*, and +*get_grid_z* functions. + **Implementation notes** * This function is used for describing :ref:`rectilinear `, @@ -423,8 +430,6 @@ See :ref:`model_grids` for more information. * In C++ and Java, this is a void function. * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned. -* This function was introduced in BMI 2.1. It replaces the deprecated - *get_grid_x*, *get_grid_y*, and *get_grid_z* functions. [:ref:`grid_funcs` | :ref:`basic_model_interface`] @@ -625,6 +630,8 @@ The number of edges per face is equal to the number of nodes per face. /* SIDL */ int get_grid_crs(in int grid, out string crs); +.. versionadded:: 2.1 + Given a :term:`grid identifier`, get `coordinate reference system`_ (CRS) information for the grid as a string.