# mesh¶

This section provides details about the Mesh Blueprint. Lots of them. We don’t have a Mesh Blueprint tutorial yet, if you are looking to wrap your mind around the basic mechanics of describing a mesh, you may want to start by reviewing the Detailed Uniform Example and exploring the other Examples included in the blueprint library.

## Protocol¶

The Blueprint protocol defines a single-domain computational mesh using one or more Coordinate Sets (via child `coordsets`), one or more Topologies (via child `topologies`), zero or more Materials Sets (via child `matsets`), zero or more Fields (via child `fields`), optional Adjacency Set information (via child `adjsets`), and optional State information (via child `state`). The protocol defines multi-domain meshes as Objects that contain one or more single-domain mesh entries. For simplicity, the descriptions below are structured relative to a single-domain mesh Object that contains one Coordinate Set named `coords`, one Topology named `topo`, and one Material Set named `matset`.

### Coordinate Sets¶

To define a computational mesh, the first required entry is a set of spatial coordinate tuples that can underpin a mesh topology.

The mesh blueprint protocol supports sets of spatial coordinates from three coordinate systems:

• Cartesian: {x,y,z}
• Cylindrical: {r,z}
• Spherical: {r,theta,phi}

The mesh blueprint protocol supports three types of Coordinate Sets: `uniform`, `rectilinear`, and `explicit`. To conform to the protocol, each entry under `coordsets` must be an Object with entries from one of the cases outlined below:

• uniform

An implicit coordinate set defined as the cartesian product of i,j,k dimensions starting at an `origin` (ex: {x,y,z}) using a given `spacing` (ex: {dx,dy,dz}).

• Cartesian
• coordsets/coords/type: “uniform”
• coordsets/coords/dims/{i,j,k}
• coordsets/coords/origin/{x,y,z} (optional, default = {0.0, 0.0, 0.0})
• coordsets/coords/spacing/{dx,dy,dz} (optional, default = {1.0, 1.0, 1.0})
• Cylindrical
• coordsets/coords/type: “uniform”
• coordsets/coords/dims/{i,j}
• coordsets/coords/origin/{r,z} (optional, default = {0.0, 0.0})
• coordsets/coords/spacing/{dr,dz} (optional, default = {1.0, 1.0})
• Spherical
• coordsets/coords/type: “uniform”
• coordsets/coords/dims/{i,j}
• coordsets/coords/origin/{r,theta,phi} (optional, default = {0.0, 0.0, 0.0})
• coordsets/coords/spacing/{dr,dtheta, dphi} (optional, default = {1.0, 1.0, 1.0})
• rectilinear

An implicit coordinate set defined as the cartesian product of passed coordinate arrays.

• Cartesian
• coordsets/coords/type: “rectilinear”
• coordsets/coords/values/{x,y,z}
• Cylindrical:
• coordsets/coords/type: “rectilinear”
• coordsets/coords/values/{r,z}
• Spherical
• coordsets/coords/type: “rectilinear”
• coordsets/coords/values/{r,theta,phi}
• explicit

An explicit set of coordinates, which includes `values` that conforms to the mcarray blueprint protocol.

• Cartesian
• coordsets/coords/type: “explicit”
• coordsets/coords/values/{x,y,z}
• Cylindrical
• coordsets/coords/type: “explicit”
• coordsets/coords/values/{r,z}
• Spherical
• coordsets/coords/type: “explicit”
• coordsets/coords/values/{r,theta,phi}

### Toplogies¶

The next entry required to describe a computational mesh is its topology. To conform to the protocol, each entry under topologies must be an Object that contains one of the topology descriptions outlined below.

#### Topology Nomenclature¶

The mesh blueprint protocol describes meshes in terms of `vertices`, `edges`, `faces`, and `elements`.

The following element shape names are supported:

Name Geometric Type Specified By
point point an index to a single coordinate tuple
line line indices to 2 coordinate tuples
tri triangle indices to 3 coordinate tuples
tet tetrahedron indices to 4 coordinate tuples
hex hexahedron indices to 8 coordinate tuples
polygonal polygon an index count N, then indices to N coordinate tuples
polyhedral polyhedron a face count M, then M polygonal face definitions

