mesh

Protocol

The mesh blueprint protocol defines a computational mesh using one or more Coordinate Sets (via child coordsets), one or more Topologies (via child topologies), zero or more Fields (via child fields), and optional State information (via child state). For simplicity, the descriptions below outline one Coordinate Set named coords one Topology named topo.

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: “uniform”
      • 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
quad quadrilateral indices to 4 coordinate tuples
tet tetrahedron indices to 4 coordinate tuples
hex hexahedron indices to 8 coordinate tuples

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 three implicit ways to define a grid of elements on top of a coordinate set. For 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.

  • 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 Topology

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 texs), 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.

Fields

Fields are used to hold simulation state arrays associated with a mesh topology.

A field contains an mcarray and information about how this data is associated with elements of the topology. To conform to the protocol, each entry under fields must be an Object that contains one of these two styles of field descriptions:

  • Standard Fields:
    • fields/den/topology: “topo”
    • fields/den/association: “vertex” | “element”
    • fields/den/values: (mcarray)
  • High Order Fields:
    • fields/den/topology: “topo”
    • fields/den/basis: (a string that includes an mfem-style finite element collection name)
    • fields/den/values: (mcarray)

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/number_of_domains: (integer)
  • state/domain_id: (integer)

Examples

The mesh blueprint namespace includes a function braid(), that generates examples that cover the range of coordinate sets and topologies supported.

The example datasets include a vertex-centered scalar field braid, an element-centered scalar field radial and as 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 &out);

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,z directions.

nz is ignored for 2d-only examples.

The resulting data is placed the Node out, which is passed in via a reference.

For more details, see the unit tests that exercise these examples in src/tests/blueprint/t_blueprint_mesh_examples.cpp