Documentation#

Introduction#

Convmesh is an utilitary softxware written in C++ that allows to convert several mesh file formats. The start idea is to manage mel mesh files, being the legacy mesh format of the finite element library Melina, now replaced by XLiFE++.

Installation#

Convmesh installation process is to compile source distributions. See Download for more.

Archive extraction builds a directory whose name is like convmesh-vXXX (where XXX is the version number). This directory contains the whole source distribution. You can move this directory wherever you want. The only requirement is to add the dorectory to your PATH.

The installation procedure is as follows:

  • Go to directory convmesh-vXXX

  • Run command make. An executable is built in the subdirectory bin

  • In order to check your installation, you can run the tests sequence with command make test

  • If tests are OK, you only need to add the bin subdirectory to your PATH.

  • Enjoy

Features#

What Convmesh does ?#

Convmesh is a mesh file converter. It can convert a msh (version 2.X only) file format or a mel file format into msh (version 2.X only), mel, amdba or vtk (2.0 version in unstructured grid data). Every file format is explained in Mesh file formats.

Amdba and vtk file formats are not considered as finite elements mesh format, but only as geometrical mesh formats. This is the reason why you can not use them as input of Convmesh.

Furthermore, when exporting into mel file format, Convmesh enables you to use some mesh tools : renaming domains, extract sub-domains, crack domains, … These features are explained in Transformations.

Using Convmesh#

Typical use of Convmesh is to give the inpout file name and the output file name:

$ convmesh [options] filename1.ext1 filename2.ext2

If filenames differ only by the extension, you can only give the extension for the output file:

$ convmesh [options] filename1.ext1 ext2

To learn everything about available options, please consult the help:

$ convmesh -h

The most important option is -i, that enables the interactive mode. Then, you can use transformations tools, before savinf the output file.

Mesh file formats#

Msh file format#

A mesh file in msh format is organized into data blocks. Each of these blocks is described in a subsection, in the order in which they appear in the mesh file (at least for mandatory blocks).

Format information#

The first block contains general information about the file:

$MeshFormat
version-number file-type data-size
$EndMeshFormat
version-number:

is a real number currently worth 2.1 or 2.2 (latest versions of the msh format). It may also be worth 2 (or 2.0), or even 1.x if you have a very old version of your mesh generator. In this case, I advise you to update it, as Convmesh only supports versions after 2.0.

file-type:

is 0 for a text file.

data-size:

specifies the number of significant digits in a double-precision float (=sizeof(double)). It is therefore very often 8.

As the 2.2 format has not yet stabilized, I’m going to describe the 2.1 format.

Nodes definition#

The next block concerns the definition of nodes, i.e. their number and the list of their coordinates:

$Nodes
number-of-nodes
node-number x-coord y-coord z-coord
...
$EndNodes

Elements definition#

The next block concerns the definition of elements (triangles, quadrangles, tetrahedrons, …):

$Elements
number-of-elements
elm-number elm-type number-of-tags node-number-list
...
$EndElements
elm-type:

the type of finite element (mesh geometry and interpolation order).

number-of-tags:

the number of element parameters.

<tags>:

the list of these parameters, of size number-of-tags. By default, the first parameter is the reference number of the physical entity to which the element belongs, the second is the reference number of the elementary geometric entity containing this element. When the mesh is partitioned (Gmsh offers this feature), a third tag is added, representing the reference number of the mesh partition containing this element.

node-number-list:

designates the ordered list of element node references.

Labels definition#

The next section concerns the definition of physical labels for the various mesh regions. This block is only used to specify labels using character strings.

$PhysicalNames
number-of-names
physical-dimension physical-number 'physical name'
...
$EndPhysicalNames

Caution

The domain dimension, contained in the physical-dimension variable, has only been present since version 2.1 of the msh format. Be careful if you’re using format 2.0!

Example#

Here’s the msh-format version of a single cubic element of order 1, where domain_2 denotes the volume domain and domain_1 the domain defining the edge of domain_2:

$MeshFormat
2 0 8
$EndMeshFormat
$PhysicalNames
2
1 domain_1
2 domain_2
$EndPhysicalNames
$Nodes
8
1 0 0 0
2 1 0 0
3 1 1 0
4 0 1 0
5 0 0 1
6 0 1 1
7 1 1 1
8 1 0 1
$EndNodes
$Elements
7
1 5 3 2 0 0 1 2 3 4 5 6 7 8
2 3 3 1 0 0 2 6 5 1
3 3 3 1 0 0 7 6 2 3
4 3 3 1 0 0 5 6 7 8
5 3 3 1 0 0 3 4 8 7
6 3 3 1 0 0 8 4 1 5
7 3 3 1 0 0 1 4 3 2
$EndElements

Mel file format#

