Merge pull request #1239 from LLNL/feature/whitlock/blueprint_doc_imp…

…rovements

Improve Blueprint docs for strided structured topology.

src/docs/sphinx/blueprint_mesh.rst

@@ -240,6 +240,105 @@ The mesh blueprint protocol accepts four implicit ways to define a topology on a
   * topologies/topo/elements/dims/{i,j,k}
   * topologies/topo/elements/origin/{i0,j0,k0} (optional, default = {0,0,0})
 
+  Additional optional fields for *"strided"* structured:
+
+  * topologies/topo/elements/dims/offsets: [0,0,0] (integer list 2-3 elements)
+  * topologies/topo/elements/dims/strides: [i,j,k] (optional list 2-3 elements)
+
+
+
+Structured Topology
+********************
+
+A structured topology creates an implicitly defined topology consisting of lines, quads, or hexs,
+depending on the dimension of the mesh as given by the ``dims/i``, ``dims/j``, ``dims/k`` values.
+If the topology is part of a larger dataset containing multiple domains, ``origin`` values may be
+provided to indicate the domain's position in the global indexing.
+
+2D example:
+
+  .. code:: yaml
+
+    coordsets:
+      coords:
+        type: "explicit"
+        values:
+          x: [0., 1., 2., 3.,
+              0.1, 1.1, 2.1., 3.1,
+              0.2, 1.2, 2.2, 3.2]
+          y: [0., 0.1, 0., 0.1,
+              1.1, 1., 1.1, 1.,
+              2., 2.2, 2., 2.2]
+    topologies: 
+      mesh: 
+        type: "structured"
+        coordset: "coords"
+        elements:
+          dims:
+            i: 3
+            j: 2
+
+
+Strided Structured Topology
+****************************
+
+The elements of a structured topology will by default span all coordinates in the supplied coordset.
+The structured topology also supports selecting a sub-block of IJK coordinates, to create a smaller
+mesh without requiring the coordset's size to be adjusted. This facilitates using existing data
+without having to reallocate and rearrange. This use case comes up when a host code's
+data contains extra layers of elements around the mesh, which it may not be appropriate to include
+in the Blueprint dataset. For example, the surrounding nodes might not be initialized with sensible
+coordinate values.
+
+Selecting a subset of the coordset is done by adding the ``elements/dims/offsets``
+and ``elements/dims/strides`` vectors to the topology. These represent offset and stride into the supplied
+coordset data arrays. Both vectors contain *ndims* integers where ndims is the number of dimensions
+of the topology. Viewing the coordset data as a multi-dimensional array of size i,j(,k), the offset
+represents i,j(,k) indices where the selected data begin. The strides supply the number of array
+elements to add to the current element to move one element in I, J, or K.
+
+The following example shows how to make a strided structured 3x2 element topology using a coordset
+containing 7x7 nodes.
+
+  .. code:: yaml
+
+    coordsets:
+      coords:
+        type: "explicit"
+        values:
+          x: [-10.0, -6.6, -3.3, 0.0, 3.3, 6.6, 10.0,
+              -10.0, -6.6, -3.3, 0.0, 3.3, 6.6, 10.0,
+              -10.0, -6.6, -3.3, 0.0, 3.3, 6.6, 10.0,
+              -10.0, -6.6, -3.3, 0.0, 3.3, 6.6, 10.0,
+              -10.0, -6.6, -3.3, 0.0, 3.3, 6.6, 10.0,
+              -10.0, -6.6, -3.3, 0.0, 3.3, 6.6, 10.0]
+          y: [-10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0,
+               -6.0, -6.0, -6.0,  -6.0,  -6.0,  -6.0, -6.0,
+               -2.0, -2.0, -2.0, -2.0, -2.0, -2.0, -2.0,
+                2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0,
+                6.0, 6.0, 6.0, 6.0, 6.0, 6.0, 6.0,
+                10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0]
+    topologies: 
+      mesh: 
+        type: "structured"
+        coordset: "coords"
+        elements: 
+          dims: 
+            i: 3
+            j: 2
+            # Select a subset of the coordinates
+            offsets: [2, 2]  # Start at x[2][2],y[2][2]
+            strides: [1, 7]  # Add 1 to move right 1
+                             # Add 7 to move up 1
+
+.. figure:: strided_structured_2d.png
+    :width: 600px
+    :align: center
+
+    Plot of strided structured topology with coordset points shown.
+
+When using the "strided" form of the structured topology, it may also be necessary to provide the
+*offset*, and *stride* values to select a subset of data from fields.
 
 
 Explicit (Unstructured) Topology
