diff --git a/docs/source/bmi.best_practices.md b/docs/source/bmi.best_practices.md index f1b6437..75e9ddd 100644 --- a/docs/source/bmi.best_practices.md +++ b/docs/source/bmi.best_practices.md @@ -9,11 +9,11 @@ In no particular order, 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 + model operates on a {ref}`uniform rectilinear ` + grid, a {ref}`get-grid-x` 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. -- The {ref}`BMI functions ` listed in the +- The {ref}`BMI functions ` listed in the documentation are the minimum required. Optional functions that act as helpers can be added to a model's BMI. For example, an `update_frac` function that updates a model's state by a fractional @@ -41,7 +41,7 @@ here are some tips to help when writing a BMI for a model. - Recall that models can have multiple 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 `. + 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.control_funcs.md b/docs/source/bmi.control_funcs.md index 62db207..b8f4a30 100644 --- a/docs/source/bmi.control_funcs.md +++ b/docs/source/bmi.control_funcs.md @@ -78,7 +78,7 @@ formatted. The `update` function advances the model by a single time step. This is the model's own internal time step (as returned by the BMI -{ref}`get_time_step` function), not the time step +{ref}`get-time-step` function), not the time step of a controlling application. This function should perform all tasks that take place during one pass through the model's time loop. It does not contain the time @@ -121,7 +121,7 @@ If the model permits, the *time* argument can be a non-integral multiple of time steps, and even negative. Once called, the value returned -by the BMI {ref}`get_current_time` function must return the provided time +by the BMI {ref}`get-current-time` function must return the provided time to reflect that the model was updated to the requested time. **Implementation notes** diff --git a/docs/source/bmi.getter_setter.md b/docs/source/bmi.getter_setter.md index 91a34fc..fc5ddf6 100644 --- a/docs/source/bmi.getter_setter.md +++ b/docs/source/bmi.getter_setter.md @@ -4,7 +4,7 @@ These functions are used to access and modify the variables that a model exposes through its BMI -(see {ref}`get_input_var_names` and {ref}`get_output_var_names`). +(see {ref}`get-input-var-names` and {ref}`get-output-var-names`). A *getter* is a function called to get a variable from a model's *state*. A model's state variables typically change with each time step, @@ -41,7 +41,7 @@ The `get_value` function takes a variable name and copies values into a provided array parameter. The type and size of the array parameter depend on the variable, and can be determined through -{ref}`get_var_type`, {ref}`get_var_nbytes`, etc. +{ref}`get-var-type`, {ref}`get-var-nbytes`, etc. Recall that arrays are always flattened in BMI, even if the model uses dimensional variables. @@ -85,7 +85,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 array parameter 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. @@ -131,7 +131,7 @@ The values are returned through the *dest* argument. **Implementation notes** -All the notes from {ref}`get_value` apply. +All the notes from {ref}`get-value` apply. Additionally, - Both *dest* and *inds* are flattened arrays. @@ -166,7 +166,7 @@ and copies those values into the model's internal array of values, overwriting the current contents. The type and size of *src* must match the model's internal array, and can be determined through -{ref}`get_var_type`, {ref}`get_var_nbytes`, etc. +{ref}`get-var-type`, {ref}`get-var-nbytes`, etc. Recall that arrays are always flattened in BMI, even if the model uses dimensional variables. @@ -213,7 +213,7 @@ in the *inds* argument. **Implementation notes** -All the notes from {ref}`set_value` apply. +All the notes from {ref}`set-value` apply. Additionally, - Both *src* and *inds* are flattened arrays. diff --git a/docs/source/bmi.getting_started.md b/docs/source/bmi.getting_started.md index 9013b6e..a149274 100644 --- a/docs/source/bmi.getting_started.md +++ b/docs/source/bmi.getting_started.md @@ -6,13 +6,13 @@ If you want to add a Basic Model Interface (BMI) to your own model, here are some tips on getting started. 1\. Take a look at the list of BMI -{ref}`control functions and their descriptions ` +{ref}`control functions and their descriptions ` to get an idea of what these functions are meant to do and how they provide a standard set of controls for your model. 2\. On the theory that it's often easier to start with an example and modify it, we recommend starting with a copy of -the {ref}`BMI example code`---look for the version +the {ref}`BMI example code`---look for the version written in the language of your model---to use as a template. Each link points to a GitHub repository that includes an example model called "heat", and a corresponding BMI in a file called @@ -35,15 +35,15 @@ whereas codes that are more monolithic tend to require a lot more refactoring (but that is probably worthwhile anyway for the sake of the quality and sustainability of the code!). Each case is a bit different. -Be sure to check out our {ref}`BMI best practices ` document +Be sure to check out our {ref}`BMI best practices ` document for tips. We encourage you to contact us with questions by posting an issue on the [CSDMS Help Desk]. 4\. Test it out. Try writing a program or script that initializes your model with a simple test case using the {ref}`initialize` function, -runs it with the {ref}`update` or {ref}`update_until` functions, -and exchanges data using {ref}`get_value` and {ref}`set_value`. +runs it with the {ref}`update` or {ref}`update-until` functions, +and exchanges data using {ref}`get-value` and {ref}`set-value`. Run a test to verify that you get the same output from your BMI'd model that you got from it prior to BMI'ing. (Note: we recommend writing a {term}`unit test` for each of your diff --git a/docs/source/bmi.grid_funcs.md b/docs/source/bmi.grid_funcs.md index 4329b86..c9f7085 100644 --- a/docs/source/bmi.grid_funcs.md +++ b/docs/source/bmi.grid_funcs.md @@ -2,11 +2,11 @@ # Model grid functions -The functions in this section describe {ref}`model grids `. +The functions in this section describe {ref}`model grids `. In the BMI, every {term}`exchange item` is defined on a grid, and is referenced by a {term}`grid identifier` -returned from the {ref}`get_var_grid` function. +returned from the {ref}`get-var-grid` function. This identifier is a required input to the functions listed below. A model can have multiple grids. @@ -19,7 +19,7 @@ on which a constant thermal diffusivity is defined. Not all grid functions are used by each type of grid. However, all BMI grid functions must be implemented. -(See {ref}`model_grids` and {ref}`best_practices`.) +(See {ref}`model-grids` and {ref}`best-practices`.) (get-grid-type)= @@ -56,7 +56,7 @@ Valid grid types are: - `uniform_rectilinear` A detailed description of the grid types supported in BMI -is given in the {ref}`model_grids` section. +is given in the {ref}`model-grids` section. **Implementation notes** @@ -93,13 +93,13 @@ 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*. +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 {ref}`get-grid-x`, {ref}`get-grid-y`, etc. are implemented. **Implementation notes** -- This function is needed for every {ref}`grid type `. +- This function is needed for every {ref}`grid type `. - In C++, Java, and Python, the *rank* argument is omitted and the grid rank is returned from the function. - In C and Fortran, an integer status code indicating success (zero) or failure @@ -133,13 +133,13 @@ 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` -for {ref}`unstructured ` and -{ref}`structured quad ` grids. +length of arrays returned by {ref}`get-grid-x` and {ref}`get-grid-y` +for {ref}`unstructured ` and +{ref}`structured quad ` grids. **Implementation notes** -- This function is needed for every {ref}`grid type `. +- This function is needed for every {ref}`grid type `. - In C++, Java, and Python, the *size* argument is omitted and the grid size is returned from the function. - In C and Fortran, an integer status code indicating success (zero) or failure @@ -176,7 +176,7 @@ For example, consider a two-dimensional rectilinear grid with four columns (`nx = 4`) and three rows (`ny = 3`). -The {ref}`get_grid_shape` function would return a shape +The {ref}`get-grid-shape` function would return a shape of `[ny, nx]`, or `[3,4]`. If there were a third dimension, the length of the *z*-dimension, `nz`, would be listed first. @@ -189,7 +189,7 @@ the cells. **Implementation notes** - This function is used for describing all {ref}`structured grids - `. + `. - In Python, the *shape* 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 @@ -222,9 +222,9 @@ the cells. Get the distance between the {term}`nodes ` of the model grid. -The {ref}`get_grid_spacing` function provides the width of each cell in -the number of dimensions as returned by {ref}`get_grid_rank`. -As with {ref}`get_grid_shape`, +The {ref}`get-grid-spacing` function provides the width of each cell in +the number of dimensions as returned by {ref}`get-grid-rank`. +As with {ref}`get-grid-shape`, the spacing is given in "ij" indexing\* order; e.g., for a two-dimensional grid, the spacing between rows is followed by spacing between columns, `[dy, dx]`. @@ -232,7 +232,7 @@ the spacing between rows is followed by spacing between columns, `[dy, dx]`. **Implementation notes** - This function is used for describing {ref}`uniform rectilinear - ` grids. + ` grids. - In Python, the *spacing* 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 @@ -266,8 +266,8 @@ the spacing between rows is followed by spacing between columns, `[dy, dx]`. Get the coordinates of the lower-left corner of the model grid. The *origin* parameter is a one-dimensional array of the size -returned by {ref}`get_grid_rank`. -As with {ref}`get_grid_shape`, +returned by {ref}`get-grid-rank`. +As with {ref}`get-grid-shape`, the origin is given in "ij" indexing\* order; e.g., for a two-dimensional grid, the origin is given in the column dimension, followed by the row dimension, @@ -276,7 +276,7 @@ the origin is given in the column dimension, followed by the row dimension, **Implementation notes** - This function is used for describing {ref}`uniform rectilinear - ` grids. + ` grids. - In Python, the *origin* 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 @@ -309,14 +309,14 @@ 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. +(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. + {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 @@ -349,14 +349,14 @@ 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. +(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. + {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 @@ -389,14 +389,14 @@ 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. +(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. + {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 @@ -430,7 +430,7 @@ Get the number of {term}`nodes ` in the grid. **Implementation notes** - This function is used for describing {ref}`unstructured - ` grids. + ` grids. - In C++, Java, and Python, the *count* argument is omitted and the node count is returned from the function. - In C and Fortran, an integer status code indicating success (zero) or failure @@ -464,7 +464,7 @@ Get the number of {term}`edges ` in the grid. **Implementation notes** - This function is used for describing {ref}`unstructured - ` grids. + ` grids. - In C++, Java, and Python, the *count* argument is omitted and the edge count is returned from the function. - In C and Fortran, an integer status code indicating success (zero) or failure @@ -498,7 +498,7 @@ Get the number of {term}`faces ` in the grid. **Implementation notes** - This function is used for describing {ref}`unstructured - ` grids. + ` grids. - In C++, Java, and Python, the *count* argument is omitted and the face count is returned from the function. - In C and Fortran, an integer status code indicating success (zero) or failure @@ -533,12 +533,12 @@ Get the edge-node connectivity. For each edge, connectivity is given as node at edge tail, followed by node at edge head. The total length of the array is -2 * {ref}`get_grid_edge_count`. +2 * {ref}`get-grid-edge-count`. **Implementation notes** - This function is used for describing {ref}`unstructured - ` grids. + ` grids. - In Python, the *edge_nodes* 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 @@ -572,12 +572,12 @@ node at edge head. The total length of the array is Get the face-edge connectivity. The length of the array returned is the sum of the values of -{ref}`get_grid_nodes_per_face`. +{ref}`get-grid-nodes-per-face`. **Implementation notes** - This function is used for describing {ref}`unstructured - ` grids. + ` grids. - In Python, the *face_edges* 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 @@ -613,15 +613,15 @@ Get the face-node connectivity. For each face, the nodes (listed in a counter-clockwise direction) that form the boundary of the face. For a grid of quadrilaterals, -the total length of the array is 4 * {ref}`get_grid_face_count`. +the total length of the array is 4 * {ref}`get-grid-face-count`. More generally, the length of the array is the sum of the values of -{ref}`get_grid_nodes_per_face`. +{ref}`get-grid-nodes-per-face`. **Implementation notes** - This function is used for describing {ref}`unstructured - ` grids. + ` grids. - In Python, the *face_nodes* 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 @@ -654,13 +654,13 @@ the length of the array is the sum of the values of Get the number of nodes for each face. -The returned array has a length of {ref}`get_grid_face_count`. +The returned array has a length of {ref}`get-grid-face-count`. The number of edges per face is equal to the number of nodes per face. **Implementation notes** - This function is used for describing {ref}`unstructured - ` grids. + ` grids. - In Python, the *nodes_per_face* 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 diff --git a/docs/source/bmi.info_funcs.md b/docs/source/bmi.info_funcs.md index df2f6bb..d6a6ead 100644 --- a/docs/source/bmi.info_funcs.md +++ b/docs/source/bmi.info_funcs.md @@ -66,7 +66,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`. +Also the number of variables that can be set with {ref}`set-value`. **Implementation notes** @@ -100,7 +100,7 @@ Also the number of variables that can be set with {ref}`set_value`. 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`. +Also the number of variables that can be retrieved with {ref}`get-value`. **Implementation notes** @@ -134,7 +134,7 @@ Also the number of variables that can be retrieved with {ref}`get_value`. Gets an array of names for the variables the model can use from other models implementing a BMI. -The length of the array is given by {ref}`get_input_item_count`. +The length of the array is given by {ref}`get-input-item-count`. The names are preferably in the form of CSDMS {term}`Standard Names`. Standard Names enable a modeling framework to determine whether an input variable in one model is equivalent to, or compatible with, @@ -180,7 +180,7 @@ Standard Names do not have to be used within the model. Gets an array of names for the variables the model can provide to other models implementing a BMI. -The length of the array is given by {ref}`get_output_item_count`. +The length of the array is given by {ref}`get-output-item-count`. The names are preferably in the form of CSDMS {term}`Standard Names`. Standard Names enable a modeling framework to determine whether an input variable in one model is equivalent to, or compatible with, diff --git a/docs/source/bmi.spec.md b/docs/source/bmi.spec.md index b2d2642..fe1ca43 100644 --- a/docs/source/bmi.spec.md +++ b/docs/source/bmi.spec.md @@ -31,47 +31,47 @@ grouped by functional category. ============================== ========================================= Function Description ============================== ========================================= - :ref:`get_bmi_version` Version of the BMI implemented. + :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:`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. + :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. ============================== ========================================= ``` diff --git a/docs/source/bmi.time_funcs.md b/docs/source/bmi.time_funcs.md index c6e502d..218c2fc 100644 --- a/docs/source/bmi.time_funcs.md +++ b/docs/source/bmi.time_funcs.md @@ -129,7 +129,7 @@ The end time of the model. ``` Get the units of time as reported by the model's BMI (through -{ref}`get_current_time`, {ref}`get_end_time`, etc.). +{ref}`get-current-time`, {ref}`get-end-time`, etc.). It's recommended to use [time unit conventions] from Unidata's [UDUNITS] package; e.g., `"s"`, `"min"`, `"h"`, `"d"`. diff --git a/docs/source/bmi.var_funcs.md b/docs/source/bmi.var_funcs.md index 682c3f8..fa9de25 100644 --- a/docs/source/bmi.var_funcs.md +++ b/docs/source/bmi.var_funcs.md @@ -5,7 +5,7 @@ These BMI functions provide information about a particular input or output variable. They must accommodate any variable returned from the -{ref}`get_input_var_names` or {ref}`get_output_var_names` functions -- +{ref}`get-input-var-names` or {ref}`get-output-var-names` functions -- the variable name is used as an argument in each function. Based on the information returned, type or unit conversions can be applied when necessary. @@ -35,10 +35,10 @@ type or unit conversions can be applied when necessary. ``` Each input and output variable is defined on a grid. -(Available grid types are listed in the {ref}`grid_funcs` section.) +(Available grid types are listed in the {ref}`grid-funcs` section.) The `get_var_grid` function provides the identifier (an integer) for this grid. The identifier can be passed to the BMI -{ref}`grid information ` functions +{ref}`grid information ` functions to get the details of a particular grid; e.g., *x*- and *y*-coordinates, size, type, etc. A model can have one or more grids. @@ -241,7 +241,7 @@ element the variable is defined. Valid return values are: - In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned. - If the given variable is a scalar (i.e., defined on a {ref}`scalar - grid `), the location from this function is ignored. + grid `), the location from this function is ignored. ```{eval-rst} .. include:: links.rst diff --git a/docs/source/governance.md b/docs/source/governance.md index 2f1bb09..5d5f022 100644 --- a/docs/source/governance.md +++ b/docs/source/governance.md @@ -324,7 +324,7 @@ document, as per the [CC-0 public domain dedication / license]. [community surface dynamics modeling system]: https://csdms.colorado.edu [consensus-based democracy]: https://producingoss.com/en/producingoss.html#consensus-democracy [contributing]: https://github.com/csdms/bmi/blob/master/CONTRIBUTING.rst -[institutional partners]: ./partners.html +[institutional partners]: partners [numpy governance document]: https://numpy.org/doc/stable/dev/governance/index.html [social and political infrastructure]: https://producingoss.com/en/producingoss.html#social-infrastructure -[steering council]: ./council.html +[steering council]: council diff --git a/docs/source/index.md b/docs/source/index.md index c428e06..26a66a0 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -41,30 +41,27 @@ in which the BMI is implemented. (specs-and-examples)= -```{eval-rst} -.. table:: **Table 1:** BMI languages. - :align: center - :widths: 20, 25, 25, 30 - - ======== ============= ============== ====================== - Language Specification Repository Example - ======== ============= ============== ====================== - C `bmi.h`_ `bmi-c`_ `bmi-example-c`_ - C++ `bmi.hxx`_ `bmi-cxx`_ `bmi-example-cxx`_ - Fortran `bmi.f90`_ `bmi-fortran`_ `bmi-example-fortran`_ - Java `bmi.java`_ `bmi-java`_ `bmi-example-java`_ - Python `bmi.py`_ `bmi-python`_ `bmi-example-python`_ - ======== ============= ============== ====================== -``` +:::{table} **Table 1:** BMI languages. +:align: center +:widths: 20, 25, 25, 30 + +| Language Specification Repository Example +| -------- | ------------- | ---------- | ------- | +| C `bmi.h`_ `bmi-c`_ `bmi-example-c`_ +| C++ `bmi.hxx`_ `bmi-cxx`_ `bmi-example-cxx`_ +| Fortran `bmi.f90`_ `bmi-fortran`_ `bmi-example-fortran`_ +| Java `bmi.java`_ `bmi-java`_ `bmi-example-java`_ +| Python `bmi.py`_ `bmi-python`_ `bmi-example-python`_ +| -------- | ------------- | ---------- | ------- | +::: BMI is a community standard. Table 2 lists community-contributed language specifications and examples for two languages, Javascript and Julia. -```{eval-rst} -.. table:: **Table 2:** Community-contributed BMI languages. - :align: center - :widths: 20, 25, 25, 30 +:::{table} **Table 2:** Community-contributed BMI languages. +:align: center +:widths: 20, 25, 25, 30 ========== ============= ============ ===================== Language Specification Repository Example @@ -72,14 +69,14 @@ for two languages, Javascript and Julia. Javascript `bmi.js`_ `bmi-js`_ `bmi-example-js`_ Julia `bmi.jl`_ `bmi-julia`_ `bmi-example-julia`_ ========== ============= ============ ===================== -``` +::: Along with the examples, two documents may be particularly helpful when writing a BMI: -- {ref}`Getting Started Guide ` --- a place to start +- {ref}`Getting Started Guide ` --- a place to start if you haven't written a BMI before -- {ref}`BMI Best Practices ` --- our collected wisdom on +- {ref}`BMI Best Practices ` --- our collected wisdom on implementing a BMI A complete description of the functions that make up the BMI is given next. diff --git a/docs/source/model_grids.md b/docs/source/model_grids.md index e7688f0..6f866fe 100644 --- a/docs/source/model_grids.md +++ b/docs/source/model_grids.md @@ -5,8 +5,8 @@ The Basic Model Interface (BMI) supports several different {term}`grid` types, described below. Depending on the grid type -(as returned from the {ref}`get_grid_type` function), -a model will implement a different set of {ref}`grid functions `. +(as returned from the {ref}`get-grid-type` function), +a model will implement a different set of {ref}`grid functions `. (structured-grids)= @@ -24,7 +24,7 @@ dimensional information is ordered with "ij" indexing (as opposed to "xy"). For example, for the uniform rectilinear grid shown below, -the {ref}`get_grid_shape` function would return the array `[4, 5]`. +the {ref}`get-grid-shape` function would return the array `[4, 5]`. If there was a third dimension, its length would be listed first. @@ -58,11 +58,11 @@ and the location of the corner of the grid. Uniform rectilinear grids use the following BMI functions: -- {ref}`get_grid_rank` -- {ref}`get_grid_size` -- {ref}`get_grid_shape` -- {ref}`get_grid_spacing` -- {ref}`get_grid_origin` +- {ref}`get-grid-rank` +- {ref}`get-grid-size` +- {ref}`get-grid-shape` +- {ref}`get-grid-spacing` +- {ref}`get-grid-origin` (rectilinear)= @@ -78,20 +78,20 @@ 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-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. +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-rank` +- {ref}`get-grid-size` +- {ref}`get-grid-shape` +- {ref}`get-grid-x` +- {ref}`get-grid-y` +- {ref}`get-grid-z` (structured-quad)= @@ -104,23 +104,23 @@ Rectilinear grids use the following BMI functions: 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 +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-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 {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. 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-rank` +- {ref}`get-grid-size` +- {ref}`get-grid-shape` +- {ref}`get-grid-x` +- {ref}`get-grid-y` +- {ref}`get-grid-z` (unstructured-grids)= @@ -150,23 +150,23 @@ 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_node_count` -- {ref}`get_grid_edge_count` -- {ref}`get_grid_face_count` -- {ref}`get_grid_edge_nodes` -- {ref}`get_grid_face_edges` -- {ref}`get_grid_face_nodes` -- {ref}`get_grid_nodes_per_face` +- {ref}`get-grid-rank` +- {ref}`get-grid-x` +- {ref}`get-grid-y` +- {ref}`get-grid-z` +- {ref}`get-grid-node-count` +- {ref}`get-grid-edge-count` +- {ref}`get-grid-face-count` +- {ref}`get-grid-edge-nodes` +- {ref}`get-grid-face-edges` +- {ref}`get-grid-face-nodes` +- {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. The grid is two-dimensional, -so the {ref}`get_grid_rank` function returns 2. +so the {ref}`get-grid-rank` function returns 2. The {term}`nodes ` of the grid, labeled in the figure in red, are given by coordinates @@ -176,8 +176,8 @@ 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 will be the outputs of the {ref}`get-grid-x` and +{ref}`get-grid-y` functions, respectively. The nodes are indexed, so node 0 is at *(x, y) = (0, 3)*, node 1 is at *(x, y) = (1, 1)*, etc. @@ -187,8 +187,8 @@ the grid {term}`edges ` and {term}`faces ` are indexed. In the figure, the edges are depicted in blue italics, while the faces are boldfaced. -The outputs from {ref}`get_grid_node_count`, {ref}`get_grid_edge_count`, -and {ref}`get_grid_face_count` are: +The outputs from {ref}`get-grid-node-count`, {ref}`get-grid-edge-count`, +and {ref}`get-grid-face-count` are: ```python node_count = 6 @@ -198,7 +198,7 @@ face_count = 3 Note that the number of nodes is the length of the *x* and *y* vectors above. -The {ref}`get_grid_nodes_per_face` function returns a vector +The {ref}`get-grid-nodes-per-face` function returns a vector of length `face_count`. The first two faces are quadrilaterals, while the third is a triangle, so @@ -207,7 +207,7 @@ while the third is a triangle, so nodes_per_face = [4, 4, 3] ``` -The {ref}`get_grid_edge_nodes` function returns a vector +The {ref}`get-grid-edge-nodes` function returns a vector of length `2*edge_count`. The vector is formed, pairwise, by the node index at the tail of the edge, @@ -218,7 +218,7 @@ For the grid in the figure, this is edge_nodes = [0, 1, 1, 2, 2, 3, 3, 0, 1, 4, 4, 5, 5, 2, 5, 3] ``` -The {ref}`get_grid_face_edges` function returns a vector +The {ref}`get-grid-face-edges` function returns a vector of length `sum(nodes_per_face)`. The vector is formed from the edge indices as displayed in the figure: @@ -226,7 +226,7 @@ The vector is formed from the edge indices as displayed in the figure: face_edges = [0, 1, 2, 3, 4, 5, 6, 1, 6, 7, 2] ``` -Likewise, the {ref}`get_grid_face_nodes` function returns a vector +Likewise, the {ref}`get-grid-face-nodes` function returns a vector of length `sum(nodes_per_face)`. The vector is formed from the node indices as displayed in the figure: