Home

Hello

Thanks for an interest in the tethex project. It may be useful if you need to convert tetrahedral (triangular) finite element (FE) mesh into hexahedral (quadrilateral) one. It might be especially helpful if you use the mesh for computations with deal.II.

Nevertheless, you probably don't need to use tethex if you use Gmsh to generate FE-mesh and you have an access to a file where geometry is described (it is usually .geo file).

Gmsh has a lot of options. There is a mesh option called Mesh.SubdivisionAlgorithm (look for it here) among them that allows to get exactly the same hexahedral (quadrilateral) mesh as tethex does. Although there were some problems with vertices order which resulted in errors when such meshes were read by deal.II function, these problems were observed very rarely and they had to be fixed in new 2.8.0 version. Using Gmsh is even preferable, because it takes into account the geometry of the model, and you will have better approximation of curved surfaces and lines by hexahedral (quadrilateral) elements.

If you are still interested in tethex, here is some information about it.

Introduction

Recently I was very interested in using deal.II in my work, but the main obstacle to use it was deal.II inability to work with simplicial meshes. Because of working on models with complex geometry I use tetrahedral grids for computations. There are many packages yielding good simplicial grids, but my favourite one is Gmsh. So the idea was to use Gmsh's triangulation in deal.II computations.

Fortunately, I was not the first who thought about it. I found this work (Update Dec 2013 sorry, the link doesn't work anymore), describing an attempt to implement such Gmsh-deal.II interface. Unfortunately, as one of the deal.II authors said here, this interface "never got finished". That was the reason to write a converter between Gmsh's mesh and mesh that could be understood by deal.II. Thanks to Graham Carey's paper "Hexing the Tet" there wasn't difficult to realize how to divide tetrahedra in hexahedra.

Structure of the project

The project is quite small. It's designed to be cross-platform, though it has been developed under Linux. To configure the project CMake is used.

The main files are tethex.h and tethex.cpp. One can just include these files into their code to use all capabilities of tethex (frankly speaking, tethex.cpp includes config.h, but the latter contains just several definitions initialized during configuration, and they could be easily copied into tethex.h).

main.cpp is just needed to build an executable file. Finally, testing.h is needed for testing purposes, and doxyfile - to generate comments-based documentation.

How to build the project

It's quite simple using CMake. There are two options: TESTING (OFF by default), and DELETE_SIMPLICES (ON by default).

First option (TESTING) is responsible for launching testing procedures before actual conversion. Testing procedures take just a couple of ticks, so you don't have to worry about lack of speed, even if you build the project with testing features. Testing procedures are based on Google Test framework, so to run tests you'll need necessary headers and gtest library.

The second option (DELETE_SIMPLICES) is used to allow the program to delete simplices (tetrahedra and triangles) after conversion. The resulting file will contain all mesh elements, and simplices as well, if you don't delete them. Moreover when we delete simplices, we clear the unused memory as soon as possible. Therefore there is no rational reason to change this option.

How-to-build instruction:

1. Get the latest sources by either cloning

    $ git clone https://github.com/martemyev/tethex.git
    $ cd tethex
   

   OR downloading a release archive from http://github.com/martemyev/tethex/releases

    $ tar -xf tethex-x.y.z.tar.gz
    $ cd tethex-x.y.z
   

2. Create a 'build' directory

    $ mkdir build
    $ cd build
   

3. Configure

    $ cmake ..
   

4. Build

    $ make
   

If doxygen is available on your system, you can build the comments-based documentation.

    $ make doc

To change the default values of the options, you can use ccmake or define the options in command line

    $ cmake .. -DTESTING=ON -DDELETE_SIMPLICES=OFF -DCMAKE_BUILD_TYPE=Release

Using the project

After building of the project you'll have an executable file tethex. To convert a Gmsh's simplicial grid to a Gmsh's brick grid, you need to point tethex to the input and output mesh files

    $ ./tethex input.msh output.msh

In this case you'll see some output information like that:

    Reading input.msh file...
    Reading input.msh file is done

    vertices    : 1806
    edges       : 0
    lines       : 0
    triangles   : 392
    faces       : 0
    tetrahedra  : 9125
    quadrangles : 0
    hexahedra   : 0

    Converting simplices to bricks...
    Converting simplices to bricks is done

    vertices    : 41287
    edges       : 0
    lines       : 0
    triangles   : 0
    faces       : 0
    tetrahedra  : 0
    quadrangles : 1176
    hexahedra   : 36500

    Writing output.msh file...
    Writing output.msh file is done

Note that pointing to the output file is optional. If you omit it, tethex will write the resulting mesh in file named like the input one but with _hex before extension. For example, if the input mesh file is input.msh, the resulting file will be named input_hex.msh.

Results

There are some pictures of results of using Gmsh, tethex, deal.II, and ParaView for solution of a simple problem - Laplace equation with a constant-wise coefficient and non homogeneous Dirichlet and homogeneous Neumann boundary conditions.

2D

Since I don't have much experience of using deal.II, I don't know for sure what geometry exactly deal.II can't mesh, but I think that it can't treat the following domain.

Let material corresponding to the left triangle has coefficient 0.01, material of the right triangle has coefficient 100, and finally material of the rest of domain limited by rectangle has coefficient 1.

Let the value of Dirichlet condition on the top boundary is equal to 1, and the Dirichlet value on bottom boundary is -1. Left and right boundaries are supposed to be the area of homogeneous Neumann condition.

Triangular mesh built by Gmsh looks like that.

After conversion of triangles into quadrangles using tethex, we have the following mesh.

Finally we solve the problem using deal.II and visualize the solution using Paraview.

By the way, Gmsh builds quadrilateral grids very well. In the earlier versions there was no ability to get fully quadrilateral mesh for a complex geometry - only some parts of the grid consisted of the quadrangles, and there were triangles as well. But now Gmsh was significantly improved in this direction, and your mesh can be completely quadrilateral, as you can see on the picture below.

Using quadrilateral mesh built by Gmsh is more preferable than grid converted by tethex, because Gmsh's triangulation is coarser. And you can effectively use deal.II for adaptive refinement. But there is one problem when you try to work with such mesh in deal.II. For example, for the triangulation shown above I got the exception during the mesh reading procedure (note, that I used 7.2.0 version of deal.II):

    An error occurred in line <650> of file </home/artemiev/deal.II/source/grid/grid_reordering.cc> in function
    static void dealii::GridReordering<dim, spacedim>::invert_all_cells_of_negative_grid(const std::vector<dealii::Point<spacedim> >&, std::vector<dealii::CellData<dim> >&) [with int dim = 2, int spacedim = 2]
    The violated condition was: 
        n_negative_cells==0 || n_negative_cells==cells.size()
    The name and call sequence of the exception was:
        ExcInternalError()
    Additional Information: 
    (none)

What does this n_negative_cells==0 || n_negative_cells==cells.size() mean? It means that for deal.II the order of vertices numbers is very important, and deal.II checks that all cells are numbered clockwise or counter-clockwise - but without mixing. So even having good quadrilateral mesh from Gmsh there is no confidence, that deal.II will work with it. Update This bug had to be fixed in 2.8.0 version of Gmsh.

Therefore the idea of changing the order of vertices inside tethex rose and was implemented in 0.0.2 version. From Gmsh's point of view you won't see any changes - the mesh will be the same. But for several quadrangles the order of vertices numbers was changed - and it allows to use such mesh in deal.II. Here is the result of solving the same task on the mesh presented above.

3D

We start by saying that Gmsh cannot produce hexahedral grids for more or less complex models. There is some possibility to build parallelepipedal grids for trivial geometry though.

So, lets consider the following model - a sloped cylinder inside a cube.

The view from another angle.

We build the tetrahedral mesh using Gmsh. That's how the cylindrical inclusion looks like

This is a cut of the mesh inside the cylinder by plane going through the center of domain (option Keep whole elements is ON).

And this is a cut of the mesh of the rest of domain by the same plane.

Then we use tethex to convert tetrahedra into hexahedra, and boundary triangles into qudrangles. What we have is

Now we solve the same problem as in 2D case. We have 2 domains, and let the material of the cylinder has coefficient 0.01, and the material of the rest of the domain has coeffient 1. Dirichlet boundary condition: the solution on the top face is supposed to be equal to 1, on the bottom face = -1. Other sides of the cube are the domains where homogeneous Neumann boundary condition is held. We solve the problem using deal.II, and visualize the solution using Paraview.