- Generated by
1.9.5
|
FEAT 3
Finite Element Analysis Toolbox
|
This page describes the structure of the XML-based FEAT mesh file format and gives some important insights into the terminology and the internal definition of the topologies managed by the mesh classes of FEAT.
FEAT supports both hypercube (quadrilateral & hexahedral) and simplex (triangular & tetrahedral) meshes in arbitrary dimensions, but it does support not hybrid meshes containing both cell types at the same time. In consequence, the FEAT mesh file format also only supports meshes of a single cell type.
In the context of meshes, the following topological terms are commonly used in FEAT and throughout this page:
In FEAT, topological entities are typically referenced by their topological dimension rather than their names ("edge", "triangle", etc), which is unambiguous and more consistent between hypercube and simplex meshes, which is possible because FEAT does not support hybrid meshes anyways.
A mesh is defined by
In the context of meshes, the following dimension terms are used:
Usually, the shape and world dimensions are identical, however, if a mesh discretizes a surface of an object rather than the object itself, e.g. in the FEM-on-manifolds scenario, then the world dimension is greater than the shape dimension. However, the world dimension of a mesh can never be less than its shape dimension.
The root mesh (see Mesh XML Node Description) is a disambiguation term used for the main mesh defined by the file, which is used to discretize the computational domain that a simulation is to be performed on.
A mesh-part (see MeshPart XML Node Description) represents a named and possibly parameterized sub-set of the topological entities of root mesh. Mesh-parts are used to identify certain regions of interest such as boundary regions.
A chart (see Chart XML Node Description) is a description of a boundary, e.g. by an analytic description or even a discrete surface triangulation.
A partitioning (see Partition XML Node Description) is a splitting of the root mesh into several patches, which can be used in an MPI parallel simulation to distribute the domain among the MPI processes.
This section describes the topology ordering for the four supported 2D and 3D shapes, namely triangles, quadrilaterals, tetrahedra and hexahedra. In principle, FEAT also supports higher dimensional shapes of simplex and hypercube type, however, some parts of the mesh management classes are missing specializations for higher-dimensional shapes, so the documentation of the corresponding higher-dimensional topologies is omitted here.
The ordering of the triangle topology is as follows:
The ordering of the quadrilateral topology is as follows:
The ordering of the tetrahedron topology is as follows:
The ordering of the hexahedron topology is as follows:
This section describes both the explicit and implicit boundary parameterization mechanisms used in FEAT based on charts (see Chart XML Node Description) and mesh-parts (see MeshPart XML Node Description).
Mesh-parts can be used (amongst other things) to represent the boundary (or a part thereof) of the root mesh that it is defined on and mesh-parts may furthermore be linked to a specific chart that describes the boundary of the analytical domain that the mesh discretizes/approximates. Once a mesh gets refined by FEAT's mesh management classes (namely the FEAT::Geometry::RootMeshNode class), all of its mesh-parts are also refined and (unless otherwise specified by the user) all mesh-parts, which are linked to charts, will be used to adapt the root mesh by moving the newly created boundary vertices onto the boundary of the analytical domain.
As already hinted above, there exist two mechanisms in FEAT to perform this task of boundary adaption: explicit and implicit boundary parameterization. The decision which of these two mechanisms is chosen by the mesh management classes depends the following various factors, namely:
"param" attribute that specifies the boundary vertex parameters?If all of the above points are met, then the boundary adaption is performed by explicit parameterization, otherwise the it is performed by implicit parameterization. See the next two sub-sections for details.
Boundary adaption by explicit parameterization is best explained by an example, so we will have a closer look at the main contents of the unit_circle_tria_4.xml mesh file. This mesh discretizes the 2D unit-circle by four triangles:
The mesh file contains a chart named "outer" that represents the (red) circle of radius 1 around the midpoint (0,0) and furthermore it states that the circle is parameterized by the parameter range [0,4], where both the start-point 0 and the end-point 4 of the parameter range coincide with the East point on the circle (i.e. the point with the maximum X coordinate), which is marked by a small dash in the image above. For the exact parameterization formula, see 2D Circle Parameterization.
Next in the mesh file comes the actual root mesh with 5 vertices (center vertex first) , 8 edges (inner edges first) and the four triangles:
Finally, there is the one and only mesh-part named "bnd:o" that is linked to the chart named "outer" that we have seen above and this mesh-part also contains the full topology of the mesh-part, which is required for the computation of the vertex parameters as we will see below.
We need to specify parameter attributes for each vertex in the mesh-part (at least if we want to make use of explicit parameterization) and because this mesh-part discretizes the entire closed 2D boundary and not just an open part of it, we have to use a "life hack" and specify one of the vertices twice, because we need two assign two different parameters for them (you will see below why). We pick the upper right vertex, which is vertex number 1 in the root mesh, to be the one that is contained twice in the mesh-part; all other boundary vertices are contained in the mesh-part only once:
Next comes the list of all root mesh boundary edges, there's nothing particularly interesting here:
Now comes the topology of the mesh-part, which describes for each mesh-part edge which mesh-part vertices form that mesh-part edge; keep in mind that vertex 0 and 4 in this mesh-part actually refer to the same vertex 1 in the root mesh:
Finally comes the "param" attribute for this mesh-part, which specifies the parameters of each mesh-part vertex with respect to the explicit parameterization of the chart that this mesh-part is linked to. Because our circle chart has been defined on the domain [0,4] and the endpoints 0 and 4 coincide to the East point on the circle, the parameter for the upper right vertex in the mesh (which is contained twice in this mesh-part) can be chosen as 4*N+0.5 for any integer N, so we (arbitrarily) pick N=0 and thus 0.5 as the parameter for the first mesh-part vertex, which is the upper-right vertex in the root mesh, and then we assign the parameters 1.5, 2.5 and 3.5 counter-clockwise to the corresponding vertices accordingly. Finally, the second instance of the upper-right vertex gets assigned the parameter 4.5, which is equivalent to the parameter 0.5 that we have chosen for the first instance for the same root mesh vertex:
After the root mesh has been refined, the mesh management class will also refine all mesh-parts accordingly, and initially all newly created vertices are placed at the centers of the edges that spawned them (or the centers of faces or volumes, respectively). In the next step, the attributes of the mesh-parts are interpolated linearly from the attributes of the coarse mesh and this is where the mesh-part topology is required, because it specifies the mesh-part vertices for each mesh-part edge that are used to interpolate the new vertex parameter attributes from.
Consider the top edge in the image above: this edge number 1 of the mesh part (which corresponds to edge number 4 in the root mesh) and the topology of the mesh-part states that the this mesh-part edge is formed by the mesh-part vertices 0 and 1 (which correspond to vertices 1 and 2 in the root mesh, respectively). The parameter for mesh-part vertex 0 is 0.5 and the parameter for mesh-part vertex 1 is 1.5, so the interpolated midpoint parameter is 1.0 and this is what is assigned as a parameter to the newly created vertex on the midpoint of that top edge. Analogously, the new vertices on the left and bottom edge are assigned the parameters 2.0 and 3.0 by interpolating the edge vertex parameters. Finally, the right mesh-part edge is formed by the mesh-part vertices 3 and 4 (which correspond to vertices 4 and 1 in the root mesh, respectively) which have the parameters 3.5 and 4.5 assigned to them, respectively, so the parameter of the newly spawned vertex on the right edge is 4.0 (which is equivalent to 0.0 for our circle chart).
Now that all mesh-part vertex parameters are known, the management classes will use the chart class to explicitly compute the new vertex coordinates of all the root mesh vertices based on their parameters by using the parameterization formula of the corresponding chart, and we finally obtain the boundary adapted mesh:
Not all chart types offer the possibility to explicitly parameterize the boundary, e.g. the Sphere chart (see 3D Sphere Chart Description) or the SurfaceMesh chart (see 3D SurfaceMesh Chart Description), but all chart classes are mandated to offer an implicit boundary adaption method, which can be used to project newly created vertices onto the analytical boundary by some sort of orthogonal projection or closest-point projection.
There is nothing special to considered for the implicit parameterization from the mesh file point of view, because all that is required is a mesh-part with a mapping of all boundary vertices, edges and (in 3D) faces and that is linked to a chart, but no mesh-part topology, no mesh-part parameter attributes are required; the mesh management classes will automatically ask the chart to project all vertices contained in the mesh-part onto the boundary by whatever means the chart implements to accomplish this task.
FEAT meshes are stored in XML format containing the root mesh itself (consisting of its vertex coordinates and its mesh topology), boundary descriptions, mesh parts and partitionings. FEAT mesh files do not need to be self-contained, i.e. it is possible to split the individual parts (i.e. the root mesh, the charts, the mesh-parts and partitioning) across several files which are then passed together as a set of input files to the FEAT::Geometry::MeshFileReader or the FEAT::Control::Domain::PartiDomainControl classes.
The overall mesh file structure looks as follows:
FeatMeshFile
+- Info
+- Chart
| +- Circle
| +- Sphere
| +- Bezier
| | +- Points
| | +- Params
| +- SurfaceMesh
| | +- Vertices
| | +- Triangles
| +- Extrude
| +- Circle
| +- Bezier
+- Mesh
| +- Vertices
| +- Topology
+- MeshPart
| +- Mapping
| +- Topology
| +- Attribute
+- Partition
+- Patch
The most simple example of a 2D unit-square mesh file without any optional features is this:
<!-- This is an XML comment. -->Info node for remarks and comments instead, see Info XML Node Description. Multi-line XML comments are not supported and will lead to parser errors.The meshtype value is a string consisting of four tokens joined by colons:
<class>:<shape>:<shape-dim>:<world-dim>
where:
<class> is the mesh class: Currently, the only valid option is "conformal", which represents an unstructured conformal mesh with no hanging nodes.<shape> is the shape-type of the mesh elements: This must be one of the following:simplex if the elements are simplices (triangles, tetrahedra)hypercube if the elements are hypercubes (quadrilateral, hexahedra)<shape-dim> is the shape dimension of the mesh elements:2 for 2-dimensional shapes (triangles, quadrilaterals)3 for 3-dimensional shapes (tetrahedra, hexahedra)<world-dim> is the world dimension of the mesh, i.e. the number of coordinates per vertex<world-dim> is always equal to <shape-dim>, unless this is a surface mesh, in which case it is greater than <shape-dim>Examples: Although the FEAT mesh file format (and most of FEAT's internal mesh management classes) can also handle meshes of higher dimensions, the following mesh types are the ones that are currently being used in applications:
"conformal:hypercube:1:1" represents a 1D mesh (technically treated as an unstructured conformal mesh)"conformal:hypercube:1:2" represents a 1D mesh embedded in 2D (technically treated as an unstructured conformal mesh)"conformal:hypercube:1:3" represents a 1D mesh embedded in 3D (technically treated as an unstructured conformal mesh)"conformal:hypercube:2:2" represents a 2D unstructured conformal quadrilateral mesh"conformal:hypercube:2:3" represents a 2D unstructured conformal quadrilateral surface mesh embedded in 3D"conformal:hypercube:3:3" represents a 3D unstructured conformal hexahedral mesh"conformal:simplex:2:2" represents a 2D unstructured conformal triangular mesh"conformal:simplex:2:3" represents a 2D unstructured conformal triangular surface mesh embedded in 3D"conformal:simplex:3:3" represents a 3D unstructured conformal tetrahedral mesh"conformal:simplex:1:x" is not a valid mesh type for any value of x; this is purely by convention to avoid having two incompatible definitions of a 1D mesh.The root node of all valid FEAT mesh files is the FeatMeshFile node.
The root node can contain the following attributes:
1The meshtype attribute is optional and, if given, specifies the type of the root mesh that is stored in the mesh file. See Mesh Type Specification for possible values for this attribute. This attribute is optional, because not all mesh files actually contain a root mesh, as they may just store charts, mesh-parts or partitions.
mesh2vtk tool) may require this attribute to choose the correct execution path.In the most simple case, the root node is merely
If the mesh file contains a 2D quadrilateral mesh, then the root node would be
Each mesh file may contain an optional multi-line Info node, which contains a block of arbitrary remarks or information about the file and/or its contents. The Info node is ignored by the mesh file reader.
Example:
Charts are descriptions of geometric object like circles, spheres or splines, which are often used for parameterization of domain boundaries or fictitious boundaries within the domain.
Each chart is embedded in a separate Chart node, whose one and only attribute is the mandatory name attribute, which specifies the unique name of the chart. See the following subsections for examples of this node.
The most simple chart is the Circle chart, which represents a simple 2D circle object.
The Circle chart supports the following attributes:
The domain attribute is required for explicit boundary parameterization (see Boundary Adaption by Explicit Parameterization); without it the Circle chart only supports implicit boundary parameterization.
Let \(m_x, m_y\) denote the coordinates of the circle midpoint, \(r\) the circle radius and \(d_L, d_R\) the left and right domain interval borders, then the parameterization of the circle is defined as follows:
\[\alpha(t) := \frac{2\pi\cdot(t-d_L)}{d_R-d_L}\]
\[t \mapsto \begin{bmatrix} m_x + r\cdot\cos(\alpha(t))\\ m_y + r\cdot\sin(\alpha(t))\end{bmatrix}\]
See Boundary Adaption by Explicit Parameterization for a practical example of how this parameterization is used for the adaption of boundary vertices.
A (unparameterized) circle of radius 0.2 around the midpoint (0.5, 1.0) named "myCircle" would be defined by:
A circle of radius 1 around the midpoint (0.7, 0.2) parameterized by the interval [0, 2]:
The Sphere chart is the 3D analogon of the Circle chart, which represents a 3D sphere object.
The Sphere chart supports the following attributes:
The Sphere chart only supports implicit boundary parameterization.
A sphere of radius 0.2 around the midpoint (0.5, 1.0, 0.7) named "mySphere" would be defined by:
The Bezier chart represents a 2D Bezier-Spline (aka "Polybezier" aka "composite Bezier curve"), which can be used to describe quite complex objects by a continuous composition of Bezier curves of possibly varying degree.
Terminology:
The Bezier chart contains the following attributes:
Each Bezier chart must contain a child node named Points which encapsulates the coordinates of the vertex and control points, see Bezier Points for details.
Furthermore, a Bezier chart may also be parameterized. In this case, the spline needs an additional child node named Params, which encapsulates the 1D parameters for the vertex points of the Spline, see Bezier Parameters for details.
The Points node itself has no attributes, and its contents specify both the vertex points and the control points of the Spline. Each line corresponds to a single Bezier segment, which consists of all control points following the previous vertex point as well as the end vertex point of the segment, encoded in the following way:
\[ n~ c^1_x~ c^1_y~ c^2_x~ c^2_y~ ...~ c^n_x~ c^n_y~ v_x~ v_y\]
where
A Bezier chart may also be explicitly parameterized. In this case, the Bezier node contains a child node named Params, which contain the 1D parameter values of the vertex points. Without this Param sub-node, the Bezier chart only support implicit boundary parameterization.
A Bezier spline representing a simple line segment from (0.1, 0.5) to (0.7, 0.2) would be:
A (closed) Bezier spline representing the polyline forming the boundary of the unit-square [0,1] x [0,1], equidistantly parameterized over the 1D domain [0,4]:
Consider the (open) cubic Bezier curve spanned by the four points (0.1, 0.2), (0.3, 0.1), (0.5, 0.1) and (0.7, 0.3). This curve has two vertex points (the first and the last one) as well as two (inner) control points between the two vertex points, so in our encoding the two control points "belong" to the second vertex point, whereas the first vertex point has no control points:
A cubic Bezier spline with three vertex points (0, -0.5), (1, -0.2), (2, -0.5) and two (inner) control points for each of the two segments, equidistantly parameterized over the 1D domain [0,1]:
The SurfaceMesh chart represents a surface triangulation of a 3D object.
A SurfaceMesh has the following attributes:
The definition of a SurfaceMesh is pretty straight forward: it only contains two child nodes named Vertices and Triangles, which contain the vertex coordinate triplets and the triangle vertex index triplets, respectively.
The SurfaceMesh chart only supports implicit boundary parameterization.
A surface triangulation of the 3D unit cube [0,1] x [0,1] x [0,1] consisting of 8 vertices and 12 triangles:
The Extrude chart is a wrapper chart, which "converts" a 2D chart into a 3D chart by extruding it infinitely in positive and negative Z-direction.
The Extrude chart supports the following 2D child charts:
Circle, see 2D Circle Chart DescriptionBezier, see 2D Bezier Chart DescriptionThe Extrude chart supports explicit boundary parameterization if and only if its child Circle or Bezier chart supports its; but the Extrude chart always supports implicit boundary parameterization.
The Extrude chart supports the three attributes origin, offset and angles to define a "proper rigid
transformation" (a transformation that consists only of translations and rotations) for the extruded chart. The transformation consists of two translation vectors v and w as well as a 3D rotation matrix R, which define the following transformation mapping:
\[ x \mapsto w + R \cdot(x - v)\]
Each of the three components is optional and can be specified by the following attributes:
origin: specifies the X- and Y-coordinates of the origin vector v, separated by white-spacesoffset: specifies the X-, Y- and Z-coordinates of the offset vector w, separated by white-spacesangles: specifies the yaw, pitch and roll angles of the rotation matrix R, separated by white-spacesExtruding a 2D Circle chart effectively yields a 3D cylinder:
The CGALSurfaceMesh chart represents a surface triangulation of a 3D object very similar to the SurfaceMesh chart, but is handled by the CGAL third-party package.
filename (mandatory): specifies the absolute path to the file that contains the geometric surface data. Has to be either an off or an obj file.
The Mesh node defines the actual root mesh, i.e. the mesh that is used for the domain discretization.
Mesh XML node, otherwise it is ill-formed.A Mesh node has the following attributes:
A mesh is defined by two mandatory sets of information:
The Vertices child node specifies the set of all vertices of the mesh.
This node does not have any attributes because:
Each content line of the Vertices node specifies the coordinate tuple for one vertex, separated by white-spaces.
See Mesh Examples for examples.
Each Topology child node specifies the topology for one entity dimension, i.e. the index tuple of all vertices adjacent to one entity (edge, triangle, etc).
The Topology node has one mandatory attribute dim, which specifies the dimension of the entities that the Topology refers to.
Topology sub-node for each entity dimension > 0, otherwise the mesh file is ill-formed!See Mesh Examples for examples.
The following example shows the definition of the unit-square mesh consisting of 4 vertices, 4 edges and 1 quadrilateral:
The following example shows the definition of the unit-circle mesh consisting of 5 vertices, 8 edges and 4 triangles:
The following example shows the definition of the unit-cube mesh consisting of 8 vertices, 12 edges, 6 quadrilaterals and 1 hexahedron:
Mesh-parts are used to represent certain regions of interest of the root mesh such as e.g. boundary regions. In the most simple case, a mesh-part consists only of a list of vertices, edges, etc. of the root mesh that are assigned to that mesh-part. In more complex cases, mesh parts may have their own topology as well as sets of attributes that are assigned to the mesh-part's vertices and can be used for e.g. boundary parameterization.
A MeshPart node has the following attributes:
"root"."none": the mesh part does not have a topology"full": the full topology for the mesh-part is explicitly given"parent": the full topology is deducted automatically from the parent meshA Mapping child node specifies the (root) mesh entities of a particular dimension that belong to the particular mesh-part.
A Mapping child node has only one mandatory attribute dim, which specifies the entity dimension that this Mapping node refers to.
Each content line of a Mapping node contains the index of a single root mesh entity of the given dimension that is contained in this mesh part. Note that the indices don't need to be in any particular order. The number of entities in a Mapping node is given in the size attribute of the MeshPart node.
In analogy to the root mesh, also mesh-parts may have a topology defined on its entities. If the topology attribute of the MeshPart node is set to full, then the topology is specifies just the same way as for the root mesh.
MeshPart node is set to parent, then the topology must not be specified explicitly by using Topology nodes, but it is automatically derived from the root mesh instead.An Attribute node specifies a set of values (called attributes) assigned to the vertices of a mesh-part.
MeshPart node has at least one Attribute node, then it must specify a topology for the mesh-part. The topology may be either given explicitly or it may be derived from the root-mesh.An Attribute node has two attributes:
One special case of an attribute is the parameterization, which is represented by the name param, which is used to define the (root mesh) vertex coordinates via the chart that the mesh-part is assigned to.
Another application of mesh-part attributes is the specification of certain properties for the mesh-part, e.g. a temperature distribution on a boundary part described by that mesh-part.
See Boundary Adaption by Explicit Parameterization for a practical example of how the param attribute is used for the adaption of boundary vertices.
The following example shows a mesh-part named bnd:t that consists of the two root-mesh vertices 3 and 2 as well as the root-mesh edge 1. This mesh-part is not assigned to any chart and does not have a topology. This mesh-part could be used for the 2D Quadrilateral Unit-Square root mesh to represent the top boundary edge of the mesh.
The following example mesh-part represents the parameterized boundary mesh-part of the 2D Triangle Unit-Circle root mesh. This mesh-part contains four vertices, where the first one is stored duplicated for the parameterization, thus the total number of vertex indices is 5. The mesh-part contains all four boundary edges of the mesh.
A Partition node specifies a partitioning of the root mesh into a number of patches aka sub-domains aka partitions.
A Partition node has the following attributes:
--parti-extern-name command line parameter.A Patch node specifies the elements that belong to a specific patch/partition/sub-domain/process.
A Patch node has the following attributes:
Each line of the Patch node specifies the index of one element that belongs to this patch.
The following partition is defined on the 2D Triangle Unit-Circle and subdivides the domain into 2 patches with 2 elements each.
The following partition is defined on the once refined 2D Quadrilateral Unit-Square and subdivides the domain into 2 patches with 2 elements each.
1.9.5