diff --git a/bmi.sidl b/bmi.sidl index a9cf6bb..736c9ff 100644 --- a/bmi.sidl +++ b/bmi.sidl @@ -2,6 +2,7 @@ // The Basic Model Interface (BMI) // package csdms version 2.1-dev.0 { + interface bmi { // Model and BMI metadata @@ -39,29 +40,28 @@ package csdms version 2.1-dev.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 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); - - // 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_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); + 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); @@ -69,5 +69,8 @@ package csdms version 2.1-dev.0 { 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); } } 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. diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 341c5ef..3385558 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. @@ -230,6 +230,9 @@ the origin is given in the column dimension, followed by the row dimension, /* SIDL */ int get_grid_x(in int grid, in array x); +.. deprecated:: 2.1 + Use :ref:`get_grid_coordinate` instead. + Get the locations of the grid :term:`nodes ` in the first coordinate direction. @@ -260,6 +263,9 @@ See :ref:`model_grids` for more information. /* SIDL */ int get_grid_y(in int grid, in array y); +.. deprecated:: 2.1 + Use :ref:`get_grid_coordinate` instead. + Get the locations of the grid :term:`nodes ` in the second coordinate direction. @@ -290,6 +296,9 @@ See :ref:`model_grids` for more information. /* SIDL */ int get_grid_z(in int grid, in array z); +.. deprecated:: 2.1 + Use :ref:`get_grid_coordinate` instead. + Get the locations of the grid :term:`nodes ` in the third coordinate direction. @@ -310,6 +319,121 @@ See :ref:`model_grids` for more information. [: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); + +.. versionadded:: 2.1 + +Given a :term:`grid identifier`, +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** + +* 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); + +.. 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. + +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* +..................... + +.. code-block:: java + + /* 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 +coordinate direction. + +The length of the one-dimensional array of coordinates depends on the grid type +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 `, + :ref:`structured quadrilateral `, + and all :ref:`unstructured ` grids. +* 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. + +[:ref:`grid_funcs` | :ref:`basic_model_interface`] + + .. _get_grid_node_count: *get_grid_node_count* @@ -494,3 +618,76 @@ 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); + +.. versionadded:: 2.1 + +Given a :term:`grid identifier`, +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`_. + +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:: none + + +proj=utm +zone=13 +ellps=WGS84 +datum=WGS84 +units=m +no_defs + +or as WKT: + +.. code-block:: none + + 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 + 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 d52cea8..d7e0dc3 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -90,52 +90,56 @@ grouped by functional category. :align: center :widths: 30, 70 - ============================== ========================================= - Function Description - ============================== ========================================= - :ref:`get_bmi_version` Version of the BMI implemented. - :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:`get_bmi_version` Version of the BMI implemented. + :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. (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. + :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. + :ref:`get_grid_crs` Get coordinate reference system (CRS) information for a grid. + ================================ ========================================= .. include:: bmi.metadata_funcs.rst .. include:: bmi.control_funcs.rst @@ -170,3 +174,9 @@ 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/ +.. _spatialreference.org: https://www.spatialreference.org/ +.. _EPSG code: https://spatialreference.org/ref/epsg/ diff --git a/docs/source/conf.py b/docs/source/conf.py index b108bfc..03f0241 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 @@ -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. @@ -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 ---------------------------------------------- diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index b1cfc27..cb36e63 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. @@ -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: @@ -67,6 +71,8 @@ Uniform rectilinear grids use the following BMI functions: * :ref:`get_grid_shape` * :ref:`get_grid_spacing` * :ref:`get_grid_origin` +* :ref:`get_grid_coordinate_names` +* :ref:`get_grid_coordinate_units` .. _rectilinear: @@ -74,29 +80,39 @@ 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. -The :ref:`get_grid_y` function provides an array (whose length is the number of -*rows*, obtained from :ref:`get_grid_shape`) that gives the *y*-coordinate for each row. - -The :ref:`get_grid_x` function provides an array (whose length is the number of -*columns*, obtained from :ref:`get_grid_shape`) that gives the *x*-coordinate for each column. - Rectilinear grids use the following BMI functions: * :ref:`get_grid_rank` * :ref:`get_grid_size` * :ref:`get_grid_shape` -* :ref:`get_grid_x` -* :ref:`get_grid_y` -* :ref:`get_grid_z` +* :ref:`get_grid_coordinate_names` +* :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: @@ -104,29 +120,40 @@ 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, -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 -more general case, :ref:`get_grid_x` and :ref:`get_grid_y` are -repurposed to provide this information. + An example of a rank 2 structured quadrilateral grid. -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. +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, +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_x` -* :ref:`get_grid_y` -* :ref:`get_grid_z` +* :ref:`get_grid_coordinate_names` +* :ref:`get_grid_coordinate_units` +* :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: @@ -134,8 +161,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 @@ -143,25 +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_x` -* :ref:`get_grid_y` -* :ref:`get_grid_z` +* :ref:`get_grid_coordinate_names` +* :ref:`get_grid_coordinate_units` +* :ref:`get_grid_coordinate` * :ref:`get_grid_node_count` * :ref:`get_grid_edge_count` * :ref:`get_grid_face_count` @@ -171,7 +201,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. @@ -184,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.