@@ -479,7 +578,23 @@ To conform to protocol, each ``matsets`` child of this type must be an *Object*
    * matsets/matset/material_ids: (integer array)
    * matsets/matset/volume_fractions: (floating-point array)
 
-The following diagram illustrates a simple **uni-buffer** material set example:
+As an **o2mrelation**, the following values must also be present:
+
+   * matsets/matset/sizes: (integer array)
+   * matsets/matset/offsets: (integer array)
+   * matsets/matset/indices: (integer array)
+
+.. note::
+  It can help to think of how the data are traversed when understanding this structure. An
+  element's size and offset can be obtained by indexing the ``sizes`` and ``offsets`` with the
+  element id. These are used to look up a tuple of data from ``indices``. The resulting
+  indices for the element are array indices into the ``material_ids`` and ``volume_fractions``
+  arrays for the current element.
+
+The following diagram illustrates a simple **uni-buffer** material set example.
+Note that the ``material_ids`` and ``volume_fractions`` data arrays in this example contain
+some elements that are not referenced by the ``indices`` array. This shows how the format
+can selectively pull from data arrays that may contain other information.
 
   .. code:: yaml
 
@@ -505,6 +620,8 @@ The following diagram illustrates a simple **uni-buffer** material set example:
           indices: [1, 4, 6, 3, 2]
 
 
+
+
 Multi-Buffer Material Sets
 *********************************
 
@@ -641,6 +758,8 @@ Thus, to conform to protocol, each entry under the ``fields`` section must be an
    * fields/field/volume_dependent: "true" | "false"
    * fields/field/topology: "topo"
    * fields/field/values: (mcarray)
+   * fields/field/offsets: (integer array) (optional - for strided structured topology)
+   * fields/field/strides: (integer array) (optional - for strided structured topology)
 
  * Material-Dependent Fields:
 
@@ -660,16 +779,44 @@ Thus, to conform to protocol, each entry under the ``fields`` section must be an
    * fields/field/matset: "matset"
    * fields/field/matset_values: (mcarray)
 
-
-
-
 Topology Association for Field Values
 ======================================
 
 For implicit topologies, the field values are associated with the topology by fast varying logical dimensions starting with ``i``, then ``j``, then ``k``.
 
 For explicit topologies, the field values are associated with the topology by assuming the order of the field values matches the order the elements are defined in the topology.
 
+Strided Structured Fields
+==========================
+
+When creating structured topologies for mesh data that is surrounded by unwanted extra layers, a
+structured topology can provide ``offsets`` and ``strides`` to indicate that Blueprint should ignore
+the extra layers of data. This lets the topology be represented without having to rearrange any of
+the coordset data. The same issue arises for fields so Blueprint allows fields to supply ``offsets``
+and ``strides`` to select a subset of a larger array.
+
+The following example is for a mesh that supplied 7x7 actual nodes in the coordset but only defined
+a 3x2 element, or 4x3 node topology defined over a subset of the nodes. The ``offsets`` and ``strides``
+values in the field are used to select a subset of the field values, which in reality would be supplied
+in-memory from a host code's data structures. For readability, the values selected using 
+`offsets`` and ``strides`` are non-zero while unselected values are zero.
+
+
+  .. code:: yaml
+
+    fields:
+      vert_vals:
+        association: "vertex"
+        topology: "mesh"
+        offsets: [2, 2]
+        strides: [1, 7]
+        values: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
+                 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
+                 0.0, 0.0, 1.0, 2.0, 3.0, 4.0, 0.0,
+                 0.0, 0.0, 5.0, 6.0, 7.0, 8.0, 0.0,
+                 0.0, 0.0, 9.0, 10.0, 11.0, 12.0, 0.0,
+                 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+
 
 Species Sets
 ++++++++++++++++++++
@@ -1910,16 +2057,18 @@ them in ``<`` and ``>`` characters. An example expressions entry in the index is
 
   .. code:: json
 
+      {
       "fields":
       {
         "braid":
         {
-          // ...
+
         },
         "radial":
         {
-          // ...
-        },
+
+        }
+      },
       "expressions":
       {
         "scalar_expr":