#### Association with a Coordinate Set¶

Each topology entry must have a child `coordset` with a string that references a valid coordinate set by name.

• topologies/topo/coordset: “coords”

#### Optional association with a Grid Function¶

Topologies can optionally include a child `grid_function` with a string that references a valid field by name.

• topologies/topo/grid_function: “gf”

#### Implicit Topology¶

The mesh blueprint protocol accepts four implicit ways to define a topology on a coordinate set. The first simply uses all the points in a given coordinate set and the rest define grids of elements on top of a coordinate set. For the grid cases with a coordinate set with 1D coordinate tuples, line elements are used, for sets with 2D coordinate tuples quad elements are used, and for 3D coordinate tuples hex elements are used.

• points: An implicit topology using all of the points in a coordinate set.

• topologies/topo/coordset: “coords”
• topologies/topo/type: “points”
• uniform: An implicit topology that defines a grid of elements on top of a uniform coordinate set.

• topologies/topo/coordset: “coords”
• topologies/topo/type: “uniform”
• topologies/topo/elements/origin/{i0,j0,k0} (optional, default = {0,0,0})
• rectilinear: An implicit topology that defines a grid of elements on top of a rectilinear coordinate set.

• topologies/topo/coordset: “coords”
• topologies/topo/type: “rectilinear”
• topologies/topo/elements/origin/{i0,j0,k0} (optional, default = {0,0,0})
• structured: An implicit topology that defines a grid of elements on top of an explicit coordinate set.
• topologies/topo/coordset: “coords”
• topologies/topo/type = “structured”
• topologies/topo/elements/dims/{i,j,k}
• topologies/topo/elements/origin/{i0,j0,k0} (optional, default = {0,0,0})

#### Explicit (Unstructured) Topology¶

##### Single Shape Topologies¶

For topologies using a homogenous collection of element shapes (eg: all hexs), the topology can be specified by a connectivity array and a shape name.

• topologies/topo/coordset: “coords”
• topologies/topo/type: “unstructured”
• topologies/topo/elements/shape: (shape name)
• topologies/topo/elements/connectivity: (index array)
##### Mixed Shape Toplogies¶

For topologies using a non-homogenous collections of element shapes (eg: hexs and tets), the topology can specified using a single shape topology for each element shape.

• list - A Node in the List role, that contains a children that conform to the Single Shape Topology case.
• object - A Node in the Object role, that contains a children that conform to the Single Shape Topology case.

Note

Future version of the mesh blueprint will expand support to include mixed elements types in a single array with related index arrays.

###### Element Windings¶

The mesh blueprint does yet not have a prescribed winding convention (a way to order the association of vertices to elements) or more generally to outline a topology’s dimensional cascade (how elements are related to faces, faces are related to edges, and edges are related to vertices. )

This is a gap we are working to solve in future versions of the mesh blueprint, with a goal of providing transforms to help convert between different winding or cascade schemes.

That said VTK (and VTK-m) winding conventions are assumed by MFEM, VisIt, or Ascent when using Blueprint data.

##### Polygonal/Polyhedral Topologies¶

The `polygonal` and `polyhedral` topology shape types are structually identical to the other explicit topology shape types (see the Single Shape Topologies section above), but the contents of their `elements/connectivity` sections look slightly different. In particular, the shape index connectivity for each element in these topologies is explicit, which means that the index sequence for each element is prefixed by a count that specifies the total number of indices (polygonal) or faces (polyhedral) that comprise that element. This explicit shape index facilitates both the specification of non-standard shapes (e.g. octogons) and of highly mixed shape topologies (e.g. polygons/polyhedra of many different shapes in one topology).

In more explicit terms, the `elements/connectivity` lists for the `polygonal` and `polyhedral` topology shapes follow these rules:

• polygonal - The first element starts at the beginning of the `elements/connectivity` list. The first value `V` for each element `E` indicates the number of vertices that comprise polygon `E`. The next `V` values in the list are indices for the `V` coordinates that comprise `E`. The next element begins after this sequence of `V` values, and this specification continues until the connectivity list is exhausted of items.

