mesh

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: “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.

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 converting between windows, or different cascade schemes.

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

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.

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