E. Frequently asked questions

$Id: FAQ.txt,v 1.6 2009-08-14 08:25:37 geuzaine Exp $

This is the Gmsh FAQ

********************************************************************

Section 1: The basics

* 1.1 What is Gmsh?

Gmsh is an automatic three-dimensional finite element mesh generator
with built-in pre- and post-processing facilities. Its design goal is
to provide a simple meshing tool for academic problems with parametric
input and advanced visualization capabilities.

* 1.2 What are the terms and conditions of use?

Gmsh is distributed under the terms of the GNU General Public
License. See the file 'doc/LICENSE' for more information, or go to the
GNU foundation's web site at http://www.gnu.org.

* 1.3 What does 'Gmsh' mean?

Nothing... The name was derived from a previous version called "msh"
(a shortcut for "mesh"), with the "g" prefix added to differentiate
it. The default mesh file format used by Gmsh still uses the ".msh"
extention. 

In English people tend to pronounce 'Gmsh' as "gee-mesh".

* 1.4 Where can I find more information?

http://www.geuz.org/gmsh/ is the primary location to obtain
information about Gmsh. You will for example find a complete reference
manual as well as a searchable archive of the Gmsh mailing list
(gmsh@geuz.org) on this webpage.

********************************************************************

Section 2: Installation

* 2.1 Which OSes does Gmsh run on?

Gmsh is known to run on Windows 2000/XP/Vista, Mac OS X, Linux and
most Unix variants.

* 2.2 Are there additional requirements to run Gmsh?

You should have the OpenGL libraries installed on your system, and in
the path of the library loader. A free replacement for OpenGL can be
found at http://www.mesa3d.org.

* 2.3 How do I compile Gmsh from the source code?