```// Example Diagram:
//
//       4-----5
//       |`\   |
// e1 -> |  \  | <- e0
//       |   \.|
//       7-----6
//

//    index count ---+     +--- coordinate index values
//                   |     |
//                   v  |-----|
int64 poly_data[] = {3, 4, 6, 5,   // element 0
3, 7, 6, 4};  // element 1

conduit::Node topology = mesh["topologies/poly_topo"];
topology["coordset"] = "coords";
topology["type"] = "unstructured";
topology["elements/shape"] = "polygonal";
topology["elements/connectivity"].set_int64_ptr(&poly_data[0], 8);
```
• polyhedral - The first element begins at the first index of the `elements/connectivity` list. The first value `F` for each element `E` specifies the number of faces that comprise polyhedron `E`. The next value `V` denotes the number of vertices that comprise the first polygonal face `F1` of polyhedron `E`. Exactly like the polygonal specification, the following sequence of `V` values contain the indices of the coordinates for face `F1`. The next face `F2` begins immediately after this sequence, and this process continues until `F` faces are enumerated. The next element then begins after this supersequence, and this specification continues until the connectivity list is exhausted of items.

```// Example Diagram:
//
//         0
//        /|\
//       / | \ <- e0
//      /  |  \
//     /_.-3-._\
//    1.,  |  ,.4
//     \ `'2'` /
//      \  |  /
// e1 -> \ | /
//        \|/
//         5
//

//  face index count ---+
//                      |
//     face count ---+  |     +--- coordinate index values
//                   |  |     |
//                   v  v  |-----|
int64 poly_data[] = {5, 3, 0, 1, 2, 3, 0, 2, 4, 3, 0, 1, 3, 3, 0, 3, 4, 4, 1, 2, 4, 3,   // element 0
5, 3, 5, 1, 2, 3, 5, 2, 4, 3, 5, 1, 3, 3, 5, 3, 4, 4, 1, 2, 4, 3};  // element 1

