 |
GemaMesh
The GeMA Mesh Plugin
|
|
GemaMesh
The GeMA Mesh Plugin
|
The GemaMesh plugin publishes three main object types that can be used while providing the mesh type name. They are:
Besides, three additional object types, GemaMesh.nodesd, GemaMesh.celld and GemaMesh.elemd are available. Their capabilities are exactly the same as their "no d" brothers. The difference is that mesh data storage is specially tailored for situations where new nodes and cells will be continuouslly added to the mesh in an incremental way during the simulation. For the "d" types, a dual vector structure is adopted. The first part stores the, fixed, original mesh data, while the incrementally added nodes, cells and their data are stored at the second part. With the said partition, only the (hopefully small) second vectors need to be grown as new cells are added to the mesh. The cost of this separation is the need for a behind the scenes conditional clause to check which part of the vector should be used when accesing data.
When defining a Gema Mesh object, the following fields are available for usage during the definition:
| Attribute | Description | Type | Required |
|---|---|---|---|
| id | The mesh name. | String | Yes |
Example: id = "myMeshName" | |||
| typeName | Mesh plugin name. Should be equal to 'GemaMesh.xxx', where xxx = nodes, cell or elem. | String | Yes |
Example: typeName = "GemaMesh.elem" | |||
| description | An optional description of the mesh purpose. | String | No |
Example: description = "Discretized 100x100 plate" | |||
| dumpFile | If this option is given, the mesh geometry and initial values will be loaded from the given dump file. The file stored mesh must have the same meta-data as the one described in this mesh. In particular, the set of state-variables, attribtes and property sets must be the same. See comments on the State dump documentation. When using this option, the nodeData, ghostData, cellData, nodeSetData, boundaryEdgeData and boundaryFaceDatafields should not be filled since their contents will be read from the dump file. This can greatlly speed up the mesh loading process. | String | No |
Example: dumpFile = "$SIMULATIONDIR/$SIMULATIONNAME.dmp" | |||
| coordinateDim | The number of dimensions for each node coordinate. Should be a value equal to 1, 2 or 3. | Integer | Yes |
Example: coordinateDim = 2 | |||
| coordinateUnit | The optional unit in which node coordinates are expressed. The default value is the empty string, which is compatible with any unit system. See also the documentation on Working with units. | String | No |
Example: coordinateUnit = "m" | |||
| coordinateFormat | This optional field controls how coordinate values will be formatted when printed or saved to a text file format. It uses a subset of the C printf() syntax, allowing the user to specify the field width, precision and format type. A format = "8.2f" statement means that the formatted value will have at least 8 characters and 2 decimal values. Allowed format specifiers are 'f' (for decimal floating point format), 'e' (for scientific notation format) and 'g' (corresponding to 'f' or 'e', whichever is shortest). Default = "12.2f". | String | No |
Example: coordinateFormat = "6.3f" | |||
| topology | An optional flag that when set to true instructs GeMA to build the additional data structure used for topological queries just after loading the mesh data. Setting this flag to true is not needed for performing topological queries since the structure will be built at the first time that it is needed, but can make sure that it is built in a more predictable moment. | Boolean | No |
| topologyBuildEdgeMap | An optional flag that when set to true instructs GeMA to include an "edge -> half-face" map in the topological structure for solid meshes. This map is used by edge queries performed over solid meshes (but is not required for them to work). Since it consumes much more memory than the whole rest of the structure, it is not created by default. | Boolean | No |
| singleCellType | An optional flag that when set to true tells GeMA that all the mesh cells have a single type, and more importantly, that no cells with a different type will be added later to the mesh. This has an effect of allowing GeMA to perform some space optimizations when creating the topological data structure. If this flag is set to true, an error will be raised if an attempt is made to add a new cell to the mesh with type different from the existing cells. | Boolean | No |
| useGhostNodes | An optional flag controlling if the mesh supports ghost nodes or not. If set to false, no support for ghost nodes will exist for state variables and node attributes tied to this mesh, even if they request so through the storage field. Default = false. | Boolean | No |
Example: useGhostNodes = true | |||
| hOrder | A table that should be filled only when the mesh contains hierarchical elements, such as hquadp or hhexp. When given, it should be a table with fields P and Q, storing, respectively, the requested polynomial orders for scalar and vector fields. This option automatically implies in useGhostNodes = true. Keep in mind that although meshes can store heterogeneous elements, all of them must be either hierarchical or not. Mixing them is not possible. | Table | No |
Example: hOrder = {P = 3, Q = 2} | |||
| stateVars | A table with the list of the ids of the state variables that will be stored in each mesh node. Although optional (a mesh can be created without being associated with state variables), it is required by most physics plugins. | Table | No |
Example: stateVars = { "u", "p" } | |||
| cellProperties | A table with the list of the ids of the property sets that will be associated with this mesh. Each mesh cell / element will store a line index for each associated property set. Ignored for node meshes. Although optional for cell and element meshes, (a mesh can be created without being associated with a property set), it is required by most physics plugins. | Table | No |
Example: cellProperties = { "MateriaPropertySet" } | |||
| nodeAttributes | An optional table with the definition of the attributes associated with mesh nodes. Each table entry is a sub-table with a node attribute defintion following the syntax described in the Data options page. | Table | No |
Example: nodeAttributes = { { id = "nodeAttr1", description = "Sample scalar node attribute", unit = "g/cm3" }, { id = "nodeAttr2", dim = 2, description = "Sample vector node attribute" }, } | |||
| cellAttributes | An optional table with the definition of the attributes associated with mesh cells / elements. Each table entry is a sub-table with a cell attribute defintion following the syntax described in the Data options page. Ignored for node meshes. | Table | No |
Example: cellAttributes = { { id = "cellAttr1", description = "Sample scalar cell attribute", unit = "g/cm3" }, { id = "cellAttr2", dim = 2, description = "Sample vector cell attribute" }, } | |||
| gaussAttributes | An optional table with the definition of the attributes associated with mesh element integration points. Each table entry is a sub-table with a Gauss attribute defintion following the syntax described in the Data options page. When working with multiple integration rules, don't forget to specify the desired ruleSet. Ignored for node and cell meshes. | Table | No |
Example: gaussAttributes = { { id = "gaussAttr1", description = "Sample scalar Gauss attribute", unit = "g/cm3" }, { id = "gaussAttr2", dim = 2, description = "Sample vector Gauss attribute", ruleSet = 2 }, } | |||
| nodeData | A table storing node information for the mesh. This table has one sub-table for each node, storing, in this order, the node coordinates, optionally followed by node attribute and node state var initial values. See the Node data section below for details. Alternatively, this field can be a Lua function that when called without parameters returns the number of mesh nodes, and when called with an index 'i' returns the 'ith' node sub-table. The function will be called once without parameters and then once for each node ('i' varying from 1 to the number of nodes). It also supports receiving a table filled with several sub-tables, formated as above, that will be concatenated by the mesh loader as if they where a single node table. | Table or function | Yes |
Example: nodeData = { {0.0, 0.0}, {1.0, 0.0}, {2.0, 0.0}, {0.0, 1.0}, {1.0, 1.0}, {2.0, 1.0} } for a 2D mesh with 6 nodes where only the coordinates where initialized. See the global example below for a more elaborate scenario. | |||
| ghostData | A table (or function) similar to nodeData, storing ghost node coordinates, attributes and state var initial values. Attribute and state var values are optional. Details on the Node data section below are also applicable to ghostData. This field will be parsed only if useGhostNodes is true. | Table or function | No |
| Example: See the global example below for a more elaborate scenario. | |||
| cellData | A table storing cell types, conectivity information, groupings and initial attribute and property values. Each table entry is a sub-table storing information about a group of cells of the same type. Ignored for node meshes. It contains the following subfields: - cellType: A string defining the type of the cells stored in cellList for this entry. The mesh can contain elements with different types but they must be separated in different entries since all the elements in cellList must share the same type. - cellGroup: The optional name of the group that this cells belongs to. Different table entries with same group name are merged in the same group by the reader. - xxx: When 'xxx' equals the name of a property set included in cellProperties, this field value will be the default property index associated with cells in cellList that do not explicitly overrides this default. A property index can reference a property set line either by an integer index or an id name. If a mesh is associated with several property sets, in general it should include one default value for each property set, otherwise, that property set value MUST be provided for each cell in cellList since every cell must be connected with a property set line for each property set attached to the mesh. - cellList: The list of element conectivity, cell attribute initial values and property set index assignments. This list is a table with an entry for each cell of this cellType/cellGroup, containing, in this order, the set of node numbers that define the cell, respecting the cell type prescribed order, optionally followed by cell attribute initial values. Property set index values should be given by a named (property set, index) pair. They are optional only if a default association was included in the table that hosts this cell list. If useGhostNodes is set to true, a special key ghostNodes can optionally receive a table with a set of cell ghost node indices that will be included in the cell definition. See the Cell data section below for details. Alternatively, this subfield can be a Lua function that when called without parameters returns the number of mesh cells in this group, and when called with an index 'i' returns the 'ith' cell sub-table. The function will be called once without parameters and then once for each cell ('i' varying from 1 to the number of cells). | Table | Yes for cell and element meshes |
Example: cellData = { { cellType = "quad4", MaterialPropertySet = 1, cellList = {{1, 2, 5, 4}, {2, 3, 6, 5, MaterialPropertySet = 2}} } } for a mesh with only two cells in a single group, no cell initialization and a single property set. See the global example below for a more elaborate scenario. | |||
| elementRules | An optional table defining the set of available integration rule sets for this mesh elements. Each table entry is a sub-table with one rule set definition. Rule sets are used for defining the number of integration points used by FEM physics objects and for defining the number of Gauss points in a Gauss attribute. Each rule set consists in a set of pairs associating element type names with a rule that can be given as a number or a string. The value quad4 = 3, associates quad4 elements with a 3 x 3 element integration rule while quad4 = '3x2' to a anisotropic rule with 3 points along the element horizontal direction and 2 along its vertical direction. Similarly, hex8 = 3, associates hex8 elements with a 3 x 3 x 3 rule while hex8 = '3x4x5' to a anisotropic rule. An optional prefix letter can be used to specify the type of integration rule. Available options are G or g for Gauss rules, N, n, CN, cn, ON or on for closed or open Newton-Cotes rules (the N or n options are analogue to CN) and L or l for Lobatto rules. If this type specifier is missing, the default for the element type will be used (see the Element types documentation). If an element type is not present in the rule set, or an invalid rule is specified, its default rule will be assumed. It really only makes sense to add to a rule set element types used in the mesh. Also, keep in mind that rule sets are needed only when there is a desire to depart from the default rules for an elment type. Ignored for node and cell meshes. | Table | No |
Example: elementRules = { {quad4 = 2, tri3 = 1}, -- Rule set 1 {quad4 = 3, tri3 = 3}, -- Rule set 2 {quad4 = "L5x3", tri3 = "G3"}, -- Rule set 3 } | |||
| faceRules | An optional table, similar in purpose and following the same general syntax as elementRules, providing the rules used when integrating over an element face. Should include rules for 3D element types only. In general, this table size should be equal to the elementRules table size since they both reference the same rule set (when a physics object or a Gauss attribute specifies a rule set, it is selecting a row from both tables). If a rule set exists in one table and not in the other, the missing rule set will be considered as using default values for each type, so it is possible to have one table without the other. Ignored for node and cell meshes. For 3D elements with multiple face types, like a wedge6 whose faces can be either triangles or quadrilaterals, the element name should be suffixed with the face type name (either _quad or _tri) for defining the specific rule for each face type. | Table | No |
Example: faceRules = { {hex8 = "2x2", tet4 = 3, wedge6_quad = "2x2", wedge6_tri = 3}, -- Rule set 1 {hex8 = 3, tet4 = 6, wedge6_quad = 3, wedge6_tri = 6}, -- Rule set 2 } | |||
| edgeRules | An optional table, similar in purpose and following the same syntax as elementRules, providing the rules used when integrating over an element edge. Can include rules for both 2D and 3D elements. In general, this table size should be equal to the elementRules table size since they both reference the same rule set (when a physics object or a Gauss attribute specifies a rule set, it is selecting a row from both tables). If a rule set exists in one table and not in the other, the missing rule set will be considered as using default values for each type, so it is possible to have one table without the other. Ignored for node and cell meshes. | Table | No |
Example: edgeRules = { {quad4 = 2, tri3 = 1}, -- Rule set 1 {quad4 = 3, tri3 = 1}, -- Rule set 2 } | |||
| nodeSetData | An optional table storing a set of named collections of mesh nodes. Each table entry is a sub-table that stores an id with the node set name and a node list where each entry is a mesh node number. Ghost numbers can be included in the table as negative numbers (a value of -2 represents the second ghost number in the ghostData table). Alternatively, the nodeList subfield can be a Lua function that when called without parameters returns the number of nodes in this node set, and when called with an index 'i' returns the 'ith' node. The function will be called once without parameters and then once for each node ('i' varying from 1 to the number of nodes). It can also be a cell group name (see the cellData documentation). In that case, the node set will be filled with the set of geometry nodes referenced by the cells in the named group. | Table | No |
Example: nodeSetData = { { id = "top nodes", nodeList = { 4, 5, -3, 6} }, -- Nodes 4, 5 and 6 + Ghost node 3 { id = "left nodes", nodeList = { 1, 4 } }, -- Nodes 1 and 4 { id = "group nodes", nodeList = "cell group name"}, -- Nodes referenced by cells in the named cell group } | |||
| boundaryEdgeData | An optional table storing a set of named collections of cell borders. Each table entry is a sub-table that stores an id with the boundary name and a cell list where each entry is another table with a cell id and a border id inside this cell. See the Element types documentation for a reference about border numbering for the available mesh cell types. See the Boundary data section below for details. Ignored for node meshes. Alternatively, the cellList subfield can be a Lua function that when called without parameters returns the number of entries in this border, and when called with an index 'i' returns the 'ith' cell/border sub-table. The function will be called once without parameters and then once for each entry ('i' varying from 1 to the number of entries). | Table | No |
Example: boundaryEdgeData = { { id = "top border", cellList = { {1, 3}, {2, 3} } }, -- Element 1, border 3 + element 2, border 3 { id = "bottom border", cellList = { {1, 1}, {2, 1} } }, -- Element 1, border 1 + element 2, border 1 } | |||
| boundaryFaceData | An optional table, following the same syntax as boundaryEdgeData, but storing face ids instead of border ids. See the Boundary data section below for details. Ignored for node meshes. | Table | No |
Example: boundaryFaceData = { { id = "top face", cellList = { {1, 5} } } -- Element 1, face 5 } | |||
As explained above, each entry in the nodeData table is a table containing node coordinates, optionally followed by initial values for node attributes and state variables. Those values must follow first the definition order in the nodeAttributes table and then the definition order for state variables.
Likewise, the cellList inside the cellData table can include cell attribute initial values, following their definition order. The syntax is the same for both node and cell data initialization.
All initial values are optional, but for one value to be present, all previous values should also be present (or a nil should be given in its place). Trailing nil values can be ommited. If a value is not present, or a nil value is provided as initial value, the attribute / state variable default value will be used (if its declaration does not include a defVal clause, 0.0 will be used).
Values are expected to be in the unit given on the attribute / state variable declaration. Vector values should be given as a Lua table. For matrices, the initial value can be either given by a table of tables or linearized by column major format (the same used in the FORTRAN language), so, for a 2x2 matrix, both {11, 21, 12, 22} and { {11, 12}, {21, 22} } statements correspond to the matrix \(\begin{pmatrix} 11 & 12 \\ 21 & 22 \end{pmatrix}\). If an attribute supports functions, the value can also be a string with a function name.
Node initialization example:
The resulting initial values for the above mesh nodes are (bold values are default values replacing a nil or a missing value):
| node | x | y | na1 | na2 | na3 | sv1 | sv2 |
|---|---|---|---|---|---|---|---|
| 1 | 0 | 0 | 5.7 | {0.45, 1.23} | {{11.1, 12.1}, {21.1, 22.1}} | {101.0, 101.1, 101.2} | 1.1 |
| 2 | 10 | 0 | 5.8 | {0.00, 0.00} | {{11.0, 12.0}, {21.0, 22.0}} | {102.0, 102.1, 102.2} | 0.0 |
| 3 | 20 | 0 | -999 | {0.47, 1.25} | {{11.0, 12.0}, {21.0, 22.0}} | { 0.0, 0.0, 0.0} | 0.0 |
| 4 | 0 | 10 | 'f' | {0.48, 1.26} | {{11.4, 12.4}, {21.4, 22.4}} | {201.0, 201.1, 201.2} | 2.1 |
| 5 | 10 | 10 | -999 | {0.00, 0.00} | {{11.0, 12.0}, {21.0, 22.0}} | { 0.0, 0.0, 0.0} | 0.0 |
As explained above, each entry in the cellList table inside a boundaryEdgeData or boundaryFaceData tables contains pairs with node ids and border / face numbers. Border and face number ordering can be found on the Element types documentation. The following example shows how to define edge borders for the top and left borders for the mesh on the image below, where cell numbers are shown for each cell, and border edge numbers for cell 2.
Important: edge numbering depends on the order that nodes where listed when defining a cell. For a quad element, the first edge will always be between the first and second cell nodes, but the location of that border (top, bottom, left or right for an axis aligned quad) depends on the order that the nodes where given. On the image below, the numbers in the cell corners are the order in which each node appears in the cell definition, and the numbers along lines the edge numbers.
Except for very simple meshes, it is always a good idea to separate the mesh meta-data information given by the Mesh definition clause and its bulk data given by the set of node coordinates, cell geometry information, boundary data and initialization values (for both nodes and cells).
This can be done by saving that data in an auxiliary file that stores node, cell and border data into tables that are loaded by the model file through a call to the standard Lua dofile() function, much in the same way as is commonly done in the master simulation file. The only trick is to make sure that the data file returns the tables through a return clause. The example below illustrates this technique.
mySimulation_model.lua:
mySimulation_meshData.lua:
Dummy example for an heterogeneous mesh, supporting ghost nodes and using most of the above defined fields:
1.8.15