FAQ

From Gerris

(Difference between revisions)
Jump to: navigation, search
Revision as of 21:06, 14 May 2009
Popinet (Talk | contribs)
(Can Gerris handle moving/deforming solid geometries?)
← Previous diff
Revision as of 12:47, 4 October 2012
GeordieMcBain (Talk | contribs)
(Is there a Windows version of Gerris? - removed redundant second pair of brackets from external link)
Next diff →
Line 12: Line 12:
With a soft `g' like `genetics' or `general'. With a soft `g' like `genetics' or `general'.
 +
 +==Where does Gerris come from?==
 +
 +Gerris was developed from scratch by Stéphane Popinet starting in 2001. The first version was released as GPL-licensed code in September 2001. Gerris is not an adaptation of any previous existing code. In particular it is not an extension of the marker code developed during Stéphane Popinet's PhD or of the SURFER code developed by Stéphane Zaleski and collaborators.
==Where are the printable versions of the docs?== ==Where are the printable versions of the docs?==
Line 53: Line 57:
Gerris uses a domain decomposition approach using MPI for Gerris uses a domain decomposition approach using MPI for
-synchronisation at domain boundaries. For the moment it does not do+synchronisation at domain boundaries.
-dynamic balancing of domain sizes which limits its applicability to+
-statically refined problems.+
==Does adaptive refinement work in parallel?== ==Does adaptive refinement work in parallel?==
-Yes but there may be load-balancing issues. I+Yes.
-don't use the MPI version for the moment. For the type of studies I am+
-interested in, it is usually much easier to do "direct parallelism"+
-i.e. run several simulations with different parameters "in parallel".+
==Does the parallel version of the code do load-balancing?== ==Does the parallel version of the code do load-balancing?==
-No, the code does not have parallel load-balancing capabilities at the+Yes, see [[GfsEventBalance]].
-moment. It can do static load-balancing i.e. "optimal" partitioning of+
-the domain so that an initial mesh is divided in roughly equal-sized+
-subdomains while minimising the size of the communication boundaries.+
- +
-I don't personally use the parallel capability of the code very+
-much. What I usually need is several different sequential computations+
-with a different set of parameters. This is of course the ideal case+
-for "parallelism". I don't usually require to run "one shot" very+
-large parallel computations.+
- +
-==When will parallel load-balancing be available?==+
- +
-Load-balancing is not very high on my list of priorities at the+
-moment. I don't see fundamental obstacles to dynamic+
-load-balancing. The main limitation of the current code which would be+
-hard to do away with is the fact that only "coarse grain" parallelism+
-is possible (i.e. domains can be partitioned only at the GfsBox level+
-not at an individual cell level). This is a limitation only when the+
-ratio of total number of cells to total number of CPUs becomes small+
-however.+
- +
-What's ultimately needed to implement "full" load-balancing is a way+
-in the code to transfer entire GfsBoxes from one processor to the+
-other (ensuring the correct restructuring of associated boundary+
-conditions). This is a technical problem but which could be solved+
-relatively easily by someone with a good understanding of the code+
-structure at the GfsBox/GfsBoundary level.+
- +
-An intermediate possibly easier (but not as clean) solution can be to+
-save the simulation and stop the code when load-balancing becomes too+
-bad, then do a static load-balancing step and restart a "new"+
-simulation with this as initial state. I would probably first+
-experiment with this approach to get used to the problems involved+
-first and then move to the full internally-coded solution.+
==Can Gerris handle moving/deforming solid geometries?== ==Can Gerris handle moving/deforming solid geometries?==
Line 113: Line 78:
==Can Gerris solve the shallow-water (Saint-Venant) equations?== ==Can Gerris solve the shallow-water (Saint-Venant) equations?==
-Yes, starting with version 0.6.0, although I would not consider it+Yes, both a linearised form and the full non-linear Saint-Venant equations. See sections 4 and 5 of the [[examples]].
-ready for "general consumption" right now. For simple examples on how+
-this works have a look at the shallow-water [http://gfs.sf.net/http://gfs.sourceforge.net/tests/tests/index.html test cases].+
==How can I assist you in your development effort?== ==How can I assist you in your development effort?==
Line 161: Line 124:
Certainly not a native Windows version (Gerris relies on features Certainly not a native Windows version (Gerris relies on features
found in professional operating systems) but one should be able to found in professional operating systems) but one should be able to
-compile and install it on Windows using [http://www.cygwin.com cygwin]. You could also try to install a virtual linux machine, such as [[http://en.wikipedia.org/wiki/VMware VMware]]. See also [[FAQ#My simulation file looks fine but does not work, why?]]+compile and install it on Windows using [http://www.cygwin.com cygwin]. You could also try to install a virtual linux machine, such as [http://en.wikipedia.org/wiki/VMware VMware]. See also [[FAQ#My simulation file looks fine but does not work, why?]]
My personal advice would be "why use Windows?" My personal advice would be "why use Windows?"
Line 196: Line 159:
==How do I run the test suite or a single test case?== ==How do I run the test suite or a single test case?==
-To run the whole [http://gfs.sourceforge.net/tests/tests/index.html test suite] do:+To run the whole [[Tests|test suite]] do:
% cd src/gerris % cd src/gerris
% make -k check % make -k check
-Note that you need to be patient as the test suite takes several hours to run on a standard PC.+Note that you need to be patient as the test suite takes several hours to run on a standard PC. You can make things faster on a multicore system by using (e.g. on 8 cores the following will run about 8 times faster):
 + 
 + % make -k -j8 check
To run a single (or a few) test cases do something like: To run a single (or a few) test cases do something like:
% cd src/gerris/test % cd src/gerris/test
- % python test.py poisson advection ...+ % python test.py poisson advection shear/curvature ...
Obviously you need to have a reasonably recent version of python installed on your system. Obviously you need to have a reasonably recent version of python installed on your system.
-To generate the documentation for the test cases (i.e. a page similar to [http://gfs.sourceforge.net/tests/tests/index.html this one] but based on your local test suite results) try:+To generate the documentation for the test cases (i.e. a page similar to [[Tests|this one]] but based on your local test suite results) try:
% cd src/gerris/test % cd src/gerris/test
% make tests.tar.gz % make tests.tar.gz
-Note that you will need a number of packages for this work: hevea, source-highlight etc...+Note that you will need a number of packages for this to work: hevea, source-highlight etc...
To generate the documentation for a single test do: To generate the documentation for a single test do:
Line 225: Line 190:
=Physics and dimensioning= =Physics and dimensioning=
 +
 +==How do variables defined in the parameter file enter the equations solved?==
 +
 +Gerris solves:
 +<center><math>\frac{d \overrightarrow u}{dt} = \alpha \left\{ - \overrightarrow \nabla p +
 +\overrightarrow \nabla \cdot ( \mu (\overrightarrow \nabla \overrightarrow u +
 +\nabla \overrightarrow u^T )) + \sigma \kappa \delta_s \overrightarrow n \right\} +
 +\text{ {\tt Source} }(\overrightarrow u)</math></center>
 +
 +where alpha is defined by [[GfsPhysicalParams]], mu is defined by [[GfsSourceViscosity]],
 +sigma is defined by [[GfsSourceTension]], kappa is defined by [[GfsVariableCurvature]],
 +and the additional source term is defined by [[GfsSource]].
 +Delta_s is the Dirac distribution function of the interface, and n the normal to the interface.
 +
 +See also [http://gfs.sf.net/papers/tension.pdf An accurate adaptive solver for surface-tension-driven interfacial flows] (S. Popinet, Journal of Computational Physics 228, 5838–5866, 2009) for more details.
==Where are variables like viscosity, density etc... defined?== ==Where are variables like viscosity, density etc... defined?==
Line 255: Line 235:
==How would I create a 5x5 box?== ==How would I create a 5x5 box?==
-It is possible to change the size of the unit GfsBox, however, I would+It is possible to [[FAQ#I_don.27t_like_this_choice_of_units.2C_can_I_change_it_to_something_else.3F|change the size of the unit GfsBox]], however, I would
encourage you to think in "relative units" rather than "absolute encourage you to think in "relative units" rather than "absolute
units". When studying fluid mechanics (and other physical) problems it units". When studying fluid mechanics (and other physical) problems it
Line 303: Line 283:
(to machine precision) to the velocity field for simulation 2 at time (to machine precision) to the velocity field for simulation 2 at time
t/2.0, divided by 2.0. t/2.0, divided by 2.0.
 +
 +==How would I redimensionalise a force?==
 +
 +e.g. when using [[GfsOutputSolidForce]]. A force has units of mass x length / time^2 so that
 +
 + F Newton = F*DENSITY*Uref^2*Lref^2
==It looks like t and dt output by GfsOutputTime are also scaled? How would I scale t and dt to time in seconds?== ==It looks like t and dt output by GfsOutputTime are also scaled? How would I scale t and dt to time in seconds?==
Line 317: Line 303:
therefore therefore
VORTICITY' = VORTICITY*Vref/Lref VORTICITY' = VORTICITY*Vref/Lref
 +
 +==I don't like this choice of units, can I change it to something else?==
 +
 +Yes. You can use any unit system as long as it is consistent (you cannot set e.g. lengths in metres and velocities in, say, feet/second). The only thing you need to change is the default length, for example to make the GfsBox 3.75 metres long, one can use
 +
 + [[GfsPhysicalParams|PhysicalParams]] { L = 3.75 }
 +
 +all other quantities must then use metres as length units. Note that you are free to also choose any time unit you like (e.g. seconds, hours etc...) again provided all quantities use the same time unit.
 +
 +A well-known example of a consistent system of units is the [[w:International System of Units|SI system]] (lengths in meters, time in seconds, mass in kilograms, forces in Newtons etc...).
==The code provides support for the variable density incompressible Euler equations. Does that mean you can input the density of the fluid density (air, water, etc...)?== ==The code provides support for the variable density incompressible Euler equations. Does that mean you can input the density of the fluid density (air, water, etc...)?==
Line 372: Line 368:
and be able to export it in the GTS format (very simple, described and be able to export it in the GTS format (very simple, described
[http://gts.sourceforge.net/reference/gts-surfaces.html#GTS-SURFACE-WRITE here]) [http://gts.sourceforge.net/reference/gts-surfaces.html#GTS-SURFACE-WRITE here])
-or alternatively in the STL format (which can be converted to GTS+or alternatively in the [[w:STL_(file_format)|STL]] format (which can be converted to GTS
using the <code>stl2gts</code> program). using the <code>stl2gts</code> program).
Line 382: Line 378:
Blender can do that and is open-source, also have a look at ac3d, k3d Blender can do that and is open-source, also have a look at ac3d, k3d
-and Pro/Engineer, Rhino. There are plenty of others.+and Pro/Engineer, Rhino. [http://meshlab.sourceforge.net MeshLab] is also a good tool for file format conversion as well as mesh "reconstruction" (i.e. fixing orientation, self-intersections, filling holes etc...).
 +There are plenty of others.
==My STL file looks fine, however conversion using <code>stl2gts</code> fails, what's wrong?== ==My STL file looks fine, however conversion using <code>stl2gts</code> fails, what's wrong?==
Line 451: Line 448:
==Are there any tools for converting format-X (not STL) files (generated via a CAD system) to a GTS-format file?== ==Are there any tools for converting format-X (not STL) files (generated via a CAD system) to a GTS-format file?==
-The GTS file format is described [http://gts.sourceforge.net/reference/gts-surfaces.html#GTS-SURFACE-WRITE here].+Yes, have a look at [http://meshlab.sourceforge.net/ MeshLab] for example.
 + 
 +Alternatively, the GTS file format is described [http://gts.sourceforge.net/reference/gts-surfaces.html#GTS-SURFACE-WRITE here].
It is very simple. You should be able to write your own filter It is very simple. You should be able to write your own filter
using your favourite scripting language. You might want to have a look using your favourite scripting language. You might want to have a look
Line 561: Line 560:
=Post-processing and Visualisation= =Post-processing and Visualisation=
 +
 +==What are the basic tools for post-processing and visualisation of saved simulation files==
 +
 +The files generated by [[GfsOutputSimulation]] can be visualised with
 +[[Basic_Tutorial#Gfsview:_a_graphical_tool|Gfsview]].
 +
 +There is also a batch mode of Gfsview to produce images: [[Gfsview-batch]].
 +
 +It is also possible to generate other graphic-files formats with [[Gfs2oogl]].
==Is there a way to view the results and solid(s) at the same time (with the solid in the correct location? (Geomview question)== ==Is there a way to view the results and solid(s) at the same time (with the solid in the correct location? (Geomview question)==
Line 622: Line 630:
</source> </source>
-Also have a look at the code which writes a Gerris simulation as a VTK or Tecplot unstructured file in [http://gfs.sourceforge.net/darcs/gerris/gerris-stable/src/unstructured.c <code>src/unstructured.c</code>].+Also have a look at the code which writes a Gerris simulation as a VTK or Tecplot unstructured file in [http://gerris.dalembert.upmc.fr/darcs/gerris-stable/src/unstructured.c <code>src/unstructured.c</code>].
==The GfsOutputSimulation and GfsOutputLocation files only place up to eight decimals. Is there any way to increase the number of decimal places?== ==The GfsOutputSimulation and GfsOutputLocation files only place up to eight decimals. Is there any way to increase the number of decimal places?==
-Good question. No there isn't, short of editing and recompiling the+Yes, see the "precision" option for [[GfsOutputSimulation]] and [[GfsOutputLocation]].
-source code. That would be a nice option to have in the simulation+
-file.+
==I would like a time-averaged velocity profile, would I have to specify a number of monitoring points at different heights, or is there a method to time average over a line through the solution domain?== ==I would like a time-averaged velocity profile, would I have to specify a number of monitoring points at different heights, or is there a method to time average over a line through the solution domain?==
Line 648: Line 654:
etc... The resulting sums are then written at the end of the etc... The resulting sums are then written at the end of the
simulation in the file <code>simulation-sum</code>. This file can then be simulation in the file <code>simulation-sum</code>. This file can then be
-post-processed (using <code>gfs2oogl</code> for example) to obtain averages,+post-processed (using [[Gfs2oogl|Gfs2oogl]] for example) to obtain averages,
standard deviations etc... (along any curves you want of course). standard deviations etc... (along any curves you want of course).
Line 673: Line 679:
which will result in PPM images of size 64x64, independently which will result in PPM images of size 64x64, independently
of the maximum level of refinement in the simulation. of the maximum level of refinement in the simulation.
 +
 +==The program 'gfsview2D' received an X Window System error==
 +
 +If when trying to save a PPM snapshot from gfsview you get an error message looking like:
 +
 + The program 'gfsview2D' received an X Window System error.
 + This probably reflects a bug in the program.
 + The error was 'GLXBadContext'.
 + (Details: serial 943 error_code 154 request_code 143 minor_code 5)
 + (Note to programmers: normally, X errors are reported asynchronously;
 + that is, you will receive the error a while after causing it.
 + To debug your program, run it with the --sync command line
 + option to change this behavior. You can then get a meaningful
 + backtrace from your debugger if you break on the gdk_x_error() function.)
 +
 +it most probably is because the OpenGL driver of you graphics card does not support writing to a buffer other than the graphics card buffer (i.e. your graphics card + driver only support a subset of OpenGL, this does not "reflect a bug in the program" :) ). As an alternative you can try to use gfsview-batch instead. gfsview-batch uses the OSMesa offscreen-rendering library which is not tied to any specific hardware. The only other solution is to get a better-supported graphics card...
 +
 +If anybody knows how to test (within the gfsview code) whether the current OpenGL driver supports offscreen rendering, I would be keen to know.
==Why create a new visualisation tool like GfsView? Can't you use existing tools like Mayavi/VTK, OpenDX etc...?== ==Why create a new visualisation tool like GfsView? Can't you use existing tools like Mayavi/VTK, OpenDX etc...?==
Line 766: Line 790:
[[GfsOutputSimulation]] { step = 0.1 } result-%3.2f.gfs [[GfsOutputSimulation]] { step = 0.1 } result-%3.2f.gfs
-For restarting where you left, pick the last result file written.+For restarting where you left, pick the last result file written. The -m or -D options should not be used when restarting a simulation from a (binary) simulation file (e.g. created using GfsOutputSimulation).
==How do I make all the boundaries of a 2D box no-slip?== ==How do I make all the boundaries of a 2D box no-slip?==
Line 786: Line 810:
==How do I run Gerris in parallel?== ==How do I run Gerris in parallel?==
-The principle is relatively simple. Each <code>GfsBox</code> can take a <code>pid</code>+See [[Gerris in parallel]].
-argument which defines the number of the process on which the solution+
-for this GfsBox will be computed. If you take the "half cylinder"+
-example and do something like:+
- +
- 4 3 GfsSimulation GfsBox GfsGEdge {} {+
- Time { end = 10 }+
- Refine 6+
- GtsSurfaceFile half-cylinder.gts+
- Init {} { U = 1 }+
- OutputProjectionStats { step = 0.02 } stderr+
- OutputSimulation { step = 1 } simulation-%d-%3.1f {}+
- OutputTiming { start = end } stderr+
- }+
- GfsBox { pid = 0 left = BoundaryInflowConstant 1 }+
- GfsBox { pid = 1 }+
- GfsBox { pid = 2 }+
- GfsBox { pid = 3 right = BoundaryOutflow }+
- 1 2 right+
- 2 3 right+
- 3 4 right+
- +
-if you run this using+
- % gerris2D half-cylinder.gfs+
-it will run on one processor. If you now do+
- % mpirun -np 4 gerris2D half-cylinder.gfs+
-it will run on 4 processor with each of the <code>GfsBoxes</code> assigned to a+
-different processor. Gerris takes care of the communications necessary+
-at the boundaries between <code>GfsBoxes</code> on different processors.+
- +
-The data will be written in different files e.g:+
- vorticity-0.ppm, vorticity-1.ppm etc...+
-where the number is the pid of the processor.+
- +
-For a more complete description you will have to wait until I find the+
-time to write the corresponding section in the tutorial.+
- +
- +
-=Further reading=+
- +
-==... for the engineer==+
-[[An engineer's pipe flow]]+

Revision as of 12:47, 4 October 2012

Contents

General questions

What does "Gerris" mean?

Gerris is the Latin (and French) name of the water strider (or water boatman), an aquatic insect which uses surface tension to "walk" on the surface of the water. Have a look at the logo on the front page of the Gerris web site for a graphical description.

How is "Gerris" pronounced?

With a soft `g' like `genetics' or `general'.

Where does Gerris come from?

Gerris was developed from scratch by Stéphane Popinet starting in 2001. The first version was released as GPL-licensed code in September 2001. Gerris is not an adaptation of any previous existing code. In particular it is not an extension of the marker code developed during Stéphane Popinet's PhD or of the SURFER code developed by Stéphane Zaleski and collaborators.

Where are the printable versions of the docs?

The tutorial and examples pages have printable PDF (tutorial.pdf, examples.pdf) versions, the reference manual only exists as an HTML document.

What grid generator is Gerris using?

Gerris uses an "embedded boundary" technique. Grid generation reduces to the computation of the "shape" (surface and volume fractions) of Cartesian (cubic) cells cut by the solid boundaries. These "boolean operations" between solids are performed automatically using GTS (the GNU Triangulated Surface Library). The cells cut by the boundaries can then be refined automatically using the quad/octree structure of the discretisation. Mesh generation is entirely automatic and works for any input geometry (provided it is topologically consistent, i.e. an orientable non-self-intersecting manifold).

Can Gerris handle unstructured tetrahedral meshes?

Gerris uses a quadtree (octree in 3D) finite volume discretisation. It cannot handle unstructured meshes.

Are there any plans to extend Gerris to RANS (Reynolds-Averaged Navier-Stokes)?

The focus is on time-dependent Navier-Stokes, so RANS is not really in my mind but nothing is in the way if this is what you need.

Large Eddy Simulation (LES) models is what I am thinking about as far as turbulence modelling is concerned.

What boundary conditions are in the code now and what BCs are planned for the near future?

Slip, no-slip solid boundaries, inflow, outflow, periodic..., but everything is there to implement your own boundary conditions as Gerris can not supply all the boundary conditions users could think of.

How is Gerris parallelised? Does it use MPI or a shared memory technique?

Gerris uses a domain decomposition approach using MPI for synchronisation at domain boundaries.

Does adaptive refinement work in parallel?

Yes.

Does the parallel version of the code do load-balancing?

Yes, see GfsEventBalance.

Can Gerris handle moving/deforming solid geometries?

Yes, see GfsSolidMoving.

Can Gerris also be used for compressible fluids?

No, but this would be possible. The existing shallow-water solver in particular can be seen as one form of compressible flow solver.

Can Gerris solve the shallow-water (Saint-Venant) equations?

Yes, both a linearised form and the full non-linear Saint-Venant equations. See sections 4 and 5 of the examples.

How can I assist you in your development effort?

Thanks for asking. The easiest way you can help me is first by using the code. Setting up your own test cases etc... And reporting problems, either in term of usability, unexpected results etc...

By doing that you will certainly help me ensure that the code is as robust as possible and you will soon find areas which need improvement and which you might like to work on (preferably after consultation with me so that we can coordinate our efforts).

An important point is also to remember to try to send your questions/comments to one of the two Gerris mailing lists (gfs-users or gfs-devel) so that other people can benefit from the exchange (I will also more readily reply to a message on the mailing list than to one addressed directly to me).

Installation and coding

How do I install the parallel version of Gerris?

If when running ./configure you got lines looking like

checking for mpicc... yes

then you don't have anything else to do. Otherwise, you need to make sure that you have MPI installed and that the mpicc command is in your PATH.

For running the code in parallel, see FAQ#How do I run Gerris in parallel?.

Does the Gerris configure script support a LAM MPI implementation?

Yes, more generally it should support any MPI implementation which defines a working mpicc command accessible in the PATH.

My crappy MPI installation prevents Gerris from compiling, how do I turn MPI support off?

% ./configure --disable-mpi

Is there a Windows version of Gerris?

Certainly not a native Windows version (Gerris relies on features found in professional operating systems) but one should be able to compile and install it on Windows using cygwin. You could also try to install a virtual linux machine, such as VMware. See also FAQ#My simulation file looks fine but does not work, why?

My personal advice would be "why use Windows?"

Is there a Mac version of Gerris?

Gerris also runs on MacOSX, see Mac OSX Installation.

See also FAQ#My simulation file looks fine but does not work, why?

Are there any plans to release a more documented version of the code?

I have chosen the "classical" point of view that, if the general description of the arguments and of what the function does (given just before the body of (almost) all the exported functions) together with the code in the function itself does not clearly describe what the function is doing, then this is a problem with the code itself not with the documentation. A counter-example of that would be a very long monolithic code described by comments every few lines.

Also, from my personal experience, working with a number of research and commercial codes, I would consider Gerris to be fairly well documented. The code is also quite modular, so you shouldn't (hopefully) need to go through all the 16000 lines of code...

Of course, I would be glad to address any detailed problem you may have (unclear documentation etc...)

Are there any plans to release a C++/Java/Object Oriented implementation of Gerris?

No. Gerris is already object-oriented (with class inheritance etc...), see the tutorial for an example of how this works.

How do I run the test suite or a single test case?

To run the whole test suite do:

% cd src/gerris
% make -k check

Note that you need to be patient as the test suite takes several hours to run on a standard PC. You can make things faster on a multicore system by using (e.g. on 8 cores the following will run about 8 times faster):

% make -k -j8 check

To run a single (or a few) test cases do something like:

% cd src/gerris/test
% python test.py poisson advection shear/curvature ...

Obviously you need to have a reasonably recent version of python installed on your system.

To generate the documentation for the test cases (i.e. a page similar to this one but based on your local test suite results) try:

% cd src/gerris/test
% make tests.tar.gz

Note that you will need a number of packages for this to work: hevea, source-highlight etc...

To generate the documentation for a single test do:

% cd src/gerris/test
% gfs2doc advection

See also How to write examples.

Physics and dimensioning

How do variables defined in the parameter file enter the equations solved?

Gerris solves:

<math>\frac{d \overrightarrow u}{dt} = \alpha \left\{ - \overrightarrow \nabla p + \overrightarrow \nabla \cdot ( \mu (\overrightarrow \nabla \overrightarrow u + \nabla \overrightarrow u^T )) + \sigma \kappa \delta_s \overrightarrow n \right\} + \text{ {\tt Source} }(\overrightarrow u)</math>

where alpha is defined by GfsPhysicalParams, mu is defined by GfsSourceViscosity, sigma is defined by GfsSourceTension, kappa is defined by GfsVariableCurvature, and the additional source term is defined by GfsSource. Delta_s is the Dirac distribution function of the interface, and n the normal to the interface.

See also An accurate adaptive solver for surface-tension-driven interfacial flows (S. Popinet, Journal of Computational Physics 228, 5838–5866, 2009) for more details.

Where are variables like viscosity, density etc... defined?

By default, the density is unity and the molecular viscosity is zero (i.e. there is no explicit viscous term in the momentum equation). In practice, it does not mean that there is no viscosity at all however, because any discretisation scheme always has some numerical viscosity. Of course, the lower the numerical viscosity, the better. Gerris has quite good properties in this respect.

How come Gerris generates a Von Karman vortex street for an inviscid flow around a half-cylinder? I would expect the inviscid flow to remain irrotational.

This is perfectly right in the case of flow around smooth solid boundaries. If there is a sharp corner (as for the half-cylinder), the potential flow solution is singular in the sense that the velocity tends to infinity as one gets closer to the corner. In practice (finite difference numerical solution) and in reality, the local numerical (or real) viscosity near the corner, smears out the singularity, which results in the creation of a (point) source of vorticity which is then carried away by the mean flow (as you can see on the half-cylinder example).

Even in the case of a smooth geometry, numerical inaccuracies in the boundary conditions on the solid surface can lead to the generation of a small amount of vorticity (much smaller than what is generated at a discontinuity though).

How would I create a 5x5 box?

It is possible to change the size of the unit GfsBox, however, I would encourage you to think in "relative units" rather than "absolute units". When studying fluid mechanics (and other physical) problems it is almost always a good idea to use non-dimensional units. This makes relevant independent parameters (such as the Reynolds number for example) immediately apparent. When using Gerris I would recommend scaling all your physical input parameters by a reference length (the physical length of the GfsBox). This also eliminates the need for changing the length of the GfsBox.

How would I modify the file you sent me (tangaroa.gfs) for a ship that is 150 meters long and exposed to a cross-flow wind velocity of 50 meters/sec?

You would have to non-dimensionalise both the model ship geometry and wind speed.

Let's say you want the ship to occupy one third of a GfsBox, the reference length of the GfsBox would then be 3*150 meters, so you would scale the model geometry by a factor of 1/(reference length) or 1/450.

You can do that directly in the parameter file like this:

 Solid model.gts { scale = 2.22222e-3 }

Or alternatively you might want to use the transform program to do that, something like this:

% transform --scale 2.22222e-3 < model.gts > model_scaled.gts

You also have to keep in mind that the bottom boundary of a 3D box is at z = -0.5. You want to have that coinciding with the sea level (i.e. translate your model vertically by the correct amount).

How would I redimensionalise U,V,W and P?

U metres/sec = U*Uref = U*50 metres/sec
V metres/sec = V*Uref = V*50 metres/sec
W metred/sec = W*Uref = W*50 metres/sec
P Pascals = P*DENSITY*Uref^2

However, keep in mind that the only relevant parameter for the (constant density) Navier-Stokes equations is the Reynolds number. If you do not include any explicit viscous term the (theoretical) Reynolds number is always infinite. In practice this means that the inflow velocity has only a uniform scaling influence on the final solution. For example

  • simulation 1: inflow velocity set to 1.0
  • simulation 2: inflow velocity set to 2.0

then, the velocity field of simulation 1 at time t is exactly equal (to machine precision) to the velocity field for simulation 2 at time t/2.0, divided by 2.0.

How would I redimensionalise a force?

e.g. when using GfsOutputSolidForce. A force has units of mass x length / time^2 so that

F Newton = F*DENSITY*Uref^2*Lref^2

It looks like t and dt output by GfsOutputTime are also scaled? How would I scale t and dt to time in seconds?

Let's say your reference scale is L=450 metres, your reference speed U=50 metres/sec, your reference time is then T=L/U=9 sec.

You thus need to multiply both t and dt by T=9 sec.

How do I scale Vorticity?

The units of vorticity are L/T/L and

T' = T*Lref/Vref

therefore

VORTICITY' = VORTICITY*Vref/Lref

I don't like this choice of units, can I change it to something else?

Yes. You can use any unit system as long as it is consistent (you cannot set e.g. lengths in metres and velocities in, say, feet/second). The only thing you need to change is the default length, for example to make the GfsBox 3.75 metres long, one can use

PhysicalParams { L = 3.75 }

all other quantities must then use metres as length units. Note that you are free to also choose any time unit you like (e.g. seconds, hours etc...) again provided all quantities use the same time unit.

A well-known example of a consistent system of units is the SI system (lengths in meters, time in seconds, mass in kilograms, forces in Newtons etc...).

The code provides support for the variable density incompressible Euler equations. Does that mean you can input the density of the fluid density (air, water, etc...)?

Not really if what you mean is a constant density throughout the domain. In the case of the incompressible constant-density Navier-Stokes equations, the density is irrelevant. It is only a scaling factor for the pressure.

What this really means is that Gerris can deal with flows where the density varies across the domain (e.g. a mixture of two miscible fluids, or density variations due to salinity variations in the sea for example).

Although the initialised problem is symmetric, the solution becomes asymmetric as time passes, why?

The code is indeed not perfectly numerically symmetrical. This is due mainly to the tolerance in the solution for the pressure equation, if you decrease the tolerance you should see smaller asymmetries. You can do this using

 ApproxProjectionParams {
   tolerance = 1e-6
 }
 ProjectionParams {
   tolerance = 1e-6
 }

How do I deal with negative values of the pressure?

Your question is interesting, it comes down to the meaning of "pressure" for incompressible flows.

For compressible flows "pressure" has a thermodynamic definition and is directly linked to other physical quantities through an equation of state. It is defined on an absolute scale.

For incompressible flows "pressure" does not have a thermodynamic definition (there is no equation of state linking it to other physical quantities), rather it comes about as the stress field necessary to enforce the incompressibility condition. In this context, only its gradients are relevant, not its absolute value i.e. one can add any constant to the pressure field without changing the solution.

Conclusion: If you don't like negative pressures just add any constant necessary to make them positive.

Representation of solid boundaries

How do I import my geometry into Gerris?

It depends how the geometry is defined. If it has an analytical representation, the easiest is to use implicit surfaces. Have a look at the GfsSolid and GfsSurface documentations.

If the geometry was created using a CAD package, you need to convert it into a set of triangulated surfaces and be able to export it in the GTS format (very simple, described here) or alternatively in the STL format (which can be converted to GTS using the stl2gts program).

The tricky bit is that the surfaces you export must represent proper solid objects i.e. they must be orientable, closed, manifold and non self-intersecting surfaces. Note that this is an issue only for explicit surfaces.

What CAD package can I use to export STL/GTS files?

Blender can do that and is open-source, also have a look at ac3d, k3d and Pro/Engineer, Rhino. MeshLab is also a good tool for file format conversion as well as mesh "reconstruction" (i.e. fixing orientation, self-intersections, filling holes etc...). There are plenty of others.

My STL file looks fine, however conversion using stl2gts fails, what's wrong?

If your STL file is ASCII (not binary) make sure that it is not DOS-formatted. You can convert from DOS to Unix ASCII formatting using:

% dos2unix myfile.stl

Do I need to tessellate (increase the number of triangles of) my surface before importing it into GTS?

If your solid boundary is exactly defined using a few triangles, there is no need to use more. In short, the mesh size generated by Gerris is completely independent from the "triangle size" of the input surface (in contrast to what happens in "classical" unstructured mesh solvers).

If for example, you want to resolve the boundary layers around your solid, you could tell Gerris to use a "fine enough" mesh like this:

RefineSolid 10

which tells Gerris to use 10 levels of refinement near the solid surface. "Fine enough" is going to depend on the details of the physics (most importantly Reynolds number) and on the constraints in term of computational time, memory size etc...

Which part of the parameter file tells Gerris where the half-cylinder is placed? How do I alter it?

The position of the solid object is defined (obviously) through the coordinates of its vertices. If you created it using a CAD or similar program, you can translate, rotate etc... the object using this same program.

You can also specify simple transformations (scaling, translations, rotations) directly in the parameter file, have a look at the GfsSurface documentation.

Alternatively, you can use the transform program which comes with GTS.

% transform -h

will give you a summary of the transformations you can make, currently

Usage: transform [OPTION] < file.gts
Apply geometric transformations to the input.

  -r ANGLE  --rx=ANGLE      rotate around x-axis
  -m ANGLE  --ry=ANGLE      rotate around y-axis
  -n ANGLE  --rz=ANGLE      rotate around z-axis
  -s FACTOR --scale=FACTOR  scale by FACTOR
  -R FACTOR --sx=FACTOR     scale x-axis by FACTOR
  -M FACTOR --sy=FACTOR     scale y-axis by FACTOR
  -N FACTOR --sz=FACTOR     scale z-axis by FACTOR
  -t V      --tx=V          translate of V along x-axis
  -u V      --ty=V          translate of V along y-axis
  -w V      --tz=V          translate of V along z-axis
  -i        --revert        turn surface inside out
  -o        --normalize     fit the resulting surface in a cube of
                            size 1 centered at the origin
  -v        --verbose       print statistics about the surface
  -h        --help          display this help and exit

Reports bugs to popinet@users.sourceforge.net

The resulting (transformed) object is written on the standard output.

For example, if you want the half-cylinder in the second cell do:

% transform -t 1 < half-cylinder.gts > half-cylinder1.gts

and use half-cylinder1.gts in the parameter file.

Are there any tools for converting format-X (not STL) files (generated via a CAD system) to a GTS-format file?

Yes, have a look at MeshLab for example.

Alternatively, the GTS file format is described here. It is very simple. You should be able to write your own filter using your favourite scripting language. You might want to have a look at the cleanup utility which comes with GTS (in the examples/ directory) It will allow you to link unlinked faces, remove duplicate vertices etc...

Gerris seem to allow only one solid body, is this correct?

No, there is no limitation on the number and/or complexity of solid bodies (as long as they are properly oriented, manifold geometrical surfaces). Multiple bodies are possible, either as a single GTS file containing multiple separate bodies or as multiple calls to GfsSolid in the parameter file with several non-intersecting GTS surfaces.

GfsSolid box_1.gts
GfsSolid box_2.gts

Note however that the solids cannot intersect.

How do I orient my solid surfaces properly?

The orientation of the faces of your solid defines where the fluid side is (by convention the counter-clockwise (CCW) normal direction to a face points toward the solid side). If your solid is not oriented properly you can use the flip = 1 option of GfsSurface ot the --revert or -i options of transform to turn it "inside out".

It looks like all STL files need to be turned "inside out". I don't understand why, but transform -i fixed the problem.

It is just a matter of different conventions. The program you use has chosen to orient the CCW face normals toward the "outside" of the solid object.

Can solids intersect?

No, you first need to use the "boolean operations" or "constructive solid geometry" operations of your solid modeller to generate the union of your solids.

This may change in the future.

We have a problem inserting some GTS files generated from STL files and even inserting the standard GTS files found on the GTS samples site?

The samples files on the GTS site are not necessarily describing consistent geometric surfaces (i.e. they can be open, non-manifold etc...)

Generally it is a good idea to check the topology of a GTS surface before trying to import it. This can be done using something like:

% gtscheck -v < surface.gts 

which will return something like:

# vertices: 28 edges: 84 faces: 56
# Connectivity statistics
#   incompatible faces: 0
#   duplicate faces: 0
#   boundary edges: 0
#   duplicate edges: 0
#   non-manifold edges: 0
#   edges per vertex: min: 5 mean: 6 | 1.19523 max: 9
#   faces per edge: min: 2 mean: 2 | 0 max: 2
# Geometric statistics
#   face quality: min: 0.224977 mean: 0.549119 | 0.240685 max: 0.950354
#   face area  : min: 0.0040422 mean: 0.11713 | 0.169305 max: 0.5
#   edge length : min: 0.0618034 mean: 0.675199 | 0.397857 max: 1.41421

This surface should be fine since it has no incompatible or duplicate faces and no duplicate or non-manifold edges.

How would I prepare a solid to simulate a flow inside a pipe/tube/hose?

The idea is to create a cube to fill Gerris's flow domain and to subtract the space where the fluid is meant to flow.

For example, start with a single fluid domain in your .gfs file, similar to what is used in the tutorials:

1 0 GfsSimulation GfsBox GfsGEdge {} {
[...]
GfsBox { left = GfsBoundaryInflowConstant 1 right = GfsBoundaryOutflow }

If you prefer solids created from scratch, here's an example which can be included into the .gfs file (typically at the second line):

GfsSolid ({
  double c = cube (0.0, 0., 0., 1.1);
  double cylinder = z*z + y*y - 0.12*0.12;
  return MAX (c, - cylinder);
})

If you prefer to use solids created in your CAD package of choice, create a cube with its edges parallel to the X-, Y- and Z-axis. The overall size of the cube is arbitrary, but all edges should be of equal size. If you have this, subtract your pipe's inside from this cube and export the result as STL.

The following shell commands will prepare this STL data for Gerris. The commands are split up for a better understanding, but in practice could be joined together into a shell pipeline.

# convert DOS newlines to Unix newlines, if required
tr -d '\r' < mysolid.stl > temp1
# convert the result to GTS format
stl2gts < temp1 > temp2
# depending on your CAD package, you may have to revert the triangulation's orientation
transform --revert < temp2 > temp3
# adjust the cube's size to fit Gerris's fluid domain
transform --normalize < temp3 > temp4
# make the cube slightly too big, so there's no ambiguity as to the status of the domain boundaries
transform --scale 1.001 < temp4 > mysolid.gts
# be tidy
rm temp1 temp2 temp3 temp4

Insert this solid into your .gfs file with a simple:

GfsSolid mysolid.gts

Post-processing and Visualisation

What are the basic tools for post-processing and visualisation of saved simulation files

The files generated by GfsOutputSimulation can be visualised with Gfsview.

There is also a batch mode of Gfsview to produce images: Gfsview-batch.

It is also possible to generate other graphic-files formats with Gfs2oogl.

Is there a way to view the results and solid(s) at the same time (with the solid in the correct location? (Geomview question)

Yes, you need to select the Inspect->Appearance->Normalise->None option in the Geomview menu. The default is to "normalise" (i.e. rescale) each object individually (Normalise->Individual option) so that it fits at the centre of the viewed area.

Is there any way to output U, V, W, P, etc... at point (X, Y, Z) in the flow field?

Yes, have a look at the documentation for GfsOutputLocation.

Where is the description of the format of the data section of saved simulation files?

If you intend to read the simulation files (to convert them or do other operations/calculations etc...) I would highly recommend that you do so through the functions provided by the Gerris library (gfs_simulation_read() and so on). This way you will not reinvent the wheel and you will be able to use all the functionalities provided by the library (traversal of the octree structure, computation of gradients, interpolations etc...). This would also ensure that your code is independent of the format changes in the simulation file.

Just to give you an example on how this can bite you:

the GfsOutputSimulation object can be used like this (in simulation files)

 GfsOutputSimulation { step = 0.1 } sim-%3.1f { variables = P,C }

in this case, the simulations files (sim-0.1, sim-0.2 etc...) will only contain the P and C variables.

Your code which reads the simulation files would need to know about this. The gfs_simulation_read() function deals with that for you and other functions give you easy access to this kind of information (what variables where contained in the simulation file etc...)

The following code fragment should get you started:

#include <gfs.h>
...
int main (int argc, char * argv[])
{
...
gfs_init (&argc, &argv);
GtsFile * fp = gts_file_new (stdin);
GfsSimulation * simulation = gfs_simulation_read (fp);
if (simulation == NULL) {
fprintf (stderr,
"myprogram: file on standard input is not a valid simulation file\n"
"<stdin>:%d:%d: %s\n",
fp->line, fp->pos, fp->error);
return 1;
}
gts_file_destroy (fp);
/* do stuff with simulation */
...
gts_object_destroy (GTS_OBJECT (simulation));
}

Also have a look at the code which writes a Gerris simulation as a VTK or Tecplot unstructured file in src/unstructured.c.

The GfsOutputSimulation and GfsOutputLocation files only place up to eight decimals. Is there any way to increase the number of decimal places?

Yes, see the "precision" option for GfsOutputSimulation and GfsOutputLocation.

I would like a time-averaged velocity profile, would I have to specify a number of monitoring points at different heights, or is there a method to time average over a line through the solution domain?

There is no method to do line averaging at the moment, however there is a method which averages (or more exactly stores the sum) of a given variable in time over the whole domain. You can do it like that:

 EventSum { start = 1 istep = 1 } U SUx
 EventSum { start = 1 istep = 1 } V SUy
 EventSum { start = 1 istep = 1 } W SUz
 EventSum { start = 1 istep = 1 } U*U SU2x
 EventSum { start = 1 istep = 1 } V*V SU2y
 EventSum { start = 1 istep = 1 } W*W SU2z
 OutputSimulation { start = end } simulation-sum { 
   variables = SUx,SUy,SUz,SU2x,SU2y,SU2z
 }

which would add U to SUx at every timestep (istep = 1) starting from time 1 (start = 1) etc... and U*U to SU2x at every timestep etc... The resulting sums are then written at the end of the simulation in the file simulation-sum. This file can then be post-processed (using Gfs2oogl for example) to obtain averages, standard deviations etc... (along any curves you want of course).

Using animate, the sequence of images generated by OutputPPM looks weird, what's happening?

This is probably an artefact of the way the animate command displays a series of PPM images. What happens is that OutputPPM generates PPM images which are just big enough to contain all the data in your simulation e.g. if you use 7 levels of refinement and one box, OutputPPM will generate images with 128x128 pixels. If you use an adaptive resolution with a maximum level of 6, the size of the resulting image generated by OutputPPM can be anything in 1x1, 2x2, 4x4, 8x8, 16x16, 32x32, 64x64 depending on the maximum number of levels necessary to verify your adaptation criterion. As a result, animate can see a series of PPM images with a variable size, if you look carefully you will see that the weird patterns you see are smaller-size images of your simulation, displayed in the top-left corner of the initial image. What animate should really do is blank out the previous larger image before displaying the smaller image, to make the difference in size clear.

The solution is simple, you can set the size of the images generated by OutputPPM using:

OutputPPM { step = 0.05 } tracer.ppm { v = T maxlevel = 6 }

which will result in PPM images of size 64x64, independently of the maximum level of refinement in the simulation.

The program 'gfsview2D' received an X Window System error

If when trying to save a PPM snapshot from gfsview you get an error message looking like:

The program 'gfsview2D' received an X Window System error.
This probably reflects a bug in the program.
The error was 'GLXBadContext'.
 (Details: serial 943 error_code 154 request_code 143 minor_code 5)
 (Note to programmers: normally, X errors are reported asynchronously;
  that is, you will receive the error a while after causing it.
  To debug your program, run it with the --sync command line
  option to change this behavior. You can then get a meaningful
  backtrace from your debugger if you break on the gdk_x_error() function.)

it most probably is because the OpenGL driver of you graphics card does not support writing to a buffer other than the graphics card buffer (i.e. your graphics card + driver only support a subset of OpenGL, this does not "reflect a bug in the program" :) ). As an alternative you can try to use gfsview-batch instead. gfsview-batch uses the OSMesa offscreen-rendering library which is not tied to any specific hardware. The only other solution is to get a better-supported graphics card...

If anybody knows how to test (within the gfsview code) whether the current OpenGL driver supports offscreen rendering, I would be keen to know.

Why create a new visualisation tool like GfsView? Can't you use existing tools like Mayavi/VTK, OpenDX etc...?

Most visualisation packages assume that the data is defined on either structured Cartesian meshes (this includes curvilinear coordinates) or fully unstructured meshes (tetrahedra etc...).

The octrees used by Gerris need first to be converted into unstructured tetrahedra and then imported into OpenDX etc... This is quite slow and memory-hungry and loses most of the advantages of the octree: in particular the multilevel representation of the solution is very useful from a visualisation point of view.

I am not aware of any good visualisation tool which understands octrees. It would be a good idea to post messages on OpenDX, Mayavi, VTK etc... mailing lists asking about support for octrees. I did that and got little feed back, but more messages would show the developers of these projects that there is a desire for such a feature.

GfsView makes the most of the octree structure to accelerate visualisation, computation of isosurfaces etc...

Running Gerris

Are the files vorticity.gfs and half-cylinder.gfs included in the Gerris distribution?

No, you will need to type them following the tutorial...

Your flow analysis for the RV Tangaroa is just the type of problem I would like to be able to solve quickly, etc... How long did it take to setup and run this problem? Could you send me a copy of the input file?

The longest was to get a "proper" CAD model of the vessel. We had it made by the ship designers but it was full of topological inconsistencies (folds, degenerate faces etc...). It was a real pain to fix it. Once you have a proper orientable, manifold solid there is nothing more to do really.

Have a look at the Tangaroa example.

How do you modify the mesh to give greater detail in a specific area of flow?

As you saw in the tutorial, the meshing is automatic and follows user-defined criteria. Vorticity and gradient-based criteria for example, can be used. The level of refinement used for both the initial refinement and the adaptive refinement can both be functions of space, time, other variables etc... which give almost total flexibility. Other criteria can be added within the object-oriented framework of the code if necessary.

Is there any way to initialise the grid so that a fine grid is generated around the surface of the solid and a coarser grid is generated in the flow field (resulting in significantly fewer cells being generated)?

Sure. You can use something like:

GfsRefine 6
GfsRefineSolid 8

which will first create a uniform level 6 grid and then add two extra levels (up to level 8) only in the cells cut by the solid boundary.

Is it possible to turn off adaptive meshing in defined areas?

You could do this like that for example:

AdaptVorticity { istep = 1 } { 
  cmax = 1e-2 
  levelmin = (x > 0 ? 6 : 0)
  levelmax = (x > 0 ? 6 : 7)
}

which would use a constant resolution (6 levels) on the right side of the domain (x > 0) and adaptive resolution (up to 7 levels) on the left side.

Is there a way to control the maximum size of a simulation?

Use something like:

AdaptVorticity { maxlevel = 10 maxcells = 400000 cmax = 1e-2 }

the maxcells option tells the adaptive algorithm to use a maximum of 400,000 cells to discretise the domain. When this maximum number is reached the algorithm minimises the maximum cost of the refinement by optimally distributing the cells across the domain. You have to be aware however that this means that the accuracy of the simulation will not be constant in time.

My simulation file looks fine but does not work, why?

Are you sure your text editor does not include special characters in your files? (the infamous DOS end of line comes to mind).

On Mac, traditionally, a text file uses Return (ASCII 13) as an end of line character. Unix uses Line Feed (ASCII 10) as an end of line character. You should thus convert your files if they have such characters. See for instance the osxfaq page

Restarting a simulation always starts at t = 0 ?!?

If you want to re-run a simulation from a later point in simulation time ( t > 0 ), you have to save results into distinct files:

GfsOutputSimulation { step = 0.1 } result-%3.2f.gfs

For restarting where you left, pick the last result file written. The -m or -D options should not be used when restarting a simulation from a (binary) simulation file (e.g. created using GfsOutputSimulation).

How do I make all the boundaries of a 2D box no-slip?

GfsBox {
   top =    Boundary { BcDirichlet U 0 }
   bottom = Boundary { BcDirichlet U 0 }
   left =   Boundary { BcDirichlet V 0 }
   right =  Boundary { BcDirichlet V 0 }
}

How do I make boundary conditions time-dependent?

What about this page of the tutorial? As described in the object hierarchy functions can depend on time (just use variable t). You should be able to use this to implement your boundary conditions.

How do I run Gerris in parallel?

See Gerris in parallel.

Personal tools
communication