conduit::Node topology = mesh["topologies/poly_topo"];
topology["coordset"] = "coords";
topology["type"] = "unstructured";
topology["elements/shape"] = "polyhedral";
topology["elements/connectivity"].set_int64_ptr(&poly_data[0], 44);
```
##### (Optional) Element Offsets¶

Unstructured topologies can optionally include a child `elements/offsets` to indicate the starting position of each element defined in the `elements/connectivity` array. This list is most often specified for heterogeneous and polygonal/polyhedral topologies so that the elements don’t need to be found by stepping through the input connectivity array.

• topologies/topo/elements/offsets: (index array)

To generate this array for a given unstructured topology `topo`, make the following call:

```conduit::blueprint::mesh::topology::unstructured::generate_offsets(topo,                       // input topology
topo["elements/offsets"]);  // output node for offset array
```

### Material Sets¶

Materials Sets contain material name and volume fraction information defined over a specified mesh topology.

A material set contains an mcarray that houses per-material, per-element volume fractions and a source topology over which these volume fractions are defined. To conform to protocol, each entry in the `matsets` section must be an Object that contains the following information:

• matsets/matset/topology: “topo”
• matsets/matset/volume_fractions: (mcarray)

### Fields¶

Fields are used to hold simulation state arrays associated with a mesh topology and (optionally) a mesh material set.

Each field entry can define an mcarray of material-independent values and/or an mcarray of per-material values. These data arrays must be specified alongside a source space, which specifies the space over which the field values are defined (i.e. a topology for material-independent values and a material set for material-dependent values). Minimally, each field entry must specify one of these data sets, the source space for the data set, an association type (e.g. per-vertex, per-element, or per-grid-function-entity), and a volume scaling type (e.g. volume-dependent, volume-independent). Thus, to conform to protocol, each entry under the `fields` section must be an Object that adheres to one of the following descriptions:

• Material-Independent Fields:
• fields/field/association: “vertex” | “element”
• fields/field/grid_function: (mfem-style finite element collection name) (replaces “association”)
• fields/field/volume_dependent: “true” | “false”
• fields/field/topology: “topo”
• fields/field/values: (mcarray)
• Material-Dependent Fields:
• fields/field/association: “vertex” | “element”
• fields/field/grid_function: (mfem-style finite element collection name) (replaces “association”)
• fields/field/volume_dependent: “true” | “false”
• fields/field/matset: “matset”
• fields/field/matset_values: (mcarray)
• Mixed Fields:
• fields/field/association: “vertex” | “element”
• fields/field/grid_function: (mfem-style finite element collection name) (replaces “association”)
• fields/field/volume_dependent: “true” | “false”
• fields/field/topology: “topo”
• fields/field/values: (mcarray)
• 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.

### Species Sets¶

Species Sets are a means of representing multi-dimensional per-material quantities, most commonly per-material substance fractions.

Individual Species Sets are entries in the `specsets` section of the Blueprint hierarchy, and these entries are formatted in much the same way as `fields` entries that describe per-material, multi-dimensional fields. Just as with this class of `fields` entries, each `specsets` entry must specify the material set over which it is defined and enumerate its values within an mcarray that’s organized in material-major and component-minor order. Additionally, like `field` entries, each `specsets` item must indicate a volumetric scaling type (e.g. volume-dependent, volume-independent). To put it in short, each entry in the `specsets` section of the Blueprint hierarchy must be an Object that follows this template:

• specsets/specset/volume_dependent: “true” | “false”
• specsets/specset/matset: “matset”
• specsets/specset/matset_values: (mcarray)

Adjacency Sets are used to outline the shared geometry between subsets of domains in multi-domain meshes.

Each entry in the Adjacency Sets section is meant to encapsulate a set of adjacency information shared between domains. Each individual adjacency set contains a source topology, an element association, and a list of adjacency groups. An adjacency set’s contained groups describe adjacency information shared between subsets of domains, which is represented by a subset of adjacent neighbor domains IDs and a list of shared element IDs. The fully-defined Blueprint schema for the `adjsets` entries looks like the following:

### State¶

Optional state information is used to provide metadata about the mesh. While the mesh blueprint is focused on describing a single domain of a domain decomposed mesh, the state info can be used to identify a specific mesh domain in the context of a domain decomposed mesh.

To conform, the `state` entry must be an Object and can have the following optional entries:

• state/time: (number)
• state/cycle: (number)
• state/domain_id: (integer)

## Examples¶

The C++ `conduit::blueprint::mesh::examples` namespace and the Python `conduit.blueprint.mesh.examples` module provide functions that generate example Mesh Blueprint data. For details on how to write these data sets to files, see the unit tests that exercise these examples in `src/tests/blueprint/t_blueprint_mesh_examples.cpp` and the mesh output example below. This section outlines the examples that demonstrate the most commonly used mesh schemas.

### basic¶

The simplest of the mesh examples, `basic()`, generates an homogenous example mesh with a configurable element representation/type (see the `mesh_type` table below) spanned by a single scalar field that contains a unique identifier for each mesh element. The function that needs to be called to generate an example of this type has the following signature:

```conduit::blueprint::mesh::examples::basic(const std::string &mesh_type, // element type/dimensionality
index_t nx,                   // number of grid points along x
index_t ny,                   // number of grid points along y
index_t nz,                   // number of grid points along z (3d only)
Node &res);                   // result container
```

The element representation, type, and dimensionality are all configured through the `mesh_type` argument. The supported values for this parameter and their corresponding effects are outlined in the table below:

 Mesh Type Dimensionality Coordset Type Topology Type Element Type uniform 2d/3d implicit implicit quad/hex rectilinear 2d/3d implicit implicit quad/hex structured 2d/3d explicit implicit quad/hex tris 2d explicit explicit tri quads 2d explicit explicit quad polygons 2d explicit explicit polygon tets 3d explicit explicit tet hexs 3d explicit explicit hex polyhedra 3d explicit explicit polyhedron

The remainder of this section demonstrates each of the different `basic()` mesh types, outlining each type with a simple example that (1) presents the generating call, (2) shows the results of the call in Blueprint schema form, and (3) displays the corresponding graphical rendering of this schema.

#### Uniform¶

• Usage Example
```// create container node
Node mesh;
// generate simple uniform 2d 'basic' mesh
conduit::blueprint::mesh::examples::basic("uniform", 3, 3, 0, mesh);
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "uniform",
"dims":
{
"i": 3,
"j": 3
},
"origin":
{
"x": -10.0,
"y": -10.0
},
"spacing":
{
"dx": 10.0,
"dy": 10.0
}
}
},
"topologies":
{
"mesh":
{
"type": "uniform",
"coordset": "coords"
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘uniform’)

#### Rectilinear¶

• Usage Example
```Node mesh;
// generate simple rectilinear 2d 'basic' mesh
conduit::blueprint::mesh::examples::basic("rectilinear", 3, 3, 0, mesh);
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "rectilinear",
"values":
{
"x": [-10.0, 0.0, 10.0],
"y": [-10.0, 0.0, 10.0]
}
}
},
"topologies":
{
"mesh":
{
"type": "rectilinear",
"coordset": "coords"
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘rectilinear’)

#### Structured¶

• Usage Example
```// create container node
Node mesh;
// generate simple structured 2d 'basic' mesh
conduit::blueprint::mesh::examples::basic("structured", 3, 3, 1, mesh);
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "explicit",
"values":
{
"x": [-10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0],
"y": [-10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0]
}
}
},
"topologies":
{
"mesh":
{
"type": "structured",
"coordset": "coords",
"elements":
{
"dims":
{
"i": 2,
"j": 2
}
}
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘structured’)

#### Tris¶

• Usage Example
```// create container node
Node mesh;
// generate simple explicit tri-based 2d 'basic' mesh
conduit::blueprint::mesh::examples::basic("tris", 3, 3, 0, mesh);
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "explicit",
"values":
{
"x": [-10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0],
"y": [-10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0]
}
}
},
"topologies":
{
"mesh":
{
"type": "unstructured",
"coordset": "coords",
"elements":
{
"shape": "tri",
"connectivity": [0, 3, 4, 0, 1, 4, 1, 4, 5, 1, 2, 5, 3, 6, 7, 3, 4, 7, 4, 7, 8, 4, 5, 8]
}
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘tris’)

• Usage Example
```// create container node
Node mesh;
// generate simple explicit quad-based 2d 'basic' mesh
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "explicit",
"values":
{
"x": [-10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0],
"y": [-10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0]
}
}
},
"topologies":
{
"mesh":
{
"type": "unstructured",
"coordset": "coords",
"elements":
{
"connectivity": [0, 3, 4, 1, 1, 4, 5, 2, 3, 6, 7, 4, 4, 7, 8, 5]
}
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘quads’)

#### Polygons¶

• Usage Example
```// create container node
Node mesh;
// generate simple explicit poly-based 2d 'basic' mesh
conduit::blueprint::mesh::examples::basic("polygons", 3, 3, 0, mesh);
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "explicit",
"values":
{
"x": [-10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0],
"y": [-10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0]
}
}
},
"topologies":
{
"mesh":
{
"type": "unstructured",
"coordset": "coords",
"elements":
{
"shape": "polygonal",
"connectivity": [4, 0, 3, 4, 1, 4, 1, 4, 5, 2, 4, 3, 6, 7, 4, 4, 4, 7, 8, 5]
}
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘polygons’)

#### Tets¶

• Usage Example
```// create container node
Node mesh;
// generate simple explicit tri-based 3d 'basic' mesh
conduit::blueprint::mesh::examples::basic("tets", 3, 3, 3, mesh);
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "explicit",
"values":
{
"x": [-10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0],
"y": [-10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0],
"z": [-10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0]
}
}
},
"topologies":
{
"mesh":
{
"type": "unstructured",
"coordset": "coords",
"elements":
{
"shape": "tet",
"connectivity": [0, 4, 1, 13, 0, 3, 4, 13, 0, 12, 3, 13, 0, 9, 12, 13, 0, 10, 9, 13, 0, 1, 10, 13, 1, 5, 2, 14, 1, 4, 5, 14, 1, 13, 4, 14, 1, 10, 13, 14, 1, 11, 10, 14, 1, 2, 11, 14, 3, 7, 4, 16, 3, 6, 7, 16, 3, 15, 6, 16, 3, 12, 15, 16, 3, 13, 12, 16, 3, 4, 13, 16, 4, 8, 5, 17, 4, 7, 8, 17, 4, 16, 7, 17, 4, 13, 16, 17, 4, 14, 13, 17, 4, 5, 14, 17, 9, 13, 10, 22, 9, 12, 13, 22, 9, 21, 12, 22, 9, 18, 21, 22, 9, 19, 18, 22, 9, 10, 19, 22, 10, 14, 11, 23, 10, 13, 14, 23, 10, 22, 13, 23, 10, 19, 22, 23, 10, 20, 19, 23, 10, 11, 20, 23, 12, 16, 13, 25, 12, 15, 16, 25, 12, 24, 15, 25, 12, 21, 24, 25, 12, 22, 21, 25, 12, 13, 22, 25, 13, 17, 14, 26, 13, 16, 17, 26, 13, 25, 16, 26, 13, 22, 25, 26, 13, 23, 22, 26, 13, 14, 23, 26]
}
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0, 17.0, 18.0, 19.0, 20.0, 21.0, 22.0, 23.0, 24.0, 25.0, 26.0, 27.0, 28.0, 29.0, 30.0, 31.0, 32.0, 33.0, 34.0, 35.0, 36.0, 37.0, 38.0, 39.0, 40.0, 41.0, 42.0, 43.0, 44.0, 45.0, 46.0, 47.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘tets’)

#### Hexs¶

• Usage Example
```// create container node
Node mesh;
// generate simple explicit quad-based 3d 'basic' mesh
conduit::blueprint::mesh::examples::basic("hexs", 3, 3, 3, mesh);
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "explicit",
"values":
{
"x": [-10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0],
"y": [-10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0],
"z": [-10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0]
}
}
},
"topologies":
{
"mesh":
{
"type": "unstructured",
"coordset": "coords",
"elements":
{
"shape": "hex",
"connectivity": [0, 1, 4, 3, 9, 10, 13, 12, 1, 2, 5, 4, 10, 11, 14, 13, 3, 4, 7, 6, 12, 13, 16, 15, 4, 5, 8, 7, 13, 14, 17, 16, 9, 10, 13, 12, 18, 19, 22, 21, 10, 11, 14, 13, 19, 20, 23, 22, 12, 13, 16, 15, 21, 22, 25, 24, 13, 14, 17, 16, 22, 23, 26, 25]
}
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘hexs’)

#### Polyhedra¶

• Usage Example
```// create container node
Node mesh;
// generate simple explicit poly-based 3d 'basic' mesh
conduit::blueprint::mesh::examples::basic("polyhedra", 3, 3, 3, mesh);
// print out results
mesh.print();
```
• Result
```{
"coordsets":
{
"coords":
{
"type": "explicit",
"values":
{
"x": [-10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0, -10.0, 0.0, 10.0],
"y": [-10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0],
"z": [-10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, -10.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0]
}
}
},
"topologies":
{
"mesh":
{
"type": "unstructured",
"coordset": "coords",
"elements":
{
"shape": "polyhedral",
"connectivity": [6, 4, 0, 1, 4, 3, 4, 0, 1, 10, 9, 4, 1, 4, 13, 10, 4, 4, 3, 12, 13, 4, 3, 0, 9, 12, 4, 9, 10, 13, 12, 6, 4, 1, 2, 5, 4, 4, 1, 2, 11, 10, 4, 2, 5, 14, 11, 4, 5, 4, 13, 14, 4, 4, 1, 10, 13, 4, 10, 11, 14, 13, 6, 4, 3, 4, 7, 6, 4, 3, 4, 13, 12, 4, 4, 7, 16, 13, 4, 7, 6, 15, 16, 4, 6, 3, 12, 15, 4, 12, 13, 16, 15, 6, 4, 4, 5, 8, 7, 4, 4, 5, 14, 13, 4, 5, 8, 17, 14, 4, 8, 7, 16, 17, 4, 7, 4, 13, 16, 4, 13, 14, 17, 16, 6, 4, 9, 10, 13, 12, 4, 9, 10, 19, 18, 4, 10, 13, 22, 19, 4, 13, 12, 21, 22, 4, 12, 9, 18, 21, 4, 18, 19, 22, 21, 6, 4, 10, 11, 14, 13, 4, 10, 11, 20, 19, 4, 11, 14, 23, 20, 4, 14, 13, 22, 23, 4, 13, 10, 19, 22, 4, 19, 20, 23, 22, 6, 4, 12, 13, 16, 15, 4, 12, 13, 22, 21, 4, 13, 16, 25, 22, 4, 16, 15, 24, 25, 4, 15, 12, 21, 24, 4, 21, 22, 25, 24, 6, 4, 13, 14, 17, 16, 4, 13, 14, 23, 22, 4, 14, 17, 26, 23, 4, 17, 16, 25, 26, 4, 16, 13, 22, 25, 4, 22, 23, 26, 25]
}
}
},
"fields":
{
"field":
{
"association": "element",
"topology": "mesh",
"volume_dependent": "false",
"values": [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0]
}
}
}
```
• Visual

Pseudocolor plot of `basic` (mesh type ‘polyhedra’)

### braid¶

Pseudocolor plot of a 3D braid example `braid` field

The `braid()` generates example meshes that cover the range of coordinate sets and topologies supported by the Mesh Blueprint.

The example datasets include a vertex-centered scalar field `braid`, an element-centered scalar field `radial` and a vertex-centered vector field `vel`.

```conduit::blueprint::mesh::examples::braid(const std::string &mesh_type,
index_t nx,
index_t ny,
index_t nz,
Node &res);
```

Here is a list of valid strings for the `mesh_type` argument:

 Mesh Type Description uniform 2d or 3d uniform grid (implicit coords, implicit topology) rectilinear 2d or 3d rectilinear grid (implicit coords, implicit topology) structured 2d or 3d structured grid (explicit coords, implicit topology) point 2d or 3d unstructured mesh of point elements (explicit coords, explicit topology) lines 2d or 3d unstructured mesh of line elements (explicit coords, explicit topology) tris 2d unstructured mesh of triangle elements (explicit coords, explicit topology) quads 2d unstructured mesh of quadrilateral elements (explicit coords, explicit topology) tets 3d unstructured mesh of tetrahedral elements (explicit coords, explicit topology) hexs 3d unstructured mesh of hexahedral elements (explicit coords, explicit topology)

`nx`, `ny`, `nz` specify the number of elements in the x, y, and z directions.

`nz` is ignored for 2d-only examples.

The resulting data is placed the Node `res`, which is passed in via reference.

### spiral¶

Pseudocolor and Contour plots of the spiral example `dist` field.

The `sprial()` function generates a multi-domain mesh composed of 2D square domains with the area of successive fibonacci numbers. The result estimates the Golden spiral.

The example dataset provides a vertex-centered scalar field `dist` that estimates the distance from each vertex to the Golden spiral.

```conduit::blueprint::mesh::examples::spiral(conduit::index_t ndomains,
Node &res);
```

`ndomains` specifies the number of domains to generate, which is also the number of entries from fibonacci sequence used.

The resulting data is placed the Node `res`, which is passed in via reference.

### julia¶

Pseudocolor plot of the julia example `iter` field

The `julia()` function creates a uniform grid that visualizes Julia set fractals.

The example dataset provides an element-centered scalar field `iter` that represents the number of iterations for each point tested or zero if not found in the set.

```conduit::blueprint::mesh::examples::julia(index_t nx,
index_t ny,
float64 x_min,
float64 x_max,
float64 y_min,
float64 y_max,
float64 c_re,
float64 c_im,
Node &res);
```

`nx`, `ny` specify the number of elements in the x and y directions.

`x_min`, `x_max`, `y_min`, `y_max` specify the x and y extents.

`c_re`, `c_im` specify real and complex parts of the constant used.

The resulting data is placed the Node `res`, which is passed in via reference.

### polytess¶

Pseudocolor plot of the polytess example `level` field.

The `polytess()` function generates a polygonal tesselation in the 2D plane comprised of octogons and squares (known formally as a two-color truncated square tiling).

The scalar element-centered field `level` defined in the result mesh associates each element with its topological distance from the center of the tesselation.

```conduit::blueprint::mesh::examples::polytess(index_t nlevels,
Node &res);
```

`nlevels` specifies the number of tesselation levels/layers to generate. If this value is specified as 1 or less, only the central tesselation level (i.e. the octogon in the center of the geometry) will be generated in the result.

The resulting data is placed the Node `res`, which is passed in via reference.

### miscellaneous¶

This section doesn’t overview any specific example in the `conduit::blueprint::mesh::examples` namespace, but rather provides a few additional code samples to help with various common tasks. Each subsection covers a specific task and presents how it can be accomplished using a function or set of functions in Conduit and/or the Mesh Blueprint library.

#### Outputting Meshes for Visualization¶

Suppose that you have an arbitrary Blueprint mesh that you want to output from a running code and subsequently visualize using a visualization tool (e.g. VisIt). Provided that your mesh is sufficiently simple (see the note at the end of this section for details), you can output your mesh using one of the following `conduit::relay` library functions:

```// saves the given mesh to disk at the given path (using the extension
// suffix in the path to inform the output data protocol)
conduit::relay::io_blueprint::save(const conduit::Node &mesh,
const std::string &path);

// saves the given mesh to disk at the given path with the given explicit
// output data protocol (e.g. "json", "hdf5")
conduit::relay::io_blueprint::save(const conduit::Node &mesh,
const std::string &path,
const std::string &protocol);
```

It’s important to note that both of these functions expect the given path to have a valid extension to properly output results. The valid extensions for these functions are as follows:

• `.blueprint_root` (JSON Extension)
• `.blueprint_root_hdf5` (HDF5 Extension)

Files output from these functions can be opened and subsequently visualized directly using VisIt.

Note

This automatic index generation and save functionality is under development. It handles most basic cases, but only supports `json` and `hdf5` output protocols and has limited multi-domain support. We are working on API changes and a more robust capability for future versions of Conduit.

#### Detailed Uniform Example¶

This snippet provides a complete C++ example that demonstrates:

• Describing a uniform mesh in a Conduit tree
• Verifying the tree conforms to the Mesh Blueprint
• Saving the result to a JSON file that VisIt can open
```// create a Conduit node to hold our mesh data
Node mesh;

// create the coordinate set
mesh["coordsets/coords/type"] = "uniform";
mesh["coordsets/coords/dims/i"] = 3;
mesh["coordsets/coords/dims/j"] = 3;
// add origin and spacing to the coordset (optional)
mesh["coordsets/coords/origin/x"] = -10.0;
mesh["coordsets/coords/origin/y"] = -10.0;
mesh["coordsets/coords/spacing/dx"] = 10.0;
mesh["coordsets/coords/spacing/dy"] = 10.0;

// this case is simple b/c it's implicitly derived from the coordinate set
mesh["topologies/topo/type"] = "uniform";
// reference the coordinate set by name
mesh["topologies/topo/coordset"] = "coords";

// add a simple element-associated field
mesh["fields/ele_example/association"] =  "element";
// reference the topology this field is defined on by name
mesh["fields/ele_example/topology"] =  "topo";
// set the field values, for this case we have 4 elements
mesh["fields/ele_example/values"].set(DataType::float64(4));

float64 *ele_vals_ptr = mesh["fields/ele_example/values"].value();

for(int i=0;i<4;i++)
{
ele_vals_ptr[i] = float64(i);
}

// add a simple vertex-associated field
mesh["fields/vert_example/association"] =  "vertex";
// reference the topology this field is defined on by name
mesh["fields/vert_example/topology"] =  "topo";
// set the field values, for this case we have 9 vertices
mesh["fields/vert_example/values"].set(DataType::float64(9));

float64 *vert_vals_ptr = mesh["fields/vert_example/values"].value();

for(int i=0;i<9;i++)
{
vert_vals_ptr[i] = float64(i);
}

// make sure we conform:
Node verify_info;
if(!blueprint::mesh::verify(mesh, verify_info))
{
std::cout << "Verify failed!" << std::endl;
verify_info.print();
}

// print out results
mesh.print();

// save our mesh to a json that can be read by VisIt
conduit::relay::io_blueprint::save(mesh, "basic_detailed_uniform.blueprint_root");
```