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}

Note

In all of the coordinate space definitions outlined above, spherical coordinates adhere to the definitions of theta/phi used in the physics and engineering domains. Specifically, this means that theta refers to the polar angle of the coordinate (i.e. the angle from the +Z cartesian axis) and phi refers to the azimuthal angle of the coordinate (i.e. the angle from the +X cartesian axis). The figure below most succinctly describes these conventions:

_images/spherical_coordinates_render.png

Figure of spherical coordinate conventions (courtesy of Wikipedia)

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
quad quadrilateral indices to 4 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

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:

  • adjsets/adjset/association: “vertex” | “element”
  • adjsets/adjset/topology: “topo”
  • adjsets/adjset/groups/group/neighbors: (integer array)
  • adjsets/adjset/groups/group/values: (integer array)

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
_images/basic_hex_2d_render.png

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
_images/basic_hex_2d_render.png

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
_images/basic_hex_2d_render.png

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
_images/basic_tet_2d_render.png

Pseudocolor plot of basic (mesh type ‘tris’)

Quads

  • Usage Example
// create container node
Node mesh;
// generate simple explicit quad-based 2d 'basic' mesh
conduit::blueprint::mesh::examples::basic("quads", 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": "quad",
        "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
_images/basic_hex_2d_render.png

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
_images/basic_hex_2d_render.png

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
_images/basic_tet_3d_render.png

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
_images/basic_hex_3d_render.png

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
_images/basic_hex_3d_render.png

Pseudocolor plot of basic (mesh type ‘polyhedra’)

braid

_images/braid_render.png

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

_images/spiral_render.png

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

_images/julia_render.png

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

_images/polytess_render.png

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;

// add the topology
// 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");