From b08c822a9bc738edc4c594d48a0136229b9889b9 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 16 Jan 2020 11:58:39 -0700 Subject: [PATCH] Update documentation based on #58 This commit contains minor text updates; it doesn't include the reorg or updates to the CMF page suggested in #58; since those are bigger, I'll handle them separately. --- docs/source/bmi.getter_setter.rst | 8 ++++---- docs/source/bmi.grid_funcs.rst | 4 ++-- docs/source/bmi.implementation.rst | 5 +++++ docs/source/bmi.info_funcs.rst | 4 +++- docs/source/bmi.time_funcs.rst | 8 +++++--- docs/source/bmi.var_funcs.rst | 3 +++ docs/source/model_grids.rst | 8 ++++---- 7 files changed, 26 insertions(+), 14 deletions(-) diff --git a/docs/source/bmi.getter_setter.rst b/docs/source/bmi.getter_setter.rst index 9a832f8..311f04c 100644 --- a/docs/source/bmi.getter_setter.rst +++ b/docs/source/bmi.getter_setter.rst @@ -27,8 +27,8 @@ state variable can be changed or check the new data for validity. int get_value(in string name, in array<> dest); The `get_value` function takes a variable name and copies values into a -provided buffer. -The type and size of the buffer depend on the variable, +provided array parameter. +The type and size of the array parameter depend on the variable, and can be determined through :ref:`get_var_type`, :ref:`get_var_nbytes`, etc. Recall that arrays are always flattened in BMI, @@ -39,7 +39,7 @@ even if the model uses dimensional variables. * The *dest* argument must be defined and allocated before calling `get_value`. Whatever values it contains are overwritten in the call to `get_value`. -* In Python, the buffer is a :term:`numpy` array. +* In Python, the array parameter is a :term:`numpy` array. * In C++, `get_value` is a void function. * Depending on how a model is written, a variable may not be accessible until after the call to :ref:`initialize`. Likewise, the @@ -59,7 +59,7 @@ even if the model uses dimensional variables. The `get_value_ptr` function takes a variable name and returns a reference to a variable. -Unlike the buffer returned from :ref:`get_value`, +Unlike the array parameter returned from :ref:`get_value`, the reference always points to the current values of the variable, even if the model's state has changed. diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst index 885082a..98b8958 100644 --- a/docs/source/bmi.grid_funcs.rst +++ b/docs/source/bmi.grid_funcs.rst @@ -49,7 +49,6 @@ is given in the :ref:`model_grids` section. **Implementation notes** -* This function is needed for every :ref:`grid type `. * In C++ and Python, the *type* argument is omitted and the grid type name is returned from the function. @@ -66,7 +65,8 @@ is given in the :ref:`model_grids` section. /* SIDL */ int get_grid_rank(in int grid, out int rank); -Given a :term:`grid identifier`, get the :term:`rank` of that grid as an integer. +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. diff --git a/docs/source/bmi.implementation.rst b/docs/source/bmi.implementation.rst index 0a51fd4..adc799b 100644 --- a/docs/source/bmi.implementation.rst +++ b/docs/source/bmi.implementation.rst @@ -34,6 +34,11 @@ here are some tips to help when writing a BMI for a model. responsibility to ensure that array information is flattened/redimensionalized in the correct order. +* Recall that models can have mulitple grids. This can be particularly + useful for defining :term:`exchange items ` that + don't vary over the model domain; e.g., a diffusivity -- just define + the variable on a separate :ref:`scalar grid `. + * Avoid using global variables, if possible. This isn't strictly a BMI requirement, but if a model only uses local variables, its BMI will be self-contained. This may allow multiple instances of the model to diff --git a/docs/source/bmi.info_funcs.rst b/docs/source/bmi.info_funcs.rst index 5ceab74..ed50df5 100644 --- a/docs/source/bmi.info_funcs.rst +++ b/docs/source/bmi.info_funcs.rst @@ -43,6 +43,7 @@ but it should be unique to prevent conflicts with other components. The number of variables the model can use from other models implementing a BMI. +Also the number of variables that can be set with :ref:`set_value`. **Implementation notes** @@ -64,6 +65,7 @@ implementing a BMI. The number of variables the model can provide other models implementing a BMI. +Also the number of variables that can be retrieved with :ref:`get_value`. **Implementation notes** @@ -101,7 +103,7 @@ Standard Names do not have to be used within the model. function in a vector, a standard container in the language. * In Python, the argument is omitted and the names are returned from the function in a tuple, a standard container in the language. -* A model may have no input variables. +* A model might have no input variables. [:ref:`info_funcs` | :ref:`basic_model_interface`] diff --git a/docs/source/bmi.time_funcs.rst b/docs/source/bmi.time_funcs.rst index 9ce26a5..51d4d95 100644 --- a/docs/source/bmi.time_funcs.rst +++ b/docs/source/bmi.time_funcs.rst @@ -61,8 +61,9 @@ The end time of the model. **Implementation notes** -* If the model doesn't define an end time, a large number (e.g., - 1.0e6) is typically chosen. +* If the model doesn't define an end time, a large number (e.g., the + largest floating point number supported on a platform) is typically + chosen. * In C++ and Python, the argument is omitted and the time is returned from the function. @@ -87,7 +88,8 @@ It's recommended to use `time unit conventions`_ from Unidata's **Implementation notes** * Avoid using `years` as a unit, if possible, since a year is - difficult to define precisely. + difficult to define precisely. UDUNITS defines a year as 365.2422 + days or 31556926 seconds. * In C++ and Python, the argument is omitted and the units are returned from the function. diff --git a/docs/source/bmi.var_funcs.rst b/docs/source/bmi.var_funcs.rst index 6f42c2d..24c93b8 100644 --- a/docs/source/bmi.var_funcs.rst +++ b/docs/source/bmi.var_funcs.rst @@ -160,6 +160,9 @@ element the variable is defined. Valid return values are: * In C++ and Python, the *location* argument is omitted and the location is returned from the function. +* If the given variable is a scalar (i.e., defined on a :ref:`scalar + grid `), the return from this function is + ignored. [:ref:`var_funcs` | :ref:`basic_model_interface`] diff --git a/docs/source/model_grids.rst b/docs/source/model_grids.rst index c4d422e..53045b5 100644 --- a/docs/source/model_grids.rst +++ b/docs/source/model_grids.rst @@ -33,10 +33,10 @@ its length would be listed first. .. note:: - The grid shape is the number of :term:`nodes ` in the - coordinate directions, not the number of cells or - elements. It is possible for grid values to be - associated with the nodes or with the cells. + The grid shape is the number of rows and columns of :term:`nodes + `, as opposed to other types of element (such as cells or + faces). It is possible for grid values to be associated with the + nodes or with the cells. .. _uniform_rectilinear: