Notes on using Gerris

See also the Gerris wiki; there is also an older version.


The StL surface mesh format

The StL format is described by:

It's pretty simple. The StL file defines a surface as a list of triangles and each triangle by the three Cartesian coordinates of its vertices (v1, v2, v3). The triangle's unit normal n1i + n2j + n3 k can also be specified, but, as this can be computed from the vertices, it's not essential. The file begins with the word ‘solid’ and ends with ‘endsolid’, in between each triangle is specified by:

    facet normal n1 n2 n3
    outer loop
    vertex v11 v12 v13
    vertex v21 v22 v23
    vertex v31 v32 v33

Some programs, including SolidWorks I believe, generate STL files with upper case characters. I think this violates the standard, and these won't work with Gerris. They are easily corrected however with

    $ tr [:upper:] [:lower:] < UPPER.stl > lower.stl

Further, STL files with DOS-style line-breaks can be corrected with

    $ fromdos dossy.stl

Creating and processing StL files

According to the FAQ, StL files can be created with:

Creating binary StL files with Blender

Blender begins with a cube, and if this is immediately exported to StL, we get cube.stl. It's binary.

To mesh a sphere, right-click on the cube to select it and hit DELETE. From the menu, choose Add/Mesh/ and either UVSphere or ISOSphere. You'll be asked about refinement; select some level of refinement. Hit TAB to get back to object mode, then select File/Export/STL.

For more tips on using Blender, see Blender 3D: Noob to Pro.

Converting StL to GTS with stl2gts
$ stl2gts < cube.stl > cube.gts
Processing StL files with ADMesh

ADMesh reads, processes, and writes StL files; though I note that stl2gts doesn't think the example file block.stl that comes with ADMesh is valid, unless all the upper-case letters are lowered, as mentioned above.

ADMesh can convert binary StL files to ASCII; e.g.

  $ admesh --write-ascii-stl=cube_ascii.stl cube.stl

The GTS set tool

The GTS source code package comes with a useful tool in the examples directory, set. Here's a trivial example.

  1. Copy the set script to your directory:
    $ cp /usr/local/src/gts-0.4.2/examples/set .
  2. Run the shell script
        shapes ellipse | transform --sx=0.1 --sy=0.1 | transform --rx=90 > ellipse.gts
        shapes square | transform --sx=3 --sy=0.15 | transform --ty=-0.5 > square.gts
        ./set diff ellipse.gts square.gts | transform --revert > jetplate.gts
    This should produce the GTS file jetplate.gts.
  3. Try it out, using a simple simulation file jetplate.gfs
    $ gerris3D jetplate.gfs | gfsview3D
  4. Observe the evolving solution, say by a colour plot of the tracer T, between fixed levels 0 and 1.

Thanks to Srinarayana Nagarathinam, a postgraduate student in the School of Aerospace, Mechanical, & Mechatronic Engineering, for his help in producing this example.

Obviously you'll need to modify the above to get what you need. Check out the options in the GTS tool transform:

$ transform --help

for how to rotate, translate, and scale GTS surfaces.

Mesh refinement

A catch (as at Fri. 20 Oct. 2006) is that cells cut by surfaces can't be adaptively refined; therefore they should be refined to at least the maxlevel of the adaptive refinement from the beginning, say by using RefineSolid; see Stéphane Popinet's post of 16 Mar. 2006.


In 2006, my Bachelor of Engineering thesis student Sujee Mampitiyarachchi developed a system for generating GTS wing surfaces using GNU Octave. It's called GTSwing.



Gerris is basically an unsteady solver, but stable steady solutions can be obtained as the long-time asymptote of an unsteady solution. Gerris facilitates this with the GfsEventStop command.

Creeping flow

On 7 June 2005, Stepháne Popinet wrote to the gfs-users list:

Also note that you can switch the velocity advection terms off completely using:

GfsAdvectionParams { scheme = none }

which is what you want for a pure Stokes (creeping) flow.

Expressions and functions

It's possible to express derivatives of functions; e.g. to get the x derivative of U, write dx ("U"). This works in GfsView too.

GfsFunctions can even include internal C functions, as in this example posted by Stepháne Popinet to the GFS Users Discussion List on Wed. 2 May 2007:

  # force U to 1 inside the turbine
  Init { istep = 1 } {
  U = {
  int inside_turbine (double x, double y, double z) {
  return (x >= -0.1 && x <= 0.1 && y*y + z*z <= 0.1*0.1);
  if (inside_turbine (x, y, z))
  return 1.;
  return U;


Instantaneous postprocessing

For debugging a new simulation, the following trick is useful. Add the line

  OutputSimulation { istep = 1 } stdout {}

to your test.gfs file, then pipe the output through GfsView:

$ gerris3D test.gfs | gfsview3D

Creating MPEG animations

Using ImageMagick's convert

See Converting ppm files to mpeg.

Using Netpbm's ppmtompeg

For Debian, the program ppmtompeg is included in the netpbm package.

As described in its manual, Netpbm's ppmtompeg requires a fairly complicated input parameter file; see the ppmtompeg manual.

N.B. This method does not work for multiframe PPM image files, so can't be used in the above example. I think it would be possible to work around this with pnmsplit, which will split a multi-image PNM file into multiple single-image files.

Valid XHTML 1.1., valid CSS

Last modified Mon. 6 Apr. 2009 by Geordie McBain.