You need cmake (http://www.cmake.org) and a C++ compiler. See the
README.txt file in the top-level source directory for more
information.

* 2.4 Where does Gmsh save its configuration files?

Gmsh will attempt to save temporary files and persistent configuration
options first in the $GMSH_HOME directory, then in the $HOME, $TMP or
$TEMP directories (in that order) if the $GMSH_HOME environment
variable is not defined. If none of these variables are defined, Gmsh
will try to save/load its configuration files from the current working
directory.

********************************************************************

Section 3: General problems

* 3.1 Gmsh (from a binary distribution) complains about missing
  libraries.

On Windows, if your system complains about missing OPENGL32.DLL or
GLU32.DLL libraries, then OpenGL is not properly installed on your
machine. You can download OpenGL from Microsoft's web site, or
directly from http://www.opengl.org.

On Unix try 'ldd gmsh' (or 'otool -L gmsh' on Mac OS X) to check if
all the required shared libraries are installed on your system. If
not, install them. If it still doesn't work, recompile Gmsh from the
sources.

* 3.2 Gmsh keeps re-displaying its graphics when other windows
  partially hide the graphical window.

Disable opaque move in your window manager.

* 3.3 The graphics display very slowly.

Are you are executing Gmsh from a remote host (via the network)
without GLX?  You should turn double buffering off (with the '-nodb'
command line option).

* 3.4 There is an ugly "ghost triangulation" in the vector
  PostScript/PDF files generated by Gmsh!

No, there isn't. This "ghost triangulation" is due to the fact that
most PostScript previewers nowadays antialias the graphic primitives
when they display the page on screen. (For example, in gv, you can
disable antialising with the 'State->Antialias' menu.) You should not
see this ghost triangulation in the printed output (on paper).

* 3.5 How can I save GIF, JPEG, ..., images?

Just choose the appropriate format in 'File->Save As'. By default Gmsh
guesses the format from the file extension, so you can just choose
"myfile.jpg" in the dialog.

* 3.6 How can I save MPEG, AVI, ..., animations?

See question 7.9.

********************************************************************

Section 4: Geometry module

* 4.1 Does Gmsh support NURBS curves/surfaces?

Yes, but only via STEP, IGES or BREP model import (not in .geo
files). Gmsh has to be compiled with OpenCascade support for this to
work.

* 4.2 Gmsh is very slow when I use many transformations (Translate,
  Rotate, Symmetry, Extrude, etc. ). What's wrong?

The default behavior of Gmsh is to check and suppress all duplicate
entities (points, lines and surfaces) each time a transformation
command is issued. This can slow down things a lot if many
transformations are performed. There are two solutions to this
problem:
- you may save the unrolled geometry in another file (e.g. with gmsh
  file.geo -0), and use this new file for subsequent computations;
- or you may set the 'Geometry.AutoCoherence' option to 0. This will
  prevent any automatic duplicate check/replacement. If you still need
  to remove the duplicates entities, simply add 'Coherence;' at
  strategic locations in your geo files (e.g. before the creation of
  line loops, etc.).

* 4.3 How can I display only selected parts of my model?

Use 'Tools->Visibility'. This allows you to select elementary entities
and physical groups, as well as mesh elements, in a variety of ways
(in a list or tree browser, by identification number, interactively,
or per window).

* 4.4 Can I edit STEP/IGES/BRep models?

Not yet. At the moment you can only change characteristic lengths,
define volumes and physical groups, or delete entities. The easiest
way to do this is to merge the model in a .geo file using 'Merge
"file.step";' and add the relevant scripting command after that. We
plan to add more advanced editing features in the future (to delete
entities, to create "mixed" surfaces and volumes, to export in .geo
format, etc.).

********************************************************************

Section 5: Mesh module

* 5.1 What should I do when the 2D unstructured algorithm fails?

Verify that the curves in the model do not self-intersect. If
Mesh.RandomFactor * size(triangle)/size(model) approaches machine
accuracy, increase Mesh.RandomFactor.

If everything fails send us a bug report with the version of your
operating system and the full geometry.

* 5.2 What should I do when the 3D unstructured algorithm fails?

Verify that the surfaces in your model do not self-intersect or
partially overlap. If they don't, try the other 3D algorithms
(Tool->Options->Mesh->General->3D algorithm) or try to adapt the
characteristic lengths in your input file so that the surface mesh
better matches the geometrical details of the model. 

If nothing works, send us a bug report (including your geometry).

* 5.3 The quality of the elements generated by the 3D algorithm is
  very bad.

Use 'Optimize quality' in the mesh menu. 

* 5.4 Non-recombined 3D extruded meshes sometimes fail.

The swapping algorithm is not very clever at the moment. Try to change
the surface mesh a bit, or recombine your mesh to generate prisms or
hexahedra instead of tetrahedra.

* 5.5 Does Gmsh automatically couple unstructured tetrahedral meshes
  and structured hexahedral meshed using pyramids?

No. We need your help to implement this.

* 5.6 Can I explicitly assign region numbers to extruded layers?

No, this feature has been removed in Gmsh 2.0. You must use the
standard entity number instead.

* 5.7 Did you remove the elliptic mesh generator in Gmsh 2.0?

Yes. You can achieve the same result by using the transfinite
algorithm with smoothing (e.g., with "Mesh.Smoothing = 10").

* 5.8 Does Gmsh support curved elements?

Yes, Gmsh can generate both 1st order and 2nd order elements. To
generate second order elements, click on 'Second order' in the mesh
menu after the mesh is completed. To always generate 2nd order
elements, select 'Generate second order elements' in the mesh option
panel. From the command line, you can also use '-order 2'.

* 5.9 Can I import an existing surface mesh in Gmsh and use it to
  build a 3D mesh?

Yes, you can import a surface mesh in any one of the supported mesh
file formats, define a volume, and mesh it. For an example see
'demos/sphere-discrete.geo'.

* 5.10 How do I define boundary conditions or material properties in
  Gmsh?

By design, Gmsh does not try to incorporate every possible definition
of boundary conditions or material properties--this is a job best left
to the solver. Instead, Gmsh provides a simple mechanism to tag groups
of elements, and it is up to the solver to interpret these tags as
boundary conditions, materials, etc. Associating tags with elements in
Gmsh is done by defining Physical entities (Physical Points, Physical
Lines, Physical Surfaces and Physical Volumes). See the reference
manual as well as the tutorials (in particular 'tutorial/t1.geo') for
a detailed description and some examples.

* 5.11 How can I display only the mesh associated with selected
  geometrical entities?

See question 4.3.

* 5.12 How can I "explore" a mesh (for example, to see inside a
  complex structure)?

You can use 'Tools->Clipping Planes' to clip the region of
interest. You can define up to 6 clipping planes in Gmsh (i.e., enough
to define a "cube" inside your model) and each plane can clip either
the geometry, the mesh, the post-processing views, or any combination
of the above.  The clipping planes are defined using the four
coefficients A,B,C,D of the equation A*x+B*y+C*y+D=0, which can be
adjusted interactively by dragging the mouse in the input
fields.

* 5.13 What is the signification of Rho, Eta and Gamma in
  Tools->Statistics?

They measure the quality of the tetrahedra in a mesh:

Gamma ~ inscribed_radius / circumscribed_radius
Eta ~ volume^(2/3) / sum_edge_length^2
Rho ~ min_edge_length / max_edge_length

For the exact definitions, see Geo/MElement.cpp. The graphs plot the
the number of elements vs. the quality measure.

* 5.14 Why don't the vertex and/or elememt numbers on the screen match
  the numbers in the mesh file?

Gmsh reindexes the mesh vertices and elements so that they are
numbered in a continuous sequence in the output files. The numbers
displayed on screen after mesh generation thus usually differ from the
ones saved in the mesh files. To check the actual numbers saved in the
output file just load the mesh file back using File->Open.

********************************************************************

Section 6: Solver module

* 6.1 How do I integrate my own solver with Gmsh?

If you want to simply launch a program from within Gmsh, just edit the
options to define your solver commands (e.g. Solver.Name0,
Solver.Executable0, etc.), and set the ClientServer option to zero
(e.g. Solver.ClientServer0 = 0).

If you want your solver to interact with Gmsh (for error messages,
option definitions, post-processing, etc.), you will need to link your
solver with the GmshClient routines and add the appropriate function
calls inside your program. You will of course also need to define your
solver commands in an option file, but this time you should set the
ClientServer variable to 1 (e.g. Solver.ClientServer = 1). C, C++,
Perl and Python solver examples are available in the source
distribution in the 'utils/solvers' directory.

* 6.2 On Windows, Gmsh does not seem to find the solver
  executable. What's wrong?

The solver executable (for example, 'getdp.exe') has to be in your
path. If it is not specify its location in the 'Command' field.

* 6.3 Can I launch Gmsh from my solver (instead of launching my solver
  from Gmsh) in order to monitor a solution?

Sure. The simplest (but rather crude) approach if to re-launch Gmsh
everytime you want to visualize something (a simple C program showing
how to do this is given in 'utils/misc/callgmsh.c'). A better approach
is to modify your program so that it can communicate with Gmsh over a
socket (see question 6.1 above; you can skip the option file
creation). Then select 'Always listen to incoming connection requests'
in the solver option panel (or run gmsh with the '-listen' command
line option) and Gmsh will always listen for your program on the
Solver.SocketName socket.

********************************************************************

Section 7: Post-processing module

* 7.1 How do I compute a section of a plot?

Use 'Tools->Plugins->Cut Plane'.

* 7.2 Can I save an isosurface to a file?

Yes: first run 'Tools->Plugins->Cut Map' to extract the isosurface,
then use 'View->Save As' to save the new view.

* 7.3 Can Gmsh generate isovolumes?

Yes, with the CutMap plugin (set the ExtractVolume option to -1 or 1
to extract the negative or positive levelset).

* 7.4 How do I animate my plots?

If the views contain multiple time steps, you can press the 'play'
button at the bottom of the graphic window, or change the time step by
hand in the view option panel. You can also use the left and right
arrow keys on your keyboard to change the time step in all visible
views in real time.

If you want to loop through different views instead of time steps, you
can use the 'Loop through views instead of time steps' option in the
view option panel, or use the up and down arrow keys on your keyboard.

* 7.5 How do I visualize a deformed mesh?

Load a vector view containing the displacement field, and set 'Vector
display' to 'Displacement' in View->Options->Aspect. If the
displacement is too small (or too large), you can scale it with the
'Displacement factor' option. (Remember that you can drag the mouse in
all numeric input fields to slide the value!)

Another option is to use the 'General transformation expressions' (in
View->Options->Offset) on a scalar view, with the displacement map
selected as the data source.

* 7.6 Can I visualize a field on a deformed mesh?

Yes, there are several ways to do that. 

The easiest is to load two views: the first one containing a
displacement field (a vector view that will be used to deform the
mesh), and the second one containing the field you want to display
(this view has to contain the same number of elements as the
displacement view). You should then set 'Vector display' to
'Displacement' in the first view, as well as set 'Data source' to
point to the second view. (You might want to make the second view
invisible, too. If you want to amplify or decrease the amount of
deformation, just modify the 'Displacement factor' option.)

Another solution is to use the 'General transformation expressions'
(in 'View->Options->Offset') on the field you want to display, with
the displacement map selected as the data source.

And yet another solution is to use the Warp plugin.

* 7.7 Can I color the arrows representing a vector field with data
  from a scalar field?

Yes: load both the vector and the scalar fields (the two views must
have the same number of elements) and, in the vector field options,
select the scalar view in 'Data source'.

* 7.8 Can I color isovalue surfaces with data from another scalar
  view?

Yes, using either the CutMap plugin (with the 'dView' option) or the
Evaluate plugin.

* 7.9 Is there a way to save animations?

Yes, using scripts. Have a look at 'tutorial/t8.geo' or
'demos/anim.script' for some examples.

* 7.10 Is there a way to visualize only certain components of
  vector/tensor fields?

Yes, using 'Tools->Plugins->Extract'.

* 7.11 Can I do arithmetic operations on a view? Can I perform
  operations involving different views?

Yes, with the Evaluate plugin.

* 7.12 Some plugins seem to create empty views. What's wrong?

There can be several reasons:

- the plugin might be written for specific element types only (for
  example, only for scalar triangles or tetrahedra). In that case, you
  should transform your view before running the plugin (you can use
  Plugin(DecomposeinSimplex) to transform all quads, hexas, prisms and
  pyramids into triangles and tetrahedra).

- the plugin might expect a mesh while all you provide is a point
  cloud. In 2D, you can use Plugin(Triangulate) to transform a point
  cloud into a triangulated surface. A 3D version of this plugin is
  not available yet but it is on our TODO list.

- the input parameters are out of range.

In any case, you can automatically remove all empty views with
'View->Remove->Empty Views' in the GUI, or with "Delete Empty Views;"
in a script.

* 7.13 How can I see "inside" a complicated post-processing view?

See question 5.12. 

When viewing 3D scalar fields, you can also modify the colormap
('Tools->Options->View->Map') to make the iso-surfaces "transparent":
either by holding 'Ctrl' while dragging the mouse to draw the alpha
channel by hand, or by using the 'a', 'Ctrl+a', 'p' and 'Ctrl+p'
keyboard shortcuts.

Yet another (destructive) option is to use the ExtractVolume option in
the CutSphere or CutPlane plugins.

* 7.14 I am loading a valid 3D scalar view but Gmsh does not display
  anything!

If your dataset is constant per element make sure you don't use the
'Iso-values' interval type in 'Tools->Options->View->Range'.