The mel format is a mesh format specific to the Melina finite element library. In particular, it contains formatting information for reading data, the number of elements of a given type and the definition of geometric domains based on their elements. Insofar as there are different ways of writing information, specific syntax is used to designate optional elements ( […] ) or elements to be selected ( <…∧…> ). Furthermore, a line of data in this format must not exceed 80 characters. If necessary, continue with the next line.

Element description#

The first part concerns the overall definition of the mesh.

DESCRIPTION GLOBALE [DU] [MAILLAGE]
[ [NOM] [DES] VARIABLES [D''] ESPACE : string ]
NOMBRE [D''] ELEMENTS : nb-elem ]

Variable string can be ’X’ or ’X’ ’Y’ or ’X’ ’Y’ ’Z’.

The second part concerns the definition of elements. These elements are organized into blocks that represent the type of element. First, each block is defined, then, in the same order as the blocks, the elements are defined.

The general syntax of each block definition is :

BLOC [DE]
    < typeCellStr DE LAGRANGE [ AUX POINTS DE GAUSS-LOBATTO ]
        < typeInterpStr ∧ < D'ORDRE ∧ DE DEGRE > order >
    ∧ [TYPE] [GEOMETRIQUE] typeFECellStr
    > : nb-bloc-elem ELEMENTS
typeCellStr:

designates the geometric type of the elements. It can be HEXAEDRES, PRISMES, TETRAEDRES, QUADRANGLES, TRIANGLES, or SEGMENTS

typeInterpStr:

denotes finite element interpolation. It can therefore be of the form \(Pn, n \leq 6\) or \(Qm, m \leq 10\).

order:

denotes the order of interpolation.

typeFECellStr:

is a tetragram designating the finite element type. For example, ‘TR02’ designates a second-order triangle.

Each element is defined on 2 lines, with the coordinates of each node in the element, then their global reference number. Each element is thus defined by:

...
[ligne de commentaire]
x1 [y1 [z1]] x2 [y2 [z2]] x3 [y3 [z3]] ...
refnode1 refnode2 refnode3 ...
...

If ‘AVEC COMMENTAIRE’ is specified in the reading format, these two lines can be preceded by a comment line.

Physical domains description#

One of the special features of the mel format is that it contains the definition of physical domains based on the set of elements they contain. The syntax for an element is one of the following:

E[LEMENT[S]] elem-id [ / elem-id2 ]
E[LEMENT] elem-id < F[ACE] ∧ A[RETE] ∧ P[OINT] > edge-id

The variables elem-id and elem-id2 designate the global reference number of an element, while edge-id designates the local reference number of an edge of the element.

When elem-id2 is specified, then all elements whose global reference number is between elem-id and elem-id2 inclusive belong to the domain.

The keyword F[ACE] is used for 3D elements, A[RETE] for 2D elements and P[OINT] for 1D elements.

A mel mesh ends with the keyword FIN.

Example#

Here is the mel-format version of a single cubic element of order 1, where domain_2 denotes the volume domain and domain_1 the domain defining the side of domain_2:

TITRE 1
(generated by convmesh from cubeQ1.msh)
FORMAT DE LECTURE DES COORDONNEES '*'
    DE LA NUMEROTATION GLOBALE '*'
        SANS COMMENTAIRE
DESCRIPTION GLOBALE DU MAILLAGE
NOM DES VARIABLES D''ESPACE : 'X' 'Y' 'Z'
NOMBRE D''ELEMENTS : 1
BLOC DE TYPE GEOMETRIQUE HE01 : 1 ELEMENTS
0 0 0 1 0 0 1 1 0 0 1 0 0 0 1 0 1 1 1 1 1 1 0 1
1 2 3 4 5 6 7 8
DOMAINE 'domain_1'
E 1 F 1 E 1 F 2 E 1 F 3 E 1 F 4 E 1 F 5 E 1 F 6
DOMAINE 'domain_2'
ELEMENT 1
FIN

Amdba file format#

The amdba format is a geometric mesh format, so only elements of order 1 (defined solely by their vertices) are managed. Furthermore, all elements are necessarily of the same geometric nature. The format therefore contains no description of edge elements.

nb-nodes nb-elem elem-type
n1 x1 [y1 [z1]] phys-ref1
n2 x2 [y2 [z2]] phys-ref2
....
e1 i1 j1 k1 ... e-phys-ref1
e2 i2 j2 k2 ... e-phys-ref2
...
nb-nodes:

is the number of nodes in the mesh.

nb-elem:

designates the number of meshes.

elem-type:

designates the geometric mesh type. It can therefore be SEGMENT, TRIANGLE, QUADRANGLE, TETRAEDRE, HEXAEDRE, PRISME or PYRAMIDE. This keyword indicates the number of nodes in the element.

n1, n2, …:

designate the node’s global reference number.

e1, e2, …:

designate the element’s global reference number.

