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 givenspacing
(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})
- Cartesian
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}
- Cartesian
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}
- Cartesian
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 valueV
for each elementE
indicates the number of vertices that comprise polygonE
. The nextV
values in the list are indices for theV
coordinates that compriseE
. The next element begins after this sequence ofV
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 valueF
for each elementE
specifies the number of faces that comprise polyhedronE
. The next valueV
denotes the number of vertices that comprise the first polygonal faceF1
of polyhedronE
. Exactly like the polygonal specification, the following sequence ofV
values contain the indices of the coordinates for faceF1
. The next faceF2
begins immediately after this sequence, and this process continues untilF
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
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
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
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
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
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
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
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
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
braid¶
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¶
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¶
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¶
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");