Mesh And Point Cloud Data Access
Last update: 10.07.2023
Mesh And Point Cloud Data Access
This section pre-supposes familiarity with the concepts introduced in Access to Heavyweight Data section. Heavyweight array data access structures described in that section can be combined into higher-level structures to provide access to mesh and point cloud data. This section describes these higher-level structures as well as requirements of mesh and point cloud structures.
Mesh
The mesh formats can be broken down into two categories: element-based mesh and face-based mesh.
Element-based mesh defines the mesh primarily through mesh elements along with element-to-node connectivity. Elements are faces in the context of surface meshes and cells in the context of volume meshes.
Face-based mesh defines the mesh primarily through mesh faces along with face-to-node connectivity and, if it's a volume mesh, face-to-cell connectivity.
The advantage of element-based mesh format is that it provides a way to define high-order elements (that is, elements with mid-side nodes along the edges), while the advantage of the face-based mesh format is that it provides a way to define arbitrary polygons and polyhedra.
It is possible to define the mesh using both formats at the same time. However, in most cases it would require providing redundant information, so most participant solvers can be expected to choose one of the two mesh formats.
Element-Based Surface Mesh Example
Face-Based Surface Mesh Example
Element-Based Volume Mesh Example
Face-Based Volume Mesh Example
Intermediate Structures
The intermediate structures are used to define the mesh. These structures are node data, element type data, element node count data, element-to-node connectivity data, face-to-cell connectivity data, and cell id data. They are described in more detail below.
Element-based mesh format requires:
- Node data
- Element type data (elements are faces if surface mesh)
- Element-to-node connectivity data (elements are faces if volume mesh)
Face-based mesh format requires:
- Node data
- Element node count data (elements are faces)
- Element-to-node connectivity data (elements are faces)
- Face-to-cell connectivity data (if volume mesh)
- Cell id data (if voluem mesh)
Node Data
This structure provides information about the mesh nodes. There are two relevant pieces of information when providing node data: node ids and node coordinates.
Node ids provides access to the array of integers representing node ids. The ids are considered to be global across all parallel MPI processes and all of a participant's regions that are registered with System Coupling. For example, if region A refers to node id N, and region B refers to node id N, then both regions must refer to the exact same node, i.e. node with id N is shared between regions A and B. Similarly, if running in parallel, and process with rank X refers to node with ids N, and process with rank Y refers to node id N, then both processes must refer to the exact same node, i.e. node id with id N is duplicated in both processes X and Y. The ids do not have to be contiguous. The ids must be non-negative.
Node ids are optional. If node ids are provided, then the node coordinates must be provided in the same order as node ids, i.e. n-th entry in the node ids array correponds to the n-th entry in the node coordinates array(s). If node ids are not not provided, then node coordinates must be provided in the ascending node ids order. In this case, the actual node ids are implicitly provided elsewhere, e.g. via element-to-node connectivity data (see below).
Element Type Data
This structure provides information about the element types. Supported element types are defined in the ElementTypes.hpp
(C++), syscElementTypes.h
(C), syscElementTypesF.fi
(Fortran) header files and are shown in Figures 1 to 12 below.
Figure 1: Tri3 Element Type
Figure 2: Tri6 Element Type
Figure 3: Quad4 Element Type
Figure 4: Quad8 Element Type
Figure 5: Tet4 Element Type
Figure 6: Tet10 Element Type
Figure 7: Hex8 Element Type
Figure 8: Hex20 Element Type
Figure 9: Wedge6 Element Type
Figure 10: Wedge15 Element Type
Figure 11: Pyramid5 Element Type
Figure 12: Pyramid13 Element Type
Element Node Count Data
This structure provides information about the element node counts. It contains the number of elements as well as the number of nodes within each element.
Element-to-Node Connectivity Data
This structure provides information about the element-to-node connectivity. That is, for each element, the ids of nodes connected to that element are provided.
Cell Id Data
The cell id data structure provides information about the cell ids.
Like node ids, the cell ids are considered to be global across all parallel MPI processes and all regions that are registered with System Coupling and do not have to be contiguous. However, cell ids must be positive. Zero is reserved to mean the absence of a cell when defining face-to-cell connectivity (see below), therefore 0 is not a valid id for a mesh cell.
Face-to-Cell Connectivity Data
This structure provides information about the face-to-cell connectivity data.
Each face has two sides, side 0 and side 1. The sides are defined such that if one looks through the face from side 0 to side 1, then the face nodes are provided in clock-wise order. Another way to define it is the face normal (defined using the righ-hand rule) must point from side 0 to side 1. Figure 13 illustraces the convention for defining side 0 and side 1.
Figure 13: Face Side 0 and Side 1 Convention
The face may be connected to mesh cells on either side. If a face is connected to a cell on side 0, then it will contain the id of that cell in its "cell 0" entry. Likewise, if a face is connected to a cell on side 1, then it will contain the id of that cell in its "cell 1" entry.
If the face is not connected to any cell on either side, then its corresponding cell 0 or cell 1 entry must contain zero.
Mesh Model Information
Surface and volume regions can be topologically connected and the underlying mesh can be shared. A volume mesh can have bounding surfaces. Moreover, two volume meshes can share a surface. This kind of connectivity is called the mesh model and System Coupling participant library provides a way to communicate this information.
The way to specify that the volume and surface meshes are connected is to provide the side 0 and side 1 region names in the surface mesh structure. Side 0 and side 1 region names must refer to a valid volume region (with a valid volume mesh). It is important to maintain the convention for side 0 and side 1 as shown in Figure 13. The region names must refer to valid volume regions.
Element-Based Surface Mesh Example
Figure 14 shows a sample surface mesh, with each node and face labelled. Note that in this example, there are high-order quadrilateral and trilateral with midside nodes. Also note that node ids are not contiguous.
Figure 14: Surface Mesh Element-Based Format Example
Due to the presence of the high-order elements, the element-based mesh format is more suitable for this example.
Node Data
If providing node ids, node coordinates must be provided in the same order as node ids:
If node ids are ommitted, then the node coordinates must be provided in ascending node id order. Note that the actual node ids are going to be provided via the element-to-node connectivity data (see below).
When providing solution data on nodes, the ordering of the solution data must be consistent with the ordering of the node coordinates.
Element Type Data
Relevant element types are shown in Figure 2 and Figure 4 above. High-order trilateral element types are assigned the value of 6, while high-order quadrilaterl element types are assigned the value of 8.
Note that when providing solution data on elements (faces), the ordering of the solution data must be consistent with the ordering of the elements in this element node count data structure.
Element-to-Node Connectivty Data
Note that element-to-node connectivity contains the same node ids that are defined in the node data structure. If the node ids are omitted from the node data structure, then they are deduced from this element-to-node connectivity data structure.
The proper ordering of nodes within the element is also provided in Figure 2 and Figure 4. Corner nodes are listed first, followed by the mid-side nodes.
C++
The data is stored in STL vector structures. Then, basic data structures (sysc::OutputIntegerData
and sysc::OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (sysc::NodeData
, sysc::ElementTypeData
, and sysc::ElementNodeConnectivityData
). Finally, the intermediate structures are used to create the sysc::SurfaceMesh
object.
C
The data is stored in C arrays. Then, basic data structures (SyscOutputIntegerData
and SyscOutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (SyscNodeData
, SyscElementTypeData
, and SyscElementNodeConnectivityData
). Finally, the intermediate structures are used to create the SyscSurfaceMesh
object.
Note the helper functions syscGetNodeDataIC
, syscGetElementTypeData
, syscGetElementNodeConnectivityData
, and syscGetSurfaceMeshNTI
used to create the corresponding data structures.
Fortran
The data is stored in Fortran arrays. Then, basic data structures (SyscOutputIntegerDataF
and SyscOutputVectorDataF
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (SyscNodeDataF
, SyscElementTypeDataF
, and SyscElementNodeConnectivityDataF
). Finally, the intermediate structures are used to create the SyscSurfaceMeshF
object.
Note the helper functions syscGetNodeDataF
, syscGetElementTypeDataF
, syscGetElementNodeConnectivityDataF
, and syscGetSurfaceMeshF
used to create the corresponding data structures.
Python
The data is stored in Numpy arrays. Then, basic data structures (sysc.OutputIntegerData
and sysc.OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (sysc.NodeData
, sysc.ElementTypeData
, and sysc.ElementNodeConnectivityData
). Finally, the intermediate structures are used to create the sysc.SurfaceMesh
object.
Face-Based Surface Mesh Example
Figure 15 shows a sample surface mesh, with each node and face labelled. Note that in this example, there are quadrilateral, trilateral, and polygon faces. Also note that node ids are not contiguous.
Figure 15: Surface Mesh Face-Based Format Example
Due to the presence of the polygon faces, the face-based mesh format is more suitable for this example. To describe the mesh in this example, the following structures are required:
- Node data
- Element node count data
- Element-to-node connectivity data
Node Data
If providing node ids, node coordinates must be provided in the same order as node ids:
If node ids are ommitted, then the node coordinates must be provided in ascending node id order. Note that the actual node ids would be provided via the element-to-node connectivity data (see below).
When providing solution data on nodes, the ordering of the solution data must be consistent with the ordering of the node coordinates.
Element Node Count Data
Note that when providing solution data on elements (faces), the ordering of the solution data must be consistent with the ordering of the elements in this element node count data structure.
Element-to-Node Connectivity Data
Note that the element-to-node connectivity contains the same node ids that are defined in the node data structure. If the node ids are omitted from the node data structure, then they are deduced from this element-to-node connectivity data structure.
C++
The data is stored in STL vector structures. Then, basic data structures (sysc::OutputIntegerData
and sysc::OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (sysc::NodeData
, sysc::ElementNodeCountData
, and sysc::ElementNodeConnectivityData
). Finally, the intermediate structures are used to create the sysc::SurfaceMesh
object.
C
The data is stored in C arrays. Then, basic data structures (SyscOutputIntegerData
and SyscOutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (SyscNodeData
, SyscElementNodeCountData
, and SyscElementNodeConnectivityData
). Finally, the intermediate structures are used to create the SyscSurfaceMesh
object.
Note the helper functions syscGetNodeDataIC
, syscGetElementNodeCountData
, syscGetElementNodeConnectivityData
, and syscGetSurfaceMeshNCI
used to create the corresponding data structures.
Fortran
The data is stored in Fortran arrays. Then, basic data structures (SyscOutputIntegerDataF
and SyscOutputVectorDataF
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (SyscNodeDataF
, SyscElementNodeCountDataF
, and SyscElementNodeConnectivityDataF
). Finally, the intermediate structures are used to create the SyscSurfaceMeshF
object.
Note the helper functions syscGetNodeDataF
, syscGetElementNodeCountDataF
, syscGetElementNodeConnectivityDataF
, and syscGetSurfaceMeshF
used to create the corresponding data structures.
Python
The data is stored in Numpy arrays. Then, basic data structures (sysc.OutputIntegerData
and sysc.OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (sysc.NodeData
, sysc.ElementNodeCountData
, and sysc.ElementNodeConnectivityData
). Finally, the intermediate structures are used to create the sysc.SurfaceMesh
object.
Element-Based Volume Mesh Example
Figure 16 shows a sample volume mesh, with each node and element labelled. The coordinates are also shown for each node.
In the example, there are 12 nodes and 3 elements.
Elements 2 and 3 are wedge elements (they each have 6 nodes), while element 1 is a hexahedral element (it has 8 nodes).
Figure 16: Volume Mesh Element-Based Format Example
Since there are no polyheral elements, the element-based mesh format is suitable for this example.
Node Data
If providing node ids, node coordinates must be provided in the same order as node ids. If node ids are ommitted, then the node coordinates must be provided in ascending node id order. Note that the actual node ids are going to be provided via the element-to-node connectivity data (see below).
When providing solution data on nodes, the ordering of the solution data must be consistent with the ordering of the node coordinates.
Element Type Data
Element Type data structure is used to specify the type of each element.
Relevant element types are shown in Figure 7 and Figure 9 above. Hexahedral element types are assigned the value of 11, while wedge element types are assigned the value of 13.
Note that when providing solution data on elements, the ordering of the solution data must be consistent with the ordering of the elements in this element node count data structure.
Element-to-Node Connectivity Data
Element-to-Node Connectivity data structure is used to specify element-to-node connectivity. Note that the node ordering must be consistent with what is shown in Figures 7 and 9.
C++
The data is stored in STL vector structures. Then, basic data structures (sysc::OutputIntegerData
and sysc::OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (sysc::NodeData
, sysc::ElementTypeData
, and sysc::ElementNodeConnectivityData
. Finally, the intermediate structures are used to create the sysc::VolumeMesh
object.
C
The data is stored in C arrays. Then, basic data structures (SyscOutputIntegerData
and SyscOutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (SyscNodeData
, SyscElementTypeData
, and SyscElementNodeConnectivityData
. Finally, the intermediate structures are used to create the SyscVolumeMesh
structure.
Note the helper functions syscGetNodeDataC
, syscGetElementTypeData
, syscGetElementNodeConnectivityData
, and syscGetVolumeMeshElementBased
used to create the corresponding data structures.
Fortran
The data is stored in Fortran arrays. Then, basic data structures (SyscOutputIntegerDataF
and SyscOutputVectorDataF
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (SyscNodeDataF
, SyscElementTypeDataF
, and SyscElementNodeConnectivityDataF
). Finally, the intermediate structures are used to create the SyscVolumeMeshF
object.
Note the helper functions syscGetNodeDataF
, syscGetElementTypeDataF
, syscGetElementNodeConnectivityDataF
, and syscGetVolumeMeshF
used to create the corresponding data structures.
Python
The data is stored in Numpy arrays. Then, basic data structures (sysc.OutputIntegerData
and sysc.OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (sysc.NodeData
, sysc.ElementTypeData
, and sysc.ElementNodeConnectivityData
). Finally, the intermediate structures are used to create the sysc.VolumeMesh
object.
Face-Based Volume Mesh Example
Figure 17 shows a sample volume mesh, with each node and cell labelled. The coordinates are also shown for each node.
In the example, there are 16 nodes, 16 faces, and 3 cells.
Cells 2 and 3 are hexahedral elements (they each have 6 faces and 8 nodes), while cell 1 is a polyhedral element (it has 7 faces and 10 nodes).
13 out of the 16 faces are external, that is they are connected to a cell only on one side. The remaining 3 faces are internal - they are shared between two cells: one face is shared between cells 2 & 3, one face is shared between cells 1 & 2, and one face is shared between cells 2 & 3.
Figure 17: Volume Mesh Face-Based Format Example
Due to the presence of the polyheral cell, the face-based mesh format is more suitable for this example.
Node Data
If providing node ids, node coordinates must be provided in the same order as node ids. If node ids are ommitted, then the node coordinates must be provided in ascending node id order. Note that the actual node ids are going to be provided via the face-to-node connectivity data (see below).
When providing solution data on nodes, the ordering of the solution data must be consistent with the ordering of the node coordinates.
Element Node Count Data
Element Node Count data structure is used to specify node counts for each face.
Element-to-Node Connectivity Data
Element-to-Node Connectivity data structure is used to specify face-to-node connectivity. Note that for the 13 boundary faces (faces that are not shared between two cells), the orientation is such that side 0 is on the inside of the mesh and side 1 is on the outside.
Face-to-Cell Connectivity Data
Face-to-cell connectivity data specifies which cells are connected to each face. Note that if there is no cell connected to the face on a side, then the corresponding entry in the array is 0.
Cell Id Data
Cell ids must be explicitly provided via the Cell Id data structure. Note that when providing solution data on elements (cells), the solution data ordering must be consistent with the cell id data.
C++
The data is stored in STL vector structures. Then, basic data structures (sysc::OutputIntegerData
and sysc::OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (sysc::NodeData
, sysc::ElementNodeCountData
, sysc::ElementNodeConnectivityData
, sysc::FaceCellConnectivityData
, and sysc::CellIdData
). Finally, the intermediate structures are used to create the sysc::VolumeMesh
object.
C
The data is stored in C arrays. Then, basic data structures (SyscOutputIntegerData
and SyscOutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (SyscNodeData
, SyscElementNodeCountData
, SyscElementNodeConnectivityData
, SyscFaceCellConnectivityData
, and SyscCellIdData
). Finally, the intermediate structures are used to create the SyscVolumeMesh
structure.
Note the helper functions syscGetNodeDataC
, syscGetElementNodeCountData
, syscGetElementNodeConnectivityData
, syscGetFaceCellConnectivityData
, syscGetCellIdData
, and syscGetVolumeMeshFaceBased
used to create the corresponding data structures.
Fortran
The data is stored in Fortran arrays. Then, basic data structures (SyscOutputIntegerDataF
and SyscOutputVectorDataF
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (SyscNodeDataF
, SyscElementTypeDataF
, SyscElementNodeConnectivityDataF
, SyscFaceCellConnectivityDataF
, and SyscCellIdDataF
). Finally, the intermediate structures are used to create the SyscVolumeMeshF
object.
Note the helper functions syscGetNodeDataF
, syscGetElementNodeCountDataF
, syscGetElementNodeConnectivityDataF
, , syscGetFaceCellConnectivityDataF
, syscGetCellIdDataF
, and syscGetVolumeMeshF
used to create the corresponding data structures.
Python
The data is stored in Numpy arrays. Then, basic data structures (sysc.OutputIntegerData
and sysc.OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the intermediate structures (sysc.NodeData
, sysc.ElementNodeCountData
, sysc.ElementNodeConnectivityData
, sysc.FaceCellConnectivityData
, and sysc.CellIdData
). Finally, the intermediate structures are used to create the sysc.VolumeMesh
object.
Point Cloud
Point cloud regions are collections of points (or nodes) with unspecified connectivities. To define a point cloud, node ids and node coordinates must be provided.
Point Cloud Example
This example shows how to create a point cloud that contains two nodes - one at the origin of the coordinate system (0, 0, 0) and another one at coordinates (1, 1, 1).
C++
The data is stored in STL vector structures. Then, basic data structures (sysc::OutputIntegerData
and sysc::OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the sysc::PointCloud
object.
C
The data is stored in C arrays. Then, basic data structures (SyscOutputIntegerData
and SyscOutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the SyscPointCloud
object.
Note the helper function syscGetPointCloud
used to create the point cloud structure.
Fortran
The data is stored in Fortran arrays. Then, basic data structures (SyscOutputIntegerDataF
and SyscOutputVectorDataF
) are created to pass these arrays to System Coupling. The basic structures are then used to create the SyscPointCloudF
object.
Note the helper function syscGetPointCloudF
used to create the point cloud structure.
Python
The data is stored in Numpy arrays. Then, basic data structures (sysc.OutputIntegerData
and sysc.OutputVectorData
) are created to pass these arrays to System Coupling. The basic structures are then used to create the sysc.PointCloud
object.