i1, j1, k1, …:

are the global reference numbers of nodes in element 1.

phys-ref1, phys-ref2, …:

designate the physical reference number of the node.

e-phys-ref1, e-phys-ref2, …:

designate the physical reference number of the element.

Here’s the amdba version of a single 1st-order cubic element.

8 1 HEXAEDRE
1 0 0 0 1
2 1 0 0 1
3 1 1 0 1
4 0 1 0 1
5 0 0 1 1
6 0 1 1 1
7 1 1 1 1
8 1 0 1 1
1 1 2 3 4 5 6 7 8 2

Vtk file format#

Like the amdba format, the vtk format is a geometric mesh format, so only 1st-order elements (defined solely by their vertices) are supported. Only the 2.0 format as generated by Convmesh is described here.

Header#

We generate a text mesh on an unstructured grid. This information is specified as follows:

# vtk DataFile Version 2.0
* title line
ASCII
DATASET UNSTRUCTURED_GRID

Nodes definition# 

POINTS nb-nodes datatype
x1 y1 z1
x2 y2 z2
...
nb-nodes:

is the number of nodes in the mesh.

datatype:

specifies the type of coordinates for each node. It can be bit, unsigned_char, char, unsigned_short, short, unsigned_int, int, unsigned_long, long, float or double.

Elements definition#

Like the amdba format, the vtk format does not define edge elements.

CELLS nb-cells size
nb-nodes n1 n2 ...
...
nb-cells:

is the number of cells.

size:

designates the total number of information items to be read.

nb-nodes:

is the number of nodes in the element, i.e. the number of information items still to be read on the line.

Element types definition#

Since different geometric elements can be defined by the same number of nodes (take a quadrangle and a tetrahedron, for example: 4 nodes), the last block of information specifies the type of each element. For example, 3 designates a segment, 5 designates a triangle and 14 designates a pyramid with a quadrangular base.

CELL_TYPES nb-cells
t1
t2
...

Example#

This is the vtk version of a single 1st-order cubic element.

# vtk DataFile Version 2.0
(generated by convmesh from cubeQ1.msh)
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 8 double
0 0 0
1 0 0
1 1 0
0 1 0
0 0 1
0 1 1
1 1 1
1 0 1

CELLS 1 9
8 0 1 2 3 4 5 6 7

CELL_TYPES 1
12

Transformations#

Extraction: How to set the parent of a domain ?#

Consider a geometric domain structured as follows:

Figure made with TikZ

Figure made with TikZ

The edges \(\Gamma_i\) and \(\Gamma_e\) are shared between the two domains \(\Omega_1\) and \(\Omega_2\), the former as an interface, the latter as an outer border. The extraction technique aims to be able to define in a mesh one of the domains \(\Gamma_{e1}\) = \(\Gamma_e \cap \Omega_1\), \(\Gamma_{e2}\) = \(\Gamma_e \cap \Omega_2\), \(\Gamma_{i1}\) = \(\Gamma_i \cap `\Omega_1\) and \(\Gamma_{i2}\) = \(\Gamma_i \cap \Omega_2\).

Duplicate a side domain#

Let’s place ourselves in the following context:

Figure made with TikZ

Figure made with TikZ

The disjunction technique consists in duplicating the \(\Gamma_i\) edge and dividing them both between the \(\Omega_1\) and \(\Omega_2\) domains. The nodes of these 2 copies of \(\Gamma_i\) overlap, but do not have the same global reference. The disjunction technique therefore consists in detecting the nodes on the domain to be disjoined, duplicating them, and distributing them on either side in the meshes concerned.

Crack a domain#

Let’s consider one of the following two cases:

Figure made with TikZ

Figure made with TikZ

The cracking technique consists, on the same principle as the disjunction technique, in detecting the nodes on the domain to be cracked, duplicating them, and distributing them on either side in the meshes concerned. In the first case, where the crack is part of the interface between two physical domains, distribution is carried out in the same way as for the disjunction technique. In the second case, the crack is within the same domain. The nodes on either side of the crack will therefore be distributed differently, based on the principle of adjacency. Note that the node at the tip of the crack is also duplicated.

FAQ#

Are listed here most of the questions asked to us when using Convmesh:

Convmesh is not found:

Please check if Convmesh root directory is in your PATH.

Convmesh does not run:

Please check if Convmesh does not need to be compiled once again or if your distrib needs to be updated. Please contact the developers in this context. The test you can realize is to display Convmesh help. If help is displayed, everything is OK

Convmesh runs in a loop:

Please run Convmesh with option -v (verbose mode). You will have information on the location of the infinite loop: reading input file, transformation step, writing output file, …

Convmesh does not manage to read a msh file:

First thing to check is the msh format version (2.0, 2.1, 2.2, …). It is possible that file is corrupted. See Format information