This is the Gmsh Reference Manual for Gmsh 2.7 ().

Copyright © 1997-2013 Christophe Geuzaine, Jean-François Remacle

Gmsh
****

Christophe Geuzaine and Jean-François Remacle

Gmsh is an automatic 3D finite element mesh generator with build-in pre- and post-processing facilities. This is the Gmsh Reference Manual for Gmsh 2.7 ().

Obtaining Gmsh
**************

The source code and various pre-compiled versions of Gmsh (for Windows, Mac and Unix) can be downloaded from http://geuz.org/gmsh/. Gmsh is also directly available in pre-packaged form in various Linux and BSD distributions (Debian, Ubuntu, FreeBSD, ...).

If you use Gmsh, we would appreciate that you mention it in your work by citing the following paper: ``C. Geuzaine and J.-F. Remacle, Gmsh: a three-dimensional finite element mesh generator with built-in pre- and post-processing facilities. International Journal for Numerical Methods in Engineering, Volume 79, Issue 11, pages 1309-1331, 2009''.  A preprint of that paper as well as other references and the latest news about Gmsh development are available on http://geuz.org/gmsh/.

Copying conditions
******************

Gmsh is ``free software''; this means that everyone is free to use it and to redistribute it on a free basis. Gmsh is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do.  What is not allowed is to try to prevent others from further sharing any version of Gmsh that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of Gmsh, that you receive source code or else can get it if you want it, that you can change Gmsh or use pieces of Gmsh in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights.  For example, if you distribute copies of Gmsh, you must give the recipients all the rights that you have.  You must make sure that they, too, receive or can get the source code.  And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for Gmsh.  If Gmsh is modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.

The precise conditions of the license for Gmsh are found in the General Public License that accompanies the source code (see License). Further information about this license is available from the GNU Project webpage http://www.gnu.org/copyleft/gpl-faq.html.  Detailed copyright information can be found in Copyright and credits.

If you want to integrate parts of Gmsh into a closed-source software, or want to sell a modified closed-source version of Gmsh, you will need to obtain a different license. Please contact us directly (http://geuz.org) for more information.

Overview
********

Gmsh is a three-dimensional finite element grid generator with a build-in CAD engine and post-processor. Its design goal is to provide a fast, light and user-friendly meshing tool with parametric input and advanced visualization capabilities.

Gmsh is built around four modules: geometry, mesh, solver and post-processing. All geometrical, mesh, solver and post-processing instructions are prescribed either interactively using the graphical user interface (GUI) or in text files using Gmsh's own scripting language.  Interactive actions generate language bits in the input files, and vice versa. This makes it possible to automate all treatments, using loops, conditionals and external system calls. A brief description of the four modules is given hereafter.

Geometry: geometrical entity definition
=======================================

Gmsh uses a boundary representation (``BRep'') to describe geometries. Models are created in a bottom-up flow by successively defining points, oriented lines (line segments, circles, ellipses, splines, ...), oriented surfaces (plane surfaces, ruled surfaces, triangulated surfaces, ...) and volumes. Groups of geometrical entities (called ``physical groups'') can also be defined, based on these elementary geometric entities. Gmsh's scripting language allows all geometrical entities to be fully parametrized.

Mesh: finite element mesh generation
====================================

A finite element mesh is a tessellation of a given subset of the three-dimensional space by elementary geometrical elements of various shapes (in Gmsh's case: lines, triangles, quadrangles, tetrahedra, prisms, hexahedra and pyramids), arranged in such a way that if two of them intersect, they do so along a face, an edge or a node, and never otherwise. All the finite element meshes produced by Gmsh are considered as ``unstructured'', even if they were generated in a ``structured'' way (e.g., by extrusion). This implies that the elementary geometrical elements are defined only by an ordered list of their nodes but that no predefined order relation is assumed between any two elements.

The mesh generation is performed in the same bottom-up flow as the geometry creation: lines are discretized first; the mesh of the lines is then used to mesh the surfaces; then the mesh of the surfaces is used to mesh the volumes. In this process, the mesh of an entity is only constrained by the mesh of its boundary. For example, in three dimensions, the triangles discretizing a surface will be forced to be faces of tetrahedra in the final 3D mesh only if the surface is part of the boundary of a volume; the line elements discretizing a curve will be forced to be edges of tetrahedra in the final 3D mesh only if the curve is part of the boundary of a surface, itself part of the boundary of a volume; a single node discretizing a point in the middle of a volume will be forced to be a vertex of one of the tetrahedra in the final 3D mesh only if this point is connected to a curve, itself part of the boundary of a surface, itself part of the boundary of a volume. This automatically assures the conformity of the mesh when, for example, two surfaces share a common line. But this also implies that the discretization of an ``isolated'' (N-1)-th dimensional entity inside an N-th dimensional entity does not constrain the N-th dimensional mesh---unless it is explicitly told to do so (see Miscellaneous mesh commands).  Every meshing step is constrained by a ``size field'' (sometimes called ``characteristic length field''), which prescribes the desired size of the elements in the mesh. This size field can be uniform, specified by values associated with points in the geometry, or defined by general ``fields'' (for example related to the distance to some boundary, to a arbitrary scalar field defined on another mesh, etc.).

For each meshing step, all structured mesh directives are executed first, and serve as additional constraints for the unstructured parts (Note that mixing structured volume grids with unstructured volume grids generated with the default 3D Delaunay algorithm can result, in certain cases, to non-conform surface meshes on their shared boundary. If this happens, you may consider using the frontal algorithm for the unstructured part.).

Solver: external solver interface
=================================

External solvers can be interfaced with Gmsh through Unix or TCP/IP sockets, which permits to modify solver parameters, launch external computations and process the results directly from within Gmsh's post-processing module. The default solver interfaced with Gmsh is GetDP (http://geuz.org/getdp/). Examples on how to interface other solvers are available in the source distribution (in the utils/solvers/ directory).

Post-processing: scalar, vector and tensor field visualization
==============================================================

Gmsh can load and manipulate multiple post-processing scalar, vector or tensor maps along with the geometry and the mesh. Scalar fields are represented by iso-value lines/surfaces or color maps, while vector fields are represented by three-dimensional arrows or displacement maps. Post-processing functions include section computation, offset, elevation, boundary and component extraction, color map and range modification, animation, vector graphic output, etc. All the post-processing options can be accessed either interactively or through the input script files. Scripting permits to automate all post-processing operations, as for example to create animations. User-defined operations can also be performed on post-processing views through dynamically loadable plugins.

What Gmsh is pretty good at ...
===============================

Here is a tentative list of what Gmsh does best:

  * quickly describe simple and/or ``repetitive'' geometries, thanks to user-defined functions, loops, conditionals and includes (see User-defined functions, Loops and conditionals, and General commands);

  * parametrize these geometries. Gmsh's scripting language enables all commands and command arguments to depend on previous calculations (see Expressions, and Geometry commands);

  * generate 1D, 2D and 3D simplicial (i.e., using line segments, triangles and tetrahedra) finite element meshes for CAD models in their native format (without translations) when linked with the appropriate CAD kernel (see Mesh module);

  * specify target element sizes accurately. Gmsh provides several mechanisms to control the size of the elements in the final mesh: through interpolation from sizes specified at geometry points or using flexible mesh size fields (see Mesh commands);

  * create simple extruded geometries and meshes (see Geometry commands, and Mesh commands);

  * interact with external solvers through a simple client-server architecture (see Solver module);

  * visualize and export computational results in a great variety of ways. Gmsh can display scalar, vector and tensor datasets, perform various operations on the resulting post-processing views (see Post-processing module), can export plots in many different formats (see General options list), and can generate complex animations (see General tools, and t8.geo);

  * run on low end machines and/or machines with no graphical interface. Gmsh can be compiled with or without the GUI, and all versions can be used either interactively or directly from the command line (see Running Gmsh on your system);

  * configure your preferred options. Gmsh has a large number of configuration options that can be set interactively using the GUI, scattered inside command files, changed on the fly in scripts, set in per-user configuration files, or specified on the command-line (see Running Gmsh on your system and Options);

  * and do all the above on various platforms (Windows, Mac and Unix), for free (see Copying conditions), using simple script files and/or a small but powerful GUI.

... and what Gmsh is not so good at
===================================

As of version 2.7, here are some known weaknesses of Gmsh:

  * the BRep approach for describing geometries can become inconvenient/inefficient for large models. For complex models, or if you want to use a solid-modeler approach, you should link Gmsh with an external CAD kernel and import native files directly. (The binary versions available on http://geuz.org/gmsh/ are linked with the free CAD kernel OpenCASCADE, which enables native BREP import as well as STEP and IGES import.)

  * Gmsh's internal CAD engine is fairly limited: it only handles simple primitives and does not perform any complex geometrical operations (e.g. no calculation of intersections). For such features you should link Gmsh with an external CAD kernel (see above).

  * Gmsh is not a multi-bloc mesh generator: all meshes produced by Gmsh are conforming in the sense of finite element meshes;

  * Gmsh's user interface is only exposing a limited number of the available features, and many aspects of the interface could be enhanced (especially manipulators).

  * Gmsh's scripting language is fairly limited, providing only very crude loop controls and user-defined functions, with no local variables.

  * there is no global ``undo'' capability. You will often need to edit a text file to correct mistakes.

If you have the skills and some free time, feel free to join the project: we gladly accept any code contributions (see Information for developers) to remedy the aforementioned (and all other) shortcomings!

Bug reports
===========

If you think you have found a bug in Gmsh, you can report it by email to the public Gmsh mailing list at gmsh@geuz.org, or file it directly into our bug tracking database at https://geuz.org/trac/gmsh/report (login: gmsh, password: gmsh). Please send as precise a description of the problem as you can, including sample input files that produce the bug. Don't forget to mention both the version of Gmsh and the version of your operation system (see Command-line options to see how to get this information).

See Frequently asked questions, and the bug tracking system to see which problems we already know about.

How to read this reference manual?
**********************************

Gmsh can be used at three levels:

 1. as a stand-alone graphical program, driven by an interactive graphical user interface (GUI);

 2. as a stand-alone script-driven program;

 3. as a library.

You can skip most of this reference manual if you only want to use Gmsh at the first level (i.e., interactively with the GUI). Just read the next chapter (see Running Gmsh on your system) to learn how to launch Gmsh on your system, then go experiment with the GUI and the tutorial files (see Tutorial) provided in the distribution. Screencasts that show how to use the GUI are available here: http://geuz.org/gmsh/screencasts/.

The aim of the reference manual is to explain everything you need to use Gmsh at the second level, i.e., using the built-in scripting language. A Gmsh script file is an ASCII text file that contains instructions in Gmsh's built-in scripting language. Such a file is interpreted by Gmsh's parser, and can be given any extension (or no extension at all). By convention, Gmsh uses the .geo extension for geometry scripts, and the .pos extension for parsed post-processing datasets. Once you master the tutorial (read the source files: they are heavily commented!), start reading chapter General tools, then proceed with the next four chapters, which detail the syntax of the geometry, mesh, solver and post-processing scripting commands. You will see that most of the interactive actions in the GUI have a direct equivalent in the scripting language. If you want to use Gmsh as a pre- or post-processor for your own software, you will also want to learn about the non-scripting input/output files that Gmsh can read/write. In addition to Gmsh's native ``MSH'' file format (see File formats), Gmsh can read/write many standard mesh files, depending on how it was built: check the `File->Save As' menu for a list of available formats.

Finally, to use Gmsh at the third level (i.e., to link the Gmsh library with your own code), you will need to learn the internal Gmsh Application Programming Interface (API). No complete documentation of this API is available yet; a good starting point is Source code structure, which gives a short introduction to Gmsh's internal source code structure. Then have a look e.g. at the examples in the utils/api_demos/ directory in the source code. Due to the many possible configuration options (and associated external dependencies), we currently do not distibute precompiled versions of the Gmsh library. To build the library see the instructions in the top-level README.txt file in the source distribution.

Syntactic rules used in the manual
==================================

Here are the rules we tried to follow when writing this reference manual. Note that metasyntactic variable definitions stay valid throughout the manual (and not only in the sections where the definitions appear).

 1. Keywords and literal symbols are printed like this.

 2. Metasyntactic variables (i.e., text bits that are not part of the syntax, but stand for other text bits) are printed like THIS.

 3. A colon (:) after a metasyntactic variable separates the variable from its definition.

 4. Optional rules are enclosed in < > pairs.

 5. Multiple choices are separated by |.

 6. Three dots (...) indicate a possible (multiple) repetition of the preceding rule.

Running Gmsh on your system
***************************

Interactive mode
================

To launch Gmsh in interactive mode, just double-click on the Gmsh icon, or type

     > gmsh

at your shell prompt in a terminal. This will open the main Gmsh window, with a tree-like menu on the left, a graphic area on the right, and a status bar at the bottom. (You can detach the tree menu using `Window->Attach/Detach Menu'.)

To open the first tutorial file (see Tutorial), select the `File->Open' menu, and choose t1.geo. When using a terminal, you can specify the file name directly on the command line, i.e.:

     > gmsh t1.geo

To perform the mesh generation, go to the mesh module (by selecting `Mesh' in the tree) and choose the dimension (`1D' will mesh all the lines; `2D' will mesh all the surfaces---as well as all the lines if `1D' was not called before; `3D' will mesh all the volumes---and all the surfaces if `2D' was not called before). To save the resulting mesh in the current mesh format click on `Save', or select the appropriate format and file name with the `File->Save As' menu. The default mesh file name is based on the name of the current active model, with an appended extension depending on the mesh format (Nearly all the interactive commands have keyboard shortcuts: see Keyboard shortcuts, or select `Help->Keyboard and Mouse Usage' in the menu. For example, to quickly save a mesh, you can press Ctrl+Shift+s.).

To create a new geometry or to modify an existing geometry, select 'Geometry' in the tree.  For example, to create a spline, select `Elementary', `Add', `New' and `Spline'. You will then be asked to select a list of points, and to type e to finish the selection (or q to abort it). Once the interactive command is completed, a text string is automatically added at the end of the current script file. You can edit the script file by hand at any time by pressing the `Edit' button in the `Geometry' menu and then reloading the model by pressing `Reload'. For example, it is often faster to define variables and points directly in the script file, and then use the GUI to define the lines, the surfaces and the volumes interactively.

Several files can be loaded simultaneously in Gmsh. When specified on the command line, the first one defines the active model and the others are `merged' into this model. You can merge such files with the `File->Merge' menu. For example, to merge the post-processing views contained in the files view1.pos and view5.msh together with the geometry of the first tutorial t1.geo, you can type the following command:

     > gmsh t1.geo view1.pos view5.msh

In the Post-Processing module (select `Post-Processing' in the tree), three items will appear, respectively labeled `A scalar map', `Nodal scalar map' and `Element 1 vector'. In this example the views contain several time steps: you can loop through them with the small ``remote-control'' icons in the status bar. A mouse click on the view name will toggle the visibility of the selected view, while a click on the arrow button on the right will provide access to the view's options.

Note that all the options specified interactively can also be directly specified in the script files. You can save the current options of the current active model with the `File->Save Model Options'. This will create a new option file with the same filename as the active model, but with an extra .opt extension added. The next time you open this model, the associated options will be automatically loaded, too.  To save the current options as your default preferences for all future Gmsh sessions, use the `File->Save Options As Default' menu instead. Finally, you can also save the current options in an arbitrary file by choosing the `Gmsh options' format in `File->Save As'.

For more information about available options (and how to reset them to their default values), see Options. A full list of options with their current values is also available in the `Help->Current Options' menu.

Non-interactive mode
====================

Gmsh can be run non-interactively in `batch' mode, without GUI (If you compile Gmsh without the GUI, this is the only mode you have access to.). For example, to mesh the first tutorial in batch mode, just type:

     > gmsh t1.geo -2

To mesh the same example, but with the background mesh available in the file bgmesh.pos, type:

     > gmsh t1.geo -2 -bgm bgmesh.pos

For the list of all command-line options, see Command-line options.

Command-line options
====================

     [file commandline.texi not included]

Mouse actions
=============

     [file mouse.texi not included]

For a 2 button mouse, Middle button = Shift+Left button.

For a 1 button mouse, Middle button = Shift+Left button, Right button = Alt+Left button.

Keyboard shortcuts
==================

(On Mac Ctrl is replaced by Cmd (the `Apple key') in the shortcuts below.)

     [file shortcuts.texi not included]

General tools
*************

This chapter describes the general commands and options that can be used in Gmsh's script files. By ``general'', we mean ``not specifically related to one of the geometry, mesh, solver or post-processing modules''. Commands peculiar to these modules will be introduced in Geometry module, Mesh module, Solver module, and Post-processing module, respectively.

Comments
========

Gmsh script files support both C and C++ style comments:

 1. any text comprised between /* and */ pairs is ignored;

 2. the rest of a line after a double slash // is ignored.

These commands won't have the described effects inside double quotes or inside keywords. Also note that `white space' (spaces, tabs, new line characters) is ignored inside all expressions.

Expressions
===========

The two constant types used in Gmsh scripts are REAL and STRING (there is no integer type).  These types have the same meaning and syntax as in the C or C++ programming languages.

Floating point expressions
--------------------------

Floating point expressions (or, more simply, ``expressions'') are denoted by the metasyntactic variable EXPRESSION (remember the definition of the syntactic rules in Syntactic rules), and are evaluated during the parsing of the script file:

     EXPRESSION:
       REAL |
       STRING |
       STRING [ EXPRESSION ] |
       # STRING [ ] |
       ( EXPRESSION ) |
       OPERATOR-UNARY-LEFT EXPRESSION |
       EXPRESSION OPERATOR-UNARY-RIGHT |
       EXPRESSION OPERATOR-BINARY EXPRESSION |
       EXPRESSION OPERATOR-TERNARY-LEFT EXPRESSION OPERATOR-TERNARY-RIGHT EXPRESSION |
       BUILT-IN-FUNCTION |
       REAL-OPTION |
       StrFind(CHAR-EXPRESSION, CHAR-EXPRESSION) |
       TextAttributes(CHAR-EXPRESSION<,CHAR-EXPRESSION...>)|
       GetValue("STRING", EXPRESSION)

Such EXPRESSIONs are used in most of Gmsh's scripting commands.  The third and fourth cases in this definition permit to extract one item from a list (see below) and get the size of a list, respectively. The operators OPERATOR-UNARY-LEFT, OPERATOR-UNARY-RIGHT, OPERATOR-BINARY, OPERATOR-TERNARY-LEFT and OPERATOR-TERNARY-RIGHT are defined in Operators. For the definition of BUILT-IN-FUNCTIONs, see Built-in functions. The various REAL-OPTIONs are listed in Options. StrFind searches the first CHAR-EXPRESSION for any occurrence of the second CHAR-EXPRESSION. TextAttributes creates attributes for text strings.

The last case in the definition allows to ask the user for a value interactively. For example, inserting GetValue("Value of parameter alpha?", 5.76) in an input file will query the user for the value of a certain parameter alpha, assuming the default value is 5.76. If the option General.NoPopup is set (see General options list), no question is asked and the default value is automatically used.

List of expressions are also widely used, and are defined as:

     EXPRESSION-LIST:
       EXPRESSION-LIST-ITEM <, EXPRESSION-LIST-ITEM> ...

with

     EXPRESSION-LIST-ITEM:
       EXPRESSION |
       EXPRESSION : EXPRESSION |
       EXPRESSION : EXPRESSION : EXPRESSION |
       STRING [ ] |
       STRING ( ) |
       List [ STRING ] |
       STRING [ { EXPRESSION-LIST } ] |
       STRING ( { EXPRESSION-LIST } ) |
       Point { EXPRESSION } |
       TRANSFORM |
       EXTRUDE
       Point { EXPRESSION } |
       Point|Line|Surface|Volume "*" |
       Physical Point|Line|Surface|Volume { EXPRESSION-LIST }

The second case in this last definition permits to create a list containing the range of numbers comprised between two EXPRESSIONs, with a unit incrementation step. The third case also permits to create a list containing the range of numbers comprised between two EXPRESSIONs, but with a positive or negative incrementation step equal to the third EXPRESSION. The fourth, fifth and sixth cases permit to reference an expression list.  The seventh and eight cases permit to reference an expression sublist (whose elements are those corresponding to the indices provided by the EXPRESSION-LIST).  The next two cases permit to retrieve the indices of entities created through geometrical transformations and extrusions (see Transformations, and Extrusions). The last three cases permit to retrieve the coordinates of a given geometry point (see Points), to retrieve the id numbers of all points, lines, surfaces or volumes in the model, or to retrieve the elementary entities making up physical groups.

To see the practical use of such expressions, have a look at the first couple of examples in Tutorial. Note that, in order to lighten the syntax, you can omit the braces {} enclosing an EXPRESSION-LIST if this EXPRESSION-LIST only contains a single item. Also note that a braced EXPRESSION-LIST can be preceded by a minus sign in order to change the sign of all the EXPRESSION-LIST-ITEMs.

Character expressions
---------------------

Character expressions are defined as:

     CHAR-EXPRESSION:
       "STRING" |
       Today |
       StrPrefix ( CHAR-EXPRESSION ) |
       StrRelative ( CHAR-EXPRESSION ) |
       StrCat ( CHAR-EXPRESSION , CHAR-EXPRESSION ) |
       Sprintf ( CHAR-EXPRESSION , EXPRESSION-LIST ) |
       Sprintf ( CHAR-EXPRESSION ) |
       Sprintf ( CHAR-OPTION ) |
       GetEnv ( CHAR-EXPRESSION ) |
       GetString ( CHAR-EXPRESSION , CHAR-EXPRESSION )

The third and fourth cases in this definition permit to take the prefix (e.g. to remove the extension) or the relative path of a string. The fifth case permits to concatenate two character expressions, and the sixth and seventh are equivalent to the sprintf C function (where CHAR-EXPRESSION is a format string that can contain floating point formatting characters: %e, %g, etc.). The eigth case permits to use the value of a CHAR-OPTION as a CHAR-EXPRESSION. The ninth case gets the value of an environment variable from the operating system. The last case in the definition allows to ask the user for a value interactively. The various CHAR-OPTIONs are listed in Options.

Character expressions are mostly used to specify non-numeric options and input/output file names. See t8.geo, for an interesting usage of CHAR-EXPRESSIONs in an animation script.

Color expressions
-----------------

Colors expressions are hybrids between fixed-length braced EXPRESSION-LISTs and STRINGs:

     COLOR-EXPRESSION:
       STRING |
       { EXPRESSION, EXPRESSION, EXPRESSION } |
       { EXPRESSION, EXPRESSION, EXPRESSION, EXPRESSION } |
       COLOR-OPTION

The first case permits to use the X Windows names to refer to colors, e.g., Red, SpringGreen, LavenderBlush3, ... (see Common/Colors.h in the source code for a complete list). The second case permits to define colors by using three expressions to specify their red, green and blue components (with values comprised between 0 and 255). The third case permits to define colors by using their red, green and blue color components as well as their alpha channel. The last case permits to use the value of a COLOR-OPTION as a COLOR-EXPRESSION. The various COLOR-OPTIONs are listed in Options.

See t3.geo, for an example of the use of color expressions.

Operators
=========

Gmsh's operators are similar to the corresponding operators in C and C++. Here is the list of the unary, binary and ternary operators currently implemented.

OPERATOR-UNARY-LEFT:

-
     Unary minus.

!
     Logical not.

OPERATOR-UNARY-RIGHT:

++
     Post-incrementation.

--
     Post-decrementation.

OPERATOR-BINARY:

^
     Exponentiation.

*
     Multiplication.

/
     Division.

%
     Modulo.

+
     Addition.

-
     Subtraction.

==
     Equality.

!=
     Inequality.

>
     Greater.

>=
     Greater or equality.

<
     Less.

<=
     Less or equality.

&&
     Logical `and'.

||
     Logical `or'. (Warning: the logical `or' always implies the evaluation of both arguments.  That is, unlike in C or C++, the second operand of || is evaluated even if the first one is true).

OPERATOR-TERNARY-LEFT:

?

OPERATOR-TERNARY-RIGHT:

:
     The only ternary operator, formed by OPERATOR-TERNARY-LEFT and OPERATOR-TERNARY-RIGHT, returns the value of its second argument if the first argument is non-zero; otherwise it returns the value of its third argument.

The evaluation priorities are summarized below (The affectation operators are introduced in General commands.) (from stronger to weaker, i.e., * has a highest evaluation priority than +). Parentheses () may be used anywhere to change the order of evaluation:

 1. (), [], ., #

 2. ^

 3. !, ++, --, - (unary)

 4. *, /, %

 5. +, -

 6. <, >, <=, >=

 7. ==, !=

 8. &&

 9. ||

 10. ?:

 11. =, +=, -=, *=, /=

Built-in functions
==================

A built-in function is composed of an identifier followed by a pair of parentheses containing an EXPRESSION-LIST (the list of its arguments) (For compatibility with GetDP (http://geuz.org/getdp/), parentheses can be replaced by brackets [].). Here is the list of the built-in functions currently implemented:

BUILD-IN-FUNCTION:

Acos ( EXPRESSION )
     Arc cosine (inverse cosine) of an EXPRESSION in [-1,1]. Returns a value in [0,Pi].

Asin ( EXPRESSION )
     Arc sine (inverse sine) of an EXPRESSION in [-1,1]. Returns a value in [-Pi/2,Pi/2].

Atan ( EXPRESSION )
     Arc tangent (inverse tangent) of EXPRESSION. Returns a value in [-Pi/2,Pi/2].

Atan2 ( EXPRESSION, EXPRESSION )
     Arc tangent (inverse tangent) of the first EXPRESSION divided by the second. Returns a value in [-Pi,Pi].

Ceil ( EXPRESSION )
     Rounds EXPRESSION up to the nearest integer.

Cos ( EXPRESSION )
     Cosine of EXPRESSION.

Cosh ( EXPRESSION )
     Hyperbolic cosine of EXPRESSION.

Exp ( EXPRESSION )
     Returns the value of e (the base of natural logarithms) raised to the power of EXPRESSION.

Fabs ( EXPRESSION )
     Absolute value of EXPRESSION.

Fmod ( EXPRESSION, EXPRESSION )
     Remainder of the division of the first EXPRESSION by the second, with the sign of the first.

Floor ( EXPRESSION )
     Rounds EXPRESSION down to the nearest integer.

Hypot ( EXPRESSION, EXPRESSION )
     Returns the square root of the sum of the square of its two arguments.

Log ( EXPRESSION )
     Natural logarithm of EXPRESSION (EXPRESSION > 0).

Log10 ( EXPRESSION )
     Base 10 logarithm of EXPRESSION (EXPRESSION > 0).

Modulo ( EXPRESSION, EXPRESSION )
     see Fmod( EXPRESSION, EXPRESSION ).

Rand ( EXPRESSION )
     Random number between zero and EXPRESSION.

Sqrt ( EXPRESSION )
     Square root of EXPRESSION (EXPRESSION >= 0).

Sin ( EXPRESSION )
     Sine of EXPRESSION.

Sinh ( EXPRESSION )
     Hyperbolic sine of EXPRESSION.

Tan ( EXPRESSION )
     Tangent of EXPRESSION.

Tanh ( EXPRESSION )
     Hyperbolic tangent of EXPRESSION.

User-defined functions
======================

User-defined functions take no arguments, and are evaluated as if a file containing the function body was included at the location of the Call statement.

Function STRING
     Begins the declaration of a user-defined function named STRING. The body of the function starts on the line after `Function STRING', and can contain any Gmsh command.

Return
     Ends the body of the current user-defined function. Function declarations cannot be imbricated.

Call STRING;
     Executes the body of a (previously defined) function named STRING.

See t5.geo, for an example of a user-defined function. A shortcoming of Gmsh's scripting language is that all variables are ``public''. Variables defined inside the body of a function will thus be available outside, too!

Loops and conditionals
======================

Loops and conditionals are defined as follows, and can be imbricated:

For ( EXPRESSION : EXPRESSION )
     Iterates from the value of the first EXPRESSION to the value of the second EXPRESSION, with a unit incrementation step. At each iteration, the commands comprised between `For ( EXPRESSION : EXPRESSION )' and the matching EndFor are executed.

For ( EXPRESSION : EXPRESSION : EXPRESSION )
     Iterates from the value of the first EXPRESSION to the value of the second EXPRESSION, with a positive or negative incrementation step equal to the third EXPRESSION. At each iteration, the commands comprised between `For ( EXPRESSION : EXPRESSION : EXPRESSION )' and the matching EndFor are executed.

For STRING In { EXPRESSION : EXPRESSION }
     Iterates from the value of the first EXPRESSION to the value of the second EXPRESSION, with a unit incrementation step. At each iteration, the value of the iterate is affected to an expression named STRING, and the commands comprised between `For STRING In { EXPRESSION : EXPRESSION }' and the matching EndFor are executed.

For STRING In { EXPRESSION : EXPRESSION : EXPRESSION }
     Iterates from the value of the first EXPRESSION to the value of the second EXPRESSION, with a positive or negative incrementation step equal to the third EXPRESSION. At each iteration, the value of the iterate is affected to an expression named STRING, and the commands comprised between `For STRING In { EXPRESSION : EXPRESSION : EXPRESSION }' and the matching EndFor are executed.

EndFor
     Ends a matching For command.

If ( EXPRESSION )
     The body enclosed between `If ( EXPRESSION )' and the matching Endif is evaluated if EXPRESSION is non-zero.

EndIf
     Ends a matching If command.

See t5.geo, for an example of For and If commands. Gmsh does not provide any Else (or similar) command at the time of this writing.

General commands
================

The following commands can be used anywhere in a Gmsh script:

STRING = EXPRESSION;
     Creates a new expression identifier STRING, or affects EXPRESSION to an existing expression identifier. Thirteen expression identifiers are predefined (hardcoded in Gmsh's parser):

     Pi
          Returns 3.1415926535897932.

     GMSH_MAJOR_VERSION
          Returns Gmsh's major version number.

     GMSH_MINOR_VERSION
          Returns Gmsh's minor version number.

     GMSH_PATCH_VERSION
          Returns Gmsh's patch version number.

     MPI_Size
          Returns the number of processors on which Gmsh is running (always 1, except if you compiled Gmsh's parallel extensions).

     MPI_Rank
          Returns the rank of the current processor.

     newp
          Returns the next available point number. As explained in Geometry module, a unique number must be associated with every geometrical point: newp permits to know the highest number already attributed (plus one). This is mostly useful when writing user-defined functions (see User-defined functions) or general geometric primitives, when one does not know a priori which numbers are already attributed, and which ones are still available.

     newl
          Returns the next available line number.

     news
          Returns the next available surface number.

     newv
          Returns the next available volume number.

     newll
          Returns the next available line loop number.

     newsl
          Returns the next available surface loop number.

     newreg
          Returns the next available region number. That is, newreg returns the maximum of newp, newl, news, newv, newll, newsl and all physical entity numbers (For compatibility purposes, the behavior of newl, news, newv and newreg can be modified with the Geometry.OldNewReg option (see Geometry options list).).

STRING = { };
     Creates a new expression list identifier STRING with an empty list.

STRING = { EXPRESSION-LIST };
     Creates a new expression list identifier STRING with the list EXPRESSION-LIST, or affects EXPRESSION-LIST to an existing expression list identifier. The following syntax is also allowed: STRING[] = { EXPRESSION-LIST };

STRING [ { EXPRESSION-LIST } ] = { EXPRESSION-LIST };
     Affects each item in the right hand side EXPRESSION-LIST to the elements (indexed by the left hand side EXPRESSION-LIST) of an existing expression list identifier. The two EXPRESSION-LISTs must contain the same number of items.

STRING ( { EXPRESSION-LIST } ) = { EXPRESSION-LIST };
     Same as above.

STRING += EXPRESSION;
     Adds and affects EXPRESSION to an existing expression identifier.

STRING -= EXPRESSION;
     Subtracts and affects EXPRESSION to an existing expression identifier.

STRING *= EXPRESSION;
     Multiplies and affects EXPRESSION to an existing expression identifier.

STRING /= EXPRESSION;
     Divides and affects EXPRESSION to an existing expression identifier.

STRING += { EXPRESSION-LIST };
     Appends EXPRESSION-LIST to an existing expression list or creates a new expression list with EXPRESSION-LIST.

STRING -= { EXPRESSION-LIST };
     Removes the items in EXPRESSION-LIST from the existing expression list.

STRING [ { EXPRESSION-LIST } ] += { EXPRESSION-LIST };
     Adds and affects, item per item, the right hand side EXPRESSION-LIST to an existing expression list identifier.

STRING [ { EXPRESSION-LIST } ] -= { EXPRESSION-LIST };
     Subtracts and affects, item per item, the right hand side EXPRESSION-LIST to an existing expression list identifier.

STRING [ { EXPRESSION-LIST } ] *= { EXPRESSION-LIST };
     Multiplies and affects, item per item, the right hand side EXPRESSION-LIST to an existing expression list identifier.

STRING [ { EXPRESSION-LIST } ] /= { EXPRESSION-LIST };
     Divides and affects, item per item, the right hand side EXPRESSION-LIST to an existing expression list identifier.

STRING = CHAR-EXPRESSION;
     Creates a new character expression identifier STRING with a given CHAR-EXPRESSION.

REAL-OPTION = EXPRESSION;
     Affects EXPRESSION to a real option.

CHAR-OPTION = CHAR-EXPRESSION;
     Affects CHAR-EXPRESSION to a character option.

COLOR-OPTION = COLOR-EXPRESSION;
     Affects COLOR-EXPRESSION to a color option.

REAL-OPTION += EXPRESSION;
     Adds and affects EXPRESSION to a real option.

REAL-OPTION -= EXPRESSION;
     Subtracts and affects EXPRESSION to a real option.

REAL-OPTION *= EXPRESSION;
     Multiplies and affects EXPRESSION to a real option.

REAL-OPTION /= EXPRESSION;
     Divides and affects EXPRESSION to a real option.

Abort;
     Aborts the current script.

Exit;
     Exits Gmsh.

Printf ( CHAR-EXPRESSION <, EXPRESSION-LIST> );
     Prints a character expression in the information window and/or on the terminal. Printf is equivalent to the printf C function: CHAR-EXPRESSION is a format string that can contain formatting characters (%f, %e, etc.). Note that all EXPRESSIONs are evaluated as floating point values in Gmsh (see Expressions), so that only valid floating point formatting characters make sense in CHAR-EXPRESSION. See t5.geo, for an example of the use of Printf.

Printf ( CHAR-EXPRESSION , EXPRESSION-LIST ) > CHAR-EXPRESSION;
     Same as Printf above, but output the expression in a file.

Printf ( CHAR-EXPRESSION , EXPRESSION-LIST ) >> CHAR-EXPRESSION;
     Same as Printf above, but appends the expression at the end of the file.

Error ( CHAR-EXPRESSION <, EXPRESSION-LIST> );
     Same as Printf, but raises an error.

Merge CHAR-EXPRESSION;
     Merges a file named CHAR-EXPRESSION. This command is equivalent to the `File->Merge' menu in the GUI. If the path in CHAR-EXPRESSION is not absolute, CHAR-EXPRESSION is appended to the path of the current file.

Draw;
     Redraws the scene.

BoundingBox;
     Recomputes the bounding box of the scene (which is normally computed only after new geometrical entities are added or after files are included or merged). The bounding box is computed as follows:

      1. If there is a mesh (i.e., at least one mesh vertex), the bounding box is taken as the box enclosing all the mesh vertices;

      2. If there is no mesh but there is a geometry (i.e., at least one geometrical point), the bounding box is taken as the box enclosing all the geometrical points;

      3. If there is no mesh and no geometry, but there are some post-processing views, the bounding box is taken as the box enclosing all the primitives in the views.

BoundingBox { EXPRESSION, EXPRESSION, EXPRESSION, EXPRESSION, EXPRESSION, EXPRESSION };
     Forces the bounding box of the scene to the given EXPRESSIONs (X min, X max, Y min, Y max, Z min, Z max).

Delete Model;
     Deletes the current model (all geometrical entities and their associated meshes).

Delete Physicals;
     Deletes all physical groups.

Delete Variables;
     Deletes all the expressions.

Delete Options;
     Deletes the current options and revert to the default values.

Delete STRING;
     Deletes the expression STRING.

Mesh EXPRESSION;
     Generates EXPRESSION-D mesh.

RefineMesh;
     Refines the current mesh by splitting all elements. If Mesh.SecondOrderLinear is set, the new vertices are inserted by linear interpolatinon. Otherwise they are snapped on the actual geometry.

SetOrder EXPRESSION;
     Changes the order of the elements in the current mesh.

Print CHAR-EXPRESSION;
     Prints the graphic window in a file named CHAR-EXPRESSION, using the current Print.Format (see General options list). If the path in CHAR-EXPRESSION is not absolute, CHAR-EXPRESSION is appended to the path of the current file.

Sleep EXPRESSION;
     Suspends the execution of Gmsh during EXPRESSION seconds.

SystemCall CHAR-EXPRESSION;
     Executes a (blocking) system call.

NonBlockingSystemCall CHAR-EXPRESSION;
     Executes a (non-blocking) system call.

SetName CHAR-EXPRESSION;
     Changes the name of the current model.

SyncModel;
     Forces an immediate transfer from the old geometrical database into the new one (this transfer normally occurs right after a file is read).

Include CHAR-EXPRESSION;
     Includes the file named CHAR-EXPRESSION at the current position in the input file. The include command should be given on a line of its own.  If the path in CHAR-EXPRESSION is not absolute, CHAR-EXPRESSION is appended to the path of the current file.

General options
===============

The list of all the general CHAR-OPTIONs, REAL-OPTIONs and COLOR-OPTIONs (in that order---check the default values to see the actual types) is given in General options list. Most of these options are accessible in the GUI, but not all of them. When running Gmsh interactively, changing an option in the script file will modify the option in the GUI in real time. This permits for example to resize the graphical window in a script, or to interact with animations in the script and in the GUI at the same time.

Geometry module
***************

Gmsh's geometry module provides a simple CAD engine, using a boundary representation (``BRep'') approach: you need to first define points (using the Point command: see below), then lines (using Line, Circle, Spline, ..., commands or by extruding points), then surfaces (using for example the Plane Surface or Ruled Surface commands, or by extruding lines), and finally volumes (using the Volume command or by extruding surfaces).

These geometrical entities are called ``elementary'' in Gmsh's jargon, and are assigned identification numbers when they are created:

 1. each elementary point must possess a unique identification number;

 2. each elementary line must possess a unique identification number;

 3. each elementary surface must possess a unique identification number;

 4. each elementary volume must possess a unique identification number.

Elementary geometrical entities can then be manipulated in various ways, for example using the Translate, Rotate, Scale or Symmetry commands. They can be deleted with the Delete command, provided that no higher-dimension entity references them.

Groups of elementary geometrical entities can also be defined and are called ``physical'' entities. These physical entities cannot be modified by geometry commands: their only purpose is to assemble elementary entities into larger groups, possibly modifying their orientation, so that they can be referred to by the mesh module as single entities. As is the case with elementary entities, each physical point, physical line, physical surface or physical volume must be assigned a unique identification number. See Mesh module, for more information about how physical entities affect the way meshes are saved.

Geometry commands
=================

The next subsections describe all the available geometry commands. These commands can be used anywhere in a Gmsh script file. Note that the following general syntax rule is followed for the definition of geometrical entities: ``If an EXPRESSION defines a new entity, it is enclosed between parentheses. If an EXPRESSION refers to a previously defined entity, it is enclosed between braces.''

Points
------

Point ( EXPRESSION ) = { EXPRESSION, EXPRESSION, EXPRESSION <, EXPRESSION > };
     Creates an elementary point. The EXPRESSION inside the parentheses is the point's identification number; the three first EXPRESSIONs inside the braces on the right hand side give the three X, Y and Z coordinates of the point in the three-dimensional Euclidean space; the optional last EXPRESSION sets the prescribed mesh element size at that point. See Specifying mesh element sizes, for more information about how this value is used in the meshing process.

Physical Point ( EXPRESSION | CHAR-EXPRESSION ) = { EXPRESSION-LIST };
     Creates a physical point. The EXPRESSION inside the parentheses is the physical point's identification number (if a CHAR-EXPRESSION is given instead, a unique identification number is automatically created); the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the elementary points that need to be grouped inside the physical point.

Lines
-----

BSpline ( EXPRESSION ) = { EXPRESSION-LIST };
     Creates a B-spline curve. The EXPRESSION inside the parentheses is the B-spline curve's identification number; the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the B-spline's control points. Repeating control points has the expected effect.

Circle ( EXPRESSION ) = { EXPRESSION, EXPRESSION, EXPRESSION };
     Creates a circle arc (strictly) smaller than Pi. The EXPRESSION inside the parentheses is the circle arc's identification number; the first EXPRESSION inside the braces on the right hand side gives the identification number of the start point of the arc; the second EXPRESSION gives the identification number of the center of the circle; the last EXPRESSION gives the identification number of the end point of the arc.

CatmullRom ( EXPRESSION ) = { EXPRESSION-LIST };
     CatmullRom is a synonym for Spline.

Ellipse ( EXPRESSION ) = { EXPRESSION, EXPRESSION, EXPRESSION, EXPRESSION };
     Creates an ellipse arc. The EXPRESSION inside the parentheses is the ellipse arc's identification number; the first EXPRESSION inside the braces on the right hand side gives the identification number of the start point of the arc; the second EXPRESSION gives the identification number of the center of the ellipse; the third EXPRESSION gives the identification number of any point located on the major axis of the ellipse; the last EXPRESSION gives the identification number of the end point of the arc.

Line ( EXPRESSION ) = { EXPRESSION, EXPRESSION };
     Creates a straight line segment. The EXPRESSION inside the parentheses is the line segment's identification number; the two EXPRESSIONs inside the braces on the right hand side give identification numbers of the start and end points of the segment.

Spline ( EXPRESSION ) = { EXPRESSION-LIST };
     Creates a spline curve. The EXPRESSION inside the parentheses is the spline's identification number; the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the spline's control points.

Line Loop ( EXPRESSION ) = { EXPRESSION-LIST };
     Creates an oriented line loop. The EXPRESSION inside the parentheses is the line loop's identification number; the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the elementary lines that constitute the line loop. A line loop must be a closed loop, and the elementary lines should be ordered and oriented (using negative identification numbers to specify reverse orientation). If the orientation is correct, but the ordering is wrong, Gmsh will actually reorder the list internally to create a consistent loop. Although Gmsh supports it, it is not recommended to specify multiple line loops (or subloops) in a single Line Loop command. (Line loops are used to create surfaces: see Surfaces.)

Compound Line ( EXPRESSION ) = { EXPRESSION-LIST };
     Creates a compound line from several elementary lines.  When meshed, a compound line will be reparametrized as a single line, whose mesh can thus cross internal boundaries. The EXPRESSION inside the parentheses is the compound line's identification number; the EXPRESSION-LIST on the right hand side contains the identification number of the elementary lines that should be reparametrized as a single line. See Compound Surface for additional information on compound entities.

Physical Line ( EXPRESSION | CHAR-EXPRESSION ) = { EXPRESSION-LIST };
     Creates a physical line. The EXPRESSION inside the parentheses is the physical line's identification number (if a CHAR-EXPRESSION is given instead, a unique identification number is automatically created); the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the elementary lines that need to be grouped inside the physical line. Specifying negative identification numbers in the EXPRESSION-LIST will reverse the orientation of the mesh elements belonging to the corresponding elementary lines in the saved mesh.

Surfaces
--------

Plane Surface ( EXPRESSION ) = { EXPRESSION-LIST };
     Creates a plane surface. The EXPRESSION inside the parentheses is the plane surface's identification number; the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the line loops defining the surface. The first line loop defines the exterior boundary of the surface; all other line loops define holes in the surface. A line loop defining a hole should not have any lines in common with the exterior line loop (in which case it is not a hole, and the two surfaces should be defined separately). Likewise, a line loop defining a hole should not have any lines in common with another line loop defining a hole in the same surface (in which case the two line loops should be combined).

Ruled Surface ( EXPRESSION ) = { EXPRESSION-LIST } < In Sphere { EXPRESSION } >;
     Creates a ruled surface, i.e., a surface that can be interpolated using transfinite interpolation. The EXPRESSION inside the parentheses is the ruled surface's identification number; the first EXPRESSION-LIST on the right hand side should contain the identification number of a line loop composed of either three or four elementary lines. The optional In Sphere argument forces the surface to be a spherical patch (the extra parameter gives the identification number of the center of the sphere).

Surface Loop ( EXPRESSION ) = { EXPRESSION-LIST };
     Creates a surface loop (a shell). The EXPRESSION inside the parentheses is the surface loop's identification number; the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the elementary surfaces that constitute the surface loop. A surface loop must always represent a closed shell, and the elementary surfaces should be oriented consistently (using negative identification numbers to specify reverse orientation). (Surface loops are used to create volumes: see Volumes.)

Compound Surface ( EXPRESSION ) = { EXPRESSION-LIST } < Boundary { { EXPRESSION-LIST }, { EXPRESSION-LIST }, { EXPRESSION-LIST }, { EXPRESSION-LIST } } > ;
     Creates a compound surface from several elementary surfaces.  When meshed, a compound surface will be reparametrized as a single surface, whose mesh can thus cross internal boundaries. Compound surfaces are mostly useful for remeshing discrete models; see ``J.-F. Remacle, C. Geuzaine, G. Compere and E. Marchandise, High Quality Surface Remeshing Using Harmonic Maps, International Journal for Numerical Methods in Engineering, 2009'' for details as well as the wiki for more examples.  The EXPRESSION inside the parentheses is the compound surface's identification number; the mandatory EXPRESSION-LIST on the right hand side contains the identification number of the elementary surfaces that should be reparametrized as a single surface.

Physical Surface ( EXPRESSION | CHAR-EXPRESSION ) = { EXPRESSION-LIST };
     Creates a physical surface. The EXPRESSION inside the parentheses is the physical surface's identification number (if a CHAR-EXPRESSION is given instead, a unique identification number is automatically created); the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the elementary surfaces that need to be grouped inside the physical surface. Specifying negative identification numbers in the EXPRESSION-LIST will reverse the orientation of the mesh elements belonging to the corresponding elementary surfaces in the saved mesh.

Volumes
-------

Volume ( EXPRESSION ) = { EXPRESSION-LIST };
     Creates a volume. The EXPRESSION inside the parentheses is the volume's identification number; the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the surface loops defining the volume. The first surface loop defines the exterior boundary of the volume; all other surface loops define holes in the volume.  A surface loop defining a hole should not have any surfaces in common with the exterior surface loop (in which case it is not a hole, and the two volumes should be defined separately). Likewise, a surface loop defining a hole should not have any surfaces in common with another surface loop defining a hole in the same volume (in which case the two surface loops should be combined).

Compound Volume ( EXPRESSION ) = { EXPRESSION-LIST };
     Creates a compound volume from several elementary volumes.  When meshed, a compound volume will be reparametrized as a single volume, whose mesh can thus cross internal boundaries. The EXPRESSION inside the parentheses is the compound volume's identification number; the EXPRESSION-LIST on the right hand side contains the identification number of the elementary volumes that should be reparametrized as a single volume. See Compound Surface for additional information on compound entities.

Physical Volume ( EXPRESSION | CHAR-EXPRESSION ) = { EXPRESSION-LIST };
     Creates a physical volume. The EXPRESSION inside the parentheses is the physical volume's identification number (if a CHAR-EXPRESSION is given instead, a unique identification number is automatically created); the EXPRESSION-LIST on the right hand side should contain the identification numbers of all the elementary volumes that need to be grouped inside the physical volume.

Extrusions
----------

Lines, surfaces and volumes can also be created through extrusion of points, lines and surfaces, respectively. Here is the syntax of the geometrical extrusion commands (go to Structured grids, to see how these commands can be extended in order to also extrude the mesh):

EXTRUDE:

Extrude { EXPRESSION-LIST }  { EXTRUDE-LIST }
     Extrudes all elementary entities (points, lines or surfaces) in EXTRUDE-LIST using a translation. The EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z components of the translation vector.

Extrude { { EXPRESSION-LIST }, { EXPRESSION-LIST }, EXPRESSION } { EXTRUDE-LIST }
     Extrudes all elementary entities (points, lines or surfaces) in EXTRUDE-LIST using a rotation. The first EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z direction of the rotation axis; the second EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z components of any point on this axis; the last EXPRESSION should contain the rotation angle (in radians).

Extrude { { EXPRESSION-LIST }, { EXPRESSION-LIST }, { EXPRESSION-LIST }, EXPRESSION } { EXTRUDE-LIST }
     Extrudes all elementary entities (points, lines or surfaces) in EXTRUDE-LIST using a translation combined with a rotation. The first EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z components of the translation vector; the second EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z direction of the rotation axis; the third EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z components of any point on this axis; the last EXPRESSION should contain the rotation angle (in radians).

with

     EXTRUDE-LIST:
       Point | Line | Surface { EXPRESSION-LIST }; ...

As explained in Floating point expressions, EXTRUDE can be used in an expression, in which case it returns a list of identification numbers. By default, the list contains the ``top'' of the extruded entity at index 0 and the extruded entity at index 1, followed by the ``sides'' of the extruded entity at indices 2, 3, etc.  For example:

       Point(1) = {0,0,0};
       Point(2) = {1,0,0};
       Line(1) = {1, 2};
       out[] = Extrude{0,1,0}{ Line{1}; };
       Printf("top line = %g", out[0]);
       Printf("surface = %g", out[1]);
       Printf("side lines = %g and %g", out[2], out[3]);

This behaviour can be changed with the Geometry.ExtrudeReturnLateralEntities option (see Geometry options list).

Transformations
---------------

Geometrical transformations can be applied to elementary entities, or to copies of elementary entities (using the Duplicata command: see below). The syntax of the transformation commands is:

TRANSFORM:

Dilate { { EXPRESSION-LIST }, EXPRESSION } { TRANSFORM-LIST }
     Scales all elementary entities in TRANSFORM-LIST by a factor EXPRESSION. The EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z direction of the homothetic transformation.

Rotate { { EXPRESSION-LIST }, { EXPRESSION-LIST }, EXPRESSION }  { TRANSFORM-LIST }
     Rotates all elementary entities in TRANSFORM-LIST by an angle of EXPRESSION radians. The first EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z direction of the rotation axis; the second EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z components of any point on this axis.

Symmetry { EXPRESSION-LIST } { TRANSFORM-LIST }
     Transforms all elementary entities symmetrically to a plane. The EXPRESSION-LIST should contain four EXPRESSIONs giving the coefficients of the plane's equation.

Translate { EXPRESSION-LIST } { TRANSFORM-LIST }
     Translates all elementary entities in TRANSFORM-LIST. The EXPRESSION-LIST should contain three EXPRESSIONs giving the X, Y and Z components of the translation vector.

Boundary { TRANSFORM-LIST }
     (Not a transformation per-se.) Returns the boundary of the elementary entities in TRANSFORM-LIST.

CombinedBoundary { TRANSFORM-LIST }
     (Not a transformation per-se.) Returns the boundary of the elementary entities, combined as if a single entity, in TRANSFORM-LIST. Useful to compute the boundary of a complex part.

with

     TRANSFORM-LIST:
       Point | Line | Surface | Volume { EXPRESSION-LIST }; ... |
       Duplicata { Point | Line | Surface | Volume { EXPRESSION-LIST }; ... } |
       TRANSFORM

Miscellaneous
-------------

Here is a list of all other geometry commands currently available:

Coherence;
     Removes all duplicate elementary geometrical entities (e.g., points having identical coordinates). Note that Gmsh executes the Coherence command automatically after each geometrical transformation, unless Geometry.AutoCoherence is set to zero (see Geometry options list).

Delete { Point | Line | Surface | Volume { EXPRESSION-LIST }; ... }
     Deletes all elementary entities whose identification numbers are given in EXPRESSION-LIST. If an entity is linked to another entity (for example, if a point is used as a control point of a curve), Delete has no effect (the line will have to be deleted before the point can).

Hide { Point | Line | Surface | Volume { EXPRESSION-LIST }; ... }
     Hide the entities listed in EXPRESSION-LIST, if General.VisibilityMode is set to 0 or 1.

Hide CHAR-EXPRESSION;
     Hide the entity CHAR-EXPRESSION, if General.VisibilityMode is set to 0 or 1 (CHAR-EXPRESSION can for example be "*").

Show { Point | Line | Surface | Volume { EXPRESSION-LIST }; ... }
     Show the entities listed in EXPRESSION-LIST, if General.VisibilityMode is set to 0 or 1.

Show CHAR-EXPRESSION;
     Show the entity CHAR-EXPRESSION, if General.VisibilityMode is set to 0 or 1 (CHAR-EXPRESSION can for example be "*").

Geometry options
================

The list of all the options that control the behavior of geometry commands, as well as the way geometrical entities are handled in the GUI, is give in  Geometry options list.

Mesh module
***********

Gmsh's mesh module regroups several 1D, 2D and 3D meshing algorithms, all producing grids conforming in the sense of finite elements (see Mesh):

  * The 2D unstructured algorithms generate triangles or both triangles and quadrangles (when Recombine Surface is used: see Miscellaneous mesh commands). The 3D unstructured algorithms generate tetrahedra.

  * The 2D structured algorithms (transfinite and extrusion) generate triangles by default, but quadrangles can be obtained by using the Recombine commands (see Structured grids, and Miscellaneous mesh commands). The 3D structured algorithms generate tetrahedra, hexahedra, prisms and pyramids, depending on the type of the surface meshes they are based on.

All meshes can be subdivided to generate fully quadrangular or fully hexahedral meshes with the Mesh.SubdivisionAlgorihm option (see Mesh options list). However, beware that the quality of subdivided elements initially generated with an unstructured algorithm can be quite poor.

Choosing the right unstructured algorithm
=========================================

Gmsh currently provides a choice between three 2D unstructured algorithms and between two 3D unstructured algorithms. Each algorithm has its own advantages and disadvantages.

For all 2D unstructured algorithms a Delaunay mesh that contains all the points of the 1D mesh is initially constructed using a divide-and-conquer algorithm (R. A. Dwyer, A simple divide-and-conquer algorithm for computing Delaunay triangulations in O(n log n) expected time, In Proceedings of the second annual symposium on computational geometry, Yorktown Heights, 2--4 June 1986.). Missing edges are recovered using edge swaps (N. P. Weatherill, The integrity of geometrical boundaries in the two-dimensional Delaunay triangulation, Commun. Appl. Numer. Methods 6(2), pp. 101--109, 1990.). After this initial step three different algorithms can be applied to generate the final mesh:

 1. The ``MeshAdapt'' algorithm (C. Geuzaine and J.-F. Remacle, Gmsh: a three-dimensional finite element mesh generator with built-in pre- and post-processing facilities, International Journal for Numerical Methods in Engineering 79(11), pp. 1309--1331, 2009.) is based on local mesh modifications. This technique makes use of edge swaps, splits, and collapses: long edges are split, short edges are collapsed, and edges are swapped if a better geometrical configuration is obtained.

 2. The ``Delaunay'' algorithm is inspired by the work of the GAMMA team at INRIA (P.-L. George and P. Frey, Mesh generation, Hermes, Lyon, 2000.). New points are inserted sequentially at the circumcenter of the element that has the largest adimensional circumradius. The mesh is then reconnected using an anisotropic Delaunay criterion.

 3. The ``Frontal'' algorithm is inspired by the work of S. Rebay (S. Rebay, Efficient unstructured mesh generation by means of Delaunay triangulation and Bowyer-Watson algorithm, J. Comput.  Phys. 106, pp. 25--138, 1993.).

These algorithms can be ranked as follows:

                   Robustness        Performance      Element quality
     MeshAdapt         1                  3                 2
     Delaunay          2                  1                 2
     Frontal           3                  2                 1

For very complex curved surfaces the ``MeshAdapt'' algorithm is the best choice. When high element quality is important, the ``Frontal'' algorithm should be tried. For very large meshes of plane surfaces the ``Delaunay'' algorithm is the fastest.

The ``Automatic'' algorithm tries to select the best algorithm automatically for each surface in the model. As of Gmsh 2.7, the ``Automatic'' algorithm selects ``Delaunay'' for plane surfaces and ``MeshAdapt'' for all other surfaces.

In 3D two unstructured algorithms are available:

 1. The ``Delaunay'' algorithm is split into two separate steps. First, an initial mesh of the union of all the volumes in the model is performed using H. Si's Tetgen algorithm (H. Si, Tetgen: a quality tetrahedral mesh generator and three-dimensional Delaunay triangulator, 2004.). Then a three-dimensional version of the 2D Delaunay algorithm described above is applied.

 2. The ``Frontal'' algorithm uses J. Schoeberl's Netgen algorithm (J. Schoeberl, Netgen, an advancing front 2d/3d-mesh generator based on abstract rules, Comput. Visual. Sci., 1, pp. 41--52, 1997.).

The ``Delaunay'' algorithm is the most robust and the fastest, and is the only one that supports the Field mechanism to specify element sizes (see Specifying mesh element sizes). However, this algorithm will sometimes modify the surface mesh, and is thus not suitable for producing hybrid structured/unstructured grids. In that case the ``Frontal'' algorithm should be preferred. The quality of the elements produced by both algorithms is comparable. If element quality is important the mesh optimizer(s) should be applied.

Elementary vs. physical entities
================================

If only elementary geometrical entities are defined (or if the Mesh.SaveAll option is set; see Mesh options list), the grid produced by the mesh module will be saved ``as is''. That is, all the elements in the grid will be saved using the identification number of the elementary entities they discretize as their elementary region number (and 0 as their physical region number (This behaviour was introduced in Gmsh 2.0. In older versions, both the elementary and the physical region numbers would be set to the identification number of the elementary region.); File formats). This can sometimes be inconvenient:

  * mesh elements cannot be duplicated;

  * the orientation of the mesh elements (the ordering of their nodes) is determined entirely by the orientation of their ``parent'' elementary entities, and cannot be modified;

  * elements belonging to different elementary entities cannot be linked as being part of a larger group having a physical or mathematical meaning (like `Left wing', `Metallic part', `Dirichlet boundary condition', ...).

To remedy these problems, the geometry module (see Geometry module) introduces the notion of ``physical'' entities (also called ``physical groups''). The purpose of physical entities is to assemble elementary entities into larger, possibly overlapping groups, and to control the orientation of the elements in these groups. The introduction of physical entities in large models usually greatly facilitates the manipulation of the model (e.g., using `Tools->Visibility' in the GUI) and the interfacing with external solvers.

In the MSH file format (see File formats), if physical entities are defined, the output mesh only contains those elements that belong to physical entities. Other file formats each treat physical entities in slightly different ways, depending on their capability to define groups.

In all cases, Gmsh reindexes the mesh vertices and elements so that they are numbered in a continuous sequence in the output files. Note that 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 file back using `File->Open'.

Mesh commands
=============

The mesh module commands mostly permit to modify the mesh element sizes and specify structured grid parameters. The actual mesh ``actions'' (i.e., ``mesh the lines'', ``mesh the surfaces'' and ``mesh the volumes'') cannot be specified in the script files. They have to be given either in the GUI or on the command line (see Running Gmsh on your system, and Command-line options).

Specifying mesh element sizes
-----------------------------

There are three ways to specify the size of the mesh elements for a given geometry:

 1. First, if Mesh.CharacteristicLengthFromPoints is set (it is by default), you can simply specify desired mesh element sizes at the geometrical points of the model (with the Point command: see Points). The size of the mesh elements will then be computed by linearly interpolating these values on the initial mesh (see Mesh). This might sometimes lead to over-refinement in some areas, so that you may have to add ``dummy'' geometrical entities in the model in order to get the desired element sizes.

     This method works with all the algorithms implemented in the mesh module. The final element sizes are of course constrained by the structured algorithms for which the element sizes are explicitly specified (e.g., transfinite and extruded grids: see Structured grids).

 2. Second, if Mesh.CharacteristicLengthFromCurvature is set (it is not by default), the mesh will be adapted with respect to the curvature of the geometrical entities.

 3. Finally, you can specify general mesh size ``fields''. Various fields exist:

       * A PostView field specifies an explicit background mesh in the form of a scalar post-processing view (see Post-processing commands, and File formats) in which the nodal values are the target element sizes.  This method is very general but it requires a first (usually rough) mesh and a way to compute the target sizes on this mesh (usually through an error estimation procedure, in an iterative process of mesh adaptation). Warning: only parsed (.pos) files can currently be used as background meshes (.msh files cannot be used, since the mesh used to define the field will be destroyed during the meshing process).

          (Note that you can also load a background mesh directly from the command line using the -bgm option (see Command-line options), or in the GUI by selecting `Apply as background mesh' in the post-processing view option menu.)

       * A Box field specifies the size of the elements inside and outside of a parallelepipedic region.

       * A Threshold field specifies the size of the mesh according to the distance to some geometrical entities. These entities can for example be geometry points and lines specified by an Attractor field.

       * A MathEval field specifies the size of the mesh using an explicit mathematical function.

       * A Min field specifies the size as the minimum of the sizes computed using other fields

       * ...

     Fields are supported by all the algorithms except those based on Netgen. The list of available fields with their options is given below.

The three aforementioned methods can be used simultaneously, in which case the smallest element size is selected at any given point.

All element sizes are further constrained by the Mesh.CharacteristicLengthMin, Mesh.CharacteristicLengthMax and Mesh.CharacteristicLengthFactor options (see Mesh options list)

Here are the mesh commands that are related to the specification of mesh element sizes:

Characteristic Length { EXPRESSION-LIST } = EXPRESSION;
     Modify the prescribed mesh element size of the points whose identification numbers are listed in EXPRESSION-LIST. The new value is given by EXPRESSION.

Field[EXPRESSION] = STRING;
     Create a new field (with id number EXPRESSION), of type STRING.

Field[EXPRESSION].STRING = CHAR-EXPRESSION | EXPRESSION | EXPRESSION-LIST;
     Set the option STRING of the EXPRESSION-th field.

Background Field = EXPRESSION;
     Select the EXPRESSION-th field as the one used to compute element sizes. Only one background field can be given; if you want to combine several field, use the Min or Max field (see below).

Here is the list of all available fields with their associated options:

     [file opt_fields.texi not included]

Structured grids
----------------

Extrude { EXPRESSION-LIST } { EXTRUDE-LIST LAYERS }
     Extrudes both the geometry and the mesh using a translation (see Extrusions). The LAYERS option determines how the mesh is extruded and has the following syntax:

          LAYERS:

            Layers { EXPRESSION } |
            Layers { { EXPRESSION-LIST }, { EXPRESSION-LIST } } |
            Recombine; ...

     In the first Layers form, EXPRESSION gives the number of elements to be created in the (single) layer. In the second form, the first EXPRESSION-LIST defines how many elements should be created in each extruded layer, and the second EXPRESSION-LIST gives the normalized height of each layer (the list should contain a sequence of N numbers 0 < H1 < H2 < ... < HN <= 1). See t3.geo, for an example.

     For line extrusions, the Recombine option will recombine triangles into quadrangles when possible.  For surface extrusions, the Recombine option will recombine tetrahedra into prisms, hexahedra or pyramids.

     Please note that, starting with Gmsh 2.0, region numbers cannot be specified explicitly anymore in Layers commands. Instead, as with all other geometry commands, you must use the automatically created entity identifier created by the extrusion command. For example, the following extrusion command will return the id of the new ``top'' surface in num[0] and the id of the new volume in num[1]:

          num[] = Extrude {0,0,1} { Surface{1}; Layers{10}; };

Extrude { { EXPRESSION-LIST }, { EXPRESSION-LIST }, EXPRESSION } { EXTRUDE-LIST LAYERS }
     Extrudes both the geometry and the mesh using a rotation (see Extrusions). The LAYERS option is defined as above.

Extrude { { EXPRESSION-LIST }, { EXPRESSION-LIST }, { EXPRESSION-LIST }, EXPRESSION } { EXTRUDE-LIST LAYERS }
     Extrudes both the geometry and the mesh using a combined translation and rotation (see Extrusions). The LAYERS option is defined as above.

Extrude { Surface { EXPRESSION-LIST }; LAYERS < Using Index[EXPR]; > < Using View[EXPR]; > }
     Extrudes a boundary layer from the specified surfaces. If no view is specified, the boundary layer is created using gouraud-shaped (smoothed) normal field. Specifying a boundary layer index allows to extrude several independent boundary layers (with independent normal smoothing).

Transfinite Line { EXPRESSION-LIST } | "*" = EXPRESSION < Using Progression | Bump EXPRESSION >;
     Selects the lines in EXPRESSION-LIST to be meshed with the 1D transfinite algorithm. The EXPRESSION on the right hand side gives the number of nodes that will be created on the line (this overrides any other mesh element size prescription---see Specifying mesh element sizes). The optional argument `Using Progression EXPRESSION' instructs the transfinite algorithm to distribute the nodes following a geometric progression (Progression 2 meaning for example that each line element in the series will be twice as long as the preceding one). The optional argument `Using Bump EXPRESSION' instructs the transfinite algorithm to distribute the nodes with a refinement at both ends of the line.

Transfinite Surface { EXPRESSION-LIST } | "*" < = { EXPRESSION-LIST } > < Left | Right | Alternate > ;
     Selects surfaces to be meshed with the 2D transfinite algorithm. The EXPRESSION-LIST on the right-hand-side should contain the identification numbers of three or four points on the boundary of the surface that define the corners of the transfinite interpolation. If no identification numbers are given, the transfinite algorithm will try to find the corners automatically. The optional argument specifies the way the triangles are oriented when the mesh is not recombined.

Transfinite Volume { EXPRESSION-LIST } | "*" < = { EXPRESSION-LIST } > ;
     Selects five- or six-face volumes to be meshed with the 3D transfinite algorithm.  The EXPRESSION-LIST on the right-hand-side should contain the identification numbers of the six or eight points on the boundary of the volume that define the corners of the transfinite interpolation. If no identification numbers are given, the transfinite algorithm will try to find the corners automatically.

Miscellaneous
-------------

Here is a list of all other mesh commands currently available:

Point | Line { EXPRESSION-LIST } In Surface { EXPRESSION };
     Embed the point(s) or line(s) in the given surface. The surface mesh will conform to the mesh of the point(s) or lines(s). Note that embedded lines only work with the MeshAdapt 2-D algorithm.

Periodic Line { EXPRESSION-LIST } = { EXPRESSION-LIST };
     Force mesh of lines on the left-hand side (slaves) to match the mesh of the lines on the right-hand side (masters).

Periodic Surface EXPRESSION { EXPRESSION-LIST } = EXPRESSION { EXPRESSION-LIST };
     Force mesh of the surface on the left-hand side (slave, with boundary edges specified between braces) to match the mesh of the surface on the right-hand side (master, with boundary edges specified between braces).

Coherence Mesh;
     Removes all duplicate mesh vertices.

Color COLOR-EXPRESSION { Point | Line | Surface | Volume { EXPRESSION-LIST }; ... }
     Sets the mesh color of the entities in EXPRESSION-LIST to COLOR-EXPRESSION.

Hide { Point | Line | Surface | Volume { EXPRESSION-LIST }; ... }
     Hides the mesh of the entities in EXPRESSION-LIST, if General.VisibilityMode is set to 0 or 2.

Hide CHAR-EXPRESSION;
     Hides the mesh of the entity CHAR-EXPRESSION, if General.VisibilityMode is set to 0 or 2 (CHAR-EXPRESSION can for example be "*").

Recombine Surface { EXPRESSION-LIST } | "*" < = EXPRESSION >;
     Recombines the triangular meshes of the surfaces listed in EXPRESSION-LIST into mixed triangular/quadrangular meshes. The optional EXPRESSION on the right hand side specifies the maximum difference (in degrees) allowed between the largest angle of a quadrangle and a right angle (a value of 0 would only accept quadrangles with right angles; a value of 90 would allow degenerate quadrangles; default value is 45).

Save CHAR-EXPRESSION;
     Saves the mesh in a file named CHAR-EXPRESSION, using the current Mesh.Format (see Mesh options list). If the path in CHAR-EXPRESSION is not absolute, CHAR-EXPRESSION is appended to the path of the current file.

Show { Point | Line | Surface | Volume { EXPRESSION-LIST }; ... }
     Shows the mesh of the entities in EXPRESSION-LIST, if General.VisibilityMode is set to 0 or 2.

Show CHAR-EXPRESSION;
     Shows the mesh of the entity CHAR-EXPRESSION, if General.VisibilityMode is set to 0 or 2 (CHAR-EXPRESSION can for example be "*").

Smoother Surface { EXPRESSION-LIST } = EXPRESSION;
     Sets number of elliptic smoothing steps for the surfaces listed in EXPRESSION-LIST (smoothing only applies to transfinite meshes at the moment).

Homology ( { EXPRESSION-LIST } ) { { EXPRESSION-LIST } , { EXPRESSION-LIST } };
     Compute a basis representation for homology spaces after a mesh has been generated. The first EXPRESSION-LIST is a list of dimensions whose homology bases are computed; if empty, all bases are computed. The second EXPRESSION-LIST is a list physical groups that constitute the computation domain; if empty, the whole mesh is the domain. The third EXPRESSION-LIST is a list of physical groups that constitute the relative subdomain of relative homology computation; if empty, absolute homology is computed. Resulting basis representation chains are stored as physical groups in the mesh.

Cohomology ( { EXPRESSION-LIST } ) { { EXPRESSION-LIST } , { EXPRESSION-LIST } };
     Similar to command Homology, but computes a basis representation for cohomology spaces instead.

Mesh options
============

The list of all the options that control the behavior of mesh commands, as well as the way meshes are displayed in the GUI, is given in Mesh options list.

Solver module
*************

External solvers can be driven by Gmsh through the ONELAB http://www.onelab.info interface. To add a new solver in the solver module, you need to specify its name (Solver.Name0, Solver.Name1, etc.) and the path to the executable (Solver.Executable0, Solver.Executable1, etc.); see Solver options list).

The client-server API for the solver interface is defined in the onelab.h header. See utils/solvers/c++/solver.cpp for a simple example on how to use the ONELAB programming interface. See the sources of GetDP (http://geuz.org/getdp for a more comprehensive example.

Solver options
==============

The list of all the solver options is given in Solver options list.

Post-processing module
**********************

Gmsh's post-processing module can handle multiple scalar, vector or tensor datasets along with the geometry and the mesh. The datasets can be given in several formats: in human-readable ``parsed'' format (these are just part of a standard input script, but are usually put in separate files with a .pos extension), in native MSH files (ASCII or binary files with .msh extensions: see File formats), or in standard third-party formats (like MED: http://www.code-aster.org/outils/med/).

Once loaded into Gmsh, scalar fields can be displayed as iso-value lines and surfaces or color maps, whereas vector fields can be represented either by three-dimensional arrows or by displacement maps. (Tensor fields are currently displayed as Von-Mises effective stresses, min/max eigenvalues, eigenvectors, ellipsis or ellipsoid. To display other (combinations of) components, you can use the Force scalar or Force vector options, or use Plugin(MathEval): see Post-processing plugins.)

In Gmsh's jargon, each dataset is called a ``view''. Each view is given a name, and can be manipulated either individually (each view has its own button in the GUI and can be referred to by its index in a script) or globally (see the PostProcessing.Link option in Post-processing options list).

By default, Gmsh treats all post-processing views as three-dimensional plots, i.e., draws the scalar, vector and tensor primitives (points, lines, triangles, tetrahedra, etc.) in 3D space. But Gmsh can also represent each post-processing view containing scalar points as two-dimensional (``X-Y'') plots, either space- or time-oriented:

  * in a `2D space' plot, the scalar points are taken in the same order as they are defined in the post-processing view: the abscissa of the 2D graph is the curvilinear abscissa of the curve defined by the point series, and only one curve is drawn using the values associated with the points. If several time steps are available, each time step generates a new curve;

  * in a `2D time' plot, one curve is drawn for each scalar point in the view and the abscissa is the time step.

Although visualization is usually mostly an interactive task, Gmsh exposes all the post-processing commands and options to the user in its scripting language to permit a complete automation of the post-processing process (see e.g., t8.geo, and t9.geo).

The two following sections summarize all available post-processing commands and options. Most options apply to both 2D and 3D plots (colormaps, point/line sizes, interval types, time step selection, etc.), but some are peculiar to 3D (lightning, element selection, etc.) or 2D plots (abscissa labels, etc.). Note that 2D plots can be positioned explicitly inside the graphical window, or be automatically positioned in order to avoid overlaps.

Sample post-processing files in human-readable ``parsed'' format and in the native MSH file format are available in the tutorial directory of Gmsh's distribution (.pos and .msh files). The ``parsed'' format is defined in the next section (cf. the View command); the MSH format is defined in File formats.

Post-processing commands
========================

Alias View[EXPRESSION];
     Creates an alias of the EXPRESSION-th post-processing view.

     Note that Alias creates a logical duplicate of the view without actually duplicating the data in memory. This is very useful when you want multiple simultaneous renderings of the same large dataset (usually with different display options), but you cannot afford to store all copies in memory. If what you really want is multiple physical copies of the data, just merge the file containing the post-processing view multiple times.

AliasWithOptions View[EXPRESSION];
     Creates an alias of the EXPRESSION-th post-processing view and copies all the options of the EXPRESSION-th view to the new aliased view.

Combine ElementsByViewName;
     Combines all the post-processing views having the same name into new views. The combination is done ``spatially'', i.e., simply by appending the elements at the end of the new views.

Combine ElementsFromAllViews | Combine Views;
     Combines all the post-processing views into a single new view.  The combination is done ``spatially'', i.e., simply by appending the elements at the end of the new view.

Combine ElementsFromVisibleViews;
     Combines all the visible post-processing views into a single new view. The combination is done ``spatially'', i.e., simply by appending the elements at the end of the new view.

Combine TimeStepsByViewName | Combine TimeSteps;
     Combines the data from all the post-processing views having the same name into new multi-time-step views. The combination is done ``temporally'', i.e., as if the data in each view corresponds to a different time instant. The combination will fail if the meshes in all the views are not identical.

Combine TimeStepsFromAllViews;
     Combines the data from all the post-processing views into a new multi-time-step view. The combination is done ``temporally'', i.e., as if the data in each view corresponds to a different time instant. The combination will fail if the meshes in all the views are not identical.

Combine TimeStepsFromVisibleViews;
     Combines the data from all the visible post-processing views into a new multi-time-step view. The combination is done ``temporally'', i.e., as if the data in each view corresponds to a different time instant. The combination will fail if the meshes in all the views are not identical.

Delete View[EXPRESSION];
     Deletes (removes) the EXPRESSION-th post-processing view. Note that post-processing view numbers start at 0.

Delete Empty Views;
     Deletes (removes) all the empty post-processing views.

Background Mesh View[EXPRESSION];
     Applies the EXPRESSION-th post-processing view as the current background mesh. Note that post-processing view numbers start at 0.

Plugin (STRING) . Run;
     Executes the plugin STRING. The list of default plugins is given in Post-processing plugins.

Plugin (STRING) . STRING = EXPRESSION | CHAR-EXPRESSION;
     Sets an option for a given plugin. See Post-processing plugins, for a list of default plugins and t9.geo, for some examples.

Save View[EXPRESSION] CHAR-EXPRESSION;
     Saves the the EXPRESSION-th post-processing view in a file named CHAR-EXPRESSION. If the path in CHAR-EXPRESSION is not absolute, CHAR-EXPRESSION is appended to the path of the current file.

View "STRING" { STRING < ( EXPRESSION-LIST ) > { EXPRESSION-LIST }; ... };
     Creates a new post-processing view, named "STRING".  This is an easy and quite powerful way to import post-processing data: all the values are EXPRESSIONS, you can embed datasets directly into your geometrical descriptions (see, e.g., t4.geo), the data can be easily generated ``on-the-fly'' (there is no header containing a priori information on the size of the dataset). The syntax is also very permissive, which makes it ideal for testing purposes.

     However this ``parsed format'' is read by Gmsh's script parser, which makes it inefficient if there are many elements in the dataset. Also, there is no connectivity information in parsed views and all the elements are independent (all fields can be discontinuous), so a lot of information can be duplicated. For large datasets, you should thus use the mesh-based post-processing file format described in File formats, or use one of the standard formats like MED.

     More explicitly, the syntax for a parsed View is the following

          View "STRING" {
            TYPE ( LIST-OF-COORDS ) { LIST-OF-VALUES }; ...
            < TIME { EXPRESSION-LIST }; >
            < INTERPOLATION_SCHEME { VAL-COEF-MATRIX } { VAL-EXP-MATRIX }
                            < { GEO-COEF-MATRIX } { GEO-EXP-MATRIX } > ; >
          };

     where the 47 object TYPEs that can be displayed are:

                                        TYPE  #LIST-OF-COORDS  #LIST-OF-VALUES
          --------------------------------------------------------------------
          Scalar point                  SP    3            1  * NB-TIME-STEPS
          Vector point                  VP    3            3  * NB-TIME-STEPS
          Tensor point                  TP    3            9  * NB-TIME-STEPS
          Scalar line                   SL    6            2  * NB-TIME-STEPS
          Vector line                   VL    6            6  * NB-TIME-STEPS
          Tensor line                   TL    6            18 * NB-TIME-STEPS
          Scalar triangle               ST    9            3  * NB-TIME-STEPS
          Vector triangle               VT    9            9  * NB-TIME-STEPS
          Tensor triangle               TT    9            27 * NB-TIME-STEPS
          Scalar quadrangle             SQ    12           4  * NB-TIME-STEPS
          Vector quadrangle             VQ    12           12 * NB-TIME-STEPS
          Tensor quadrangle             TQ    12           36 * NB-TIME-STEPS
          Scalar tetrahedron            SS    12           4  * NB-TIME-STEPS
          Vector tetrahedron            VS    12           12 * NB-TIME-STEPS
          Tensor tetrahedron            TS    12           36 * NB-TIME-STEPS
          Scalar hexahedron             SH    24           8  * NB-TIME-STEPS
          Vector hexahedron             VH    24           24 * NB-TIME-STEPS
          Tensor hexahedron             TH    24           72 * NB-TIME-STEPS
          Scalar prism                  SI    18           6  * NB-TIME-STEPS
          Vector prism                  VI    18           18 * NB-TIME-STEPS
          Tensor prism                  TI    18           54 * NB-TIME-STEPS
          Scalar pyramid                SY    15           5  * NB-TIME-STEPS
          Vector pyramid                VY    15           15 * NB-TIME-STEPS
          Tensor pyramid                TY    15           45 * NB-TIME-STEPS
          2D text                       T2    3            arbitrary
          3D text                       T3    4            arbitrary

     The coordinates are given `by node', i.e.,

       * (COORD1, COORD2, COORD3) for a point,

       * (COORD1-NODE1, COORD2-NODE1, COORD3-NODE1,

           COORD1-NODE2, COORD2-NODE2, COORD3-NODE2) for a line,

       * (COORD1-NODE1, COORD2-NODE1, COORD3-NODE1,

           COORD1-NODE2, COORD2-NODE2, COORD3-NODE2,

           COORD1-NODE3, COORD2-NODE3, COORD3-NODE3) for a triangle,

       * etc.

     The ordering of the nodes is given in Node ordering.

     The values are given by time step, by node and by component, i.e.:

          COMP1-NODE1-TIME1, COMP2-NODE1-TIME1, COMP3-NODE1-TIME1,
          COMP1-NODE2-TIME1, COMP2-NODE2-TIME1, COMP3-NODE2-TIME1,
          COMP1-NODE3-TIME1, COMP2-NODE3-TIME1, COMP3-NODE3-TIME1,
          COMP1-NODE1-TIME2, COMP2-NODE1-TIME2, COMP3-NODE1-TIME2,
          COMP1-NODE2-TIME2, COMP2-NODE2-TIME2, COMP3-NODE2-TIME2,
          COMP1-NODE3-TIME2, COMP2-NODE3-TIME2, COMP3-NODE3-TIME2,
          ...

     For the 2D text objects, the two first EXPRESSIONs in LIST-OF-COORDS give the X-Y position of the string in screen coordinates, measured from the top-left corner of the window. If the first (respectively second) EXPRESSION is negative, the position is measured from the right (respectively bottom) edge of the window. If the value of the first (respectively second) EXPRESSION is larger than 99999, the string is centered horizontally (respectively vertically). If the third EXPRESSION is equal to zero, the text is aligned bottom-left and displayed using the default font and size. Otherwise, the third EXPRESSION is converted into an integer whose eight lower bits give the font size, whose eight next bits select the font (the index corresponds to the position in the font menu in the GUI), and whose eight next bits define the text alignment (0=bottom-left, 1=bottom-center, 2=bottom-right, 3=top-left, 4=top-center, 5=top-right, 6=center-left, 7=center-center, 8=center-right).

     For the 3D text objects, the three first EXPRESSIONs in LIST-OF-COORDS give the XYZ position of the string in model (real world) coordinates.  The fourth EXPRESSION has the same meaning as the third EXPRESSION in 2D text objects.

     For both 2D and 3D text objects, the LIST-OF-VALUES can contain an arbitrary number of CHAR-EXPRESSIONs.

     The optional TIME list can contain a list of expressions giving the value of the time (or any other variable) for which an evolution was saved.

     The optional INTERPOLATION_SCHEME lists can contain the interpolation matrices used for high-order adaptive visualization.

     Let us assume that the approximation of the view's value over an element is written as a linear combination of D basis functions F[I], I=0, ..., D-1 (the coefficients being stored in LIST-OF-VALUES). Defining F[I] = Sum(J=0, ..., D-1) F[I][J] P[J], with P[J] = U^P[J][0] V^P[J][1] W^P[J][2] (U, V and W being the coordinates in the element's parameter space), then VAL-COEF-MATRIX denotes the D x D matrix F and VAL-EXP-MATRIX denotes the D x 3 matrix P.

     In the same way, let us also assume that the coordinates X, Y and Z of the element are obtained through a geometrical mapping from parameter space as a linear combination of M basis functions G[I], I=0, ..., M-1 (the coefficients being stored in LIST-OF-COORDS). Defining G[I] = Sum(J=0, ..., M-1) G[I][J] Q[J], with Q[J] = U^Q[J][0] V^Q[J][1] W^Q[J][2], then VAL-COEF-MATRIX denotes the M x M matrix G and VAL-EXP-MATRIX denotes the M x 3 matrix Q.

     Here are for example the interpolation matrices for a first order quadrangle:

          INTERPOLATION_SCHEME
          {
            {1/4,-1/4, 1/4,-1/4},
            {1/4, 1/4,-1/4,-1/4},
            {1/4, 1/4, 1/4, 1/4},
            {1/4,-1/4,-1/4, 1/4}
          }
          {
            {0, 0, 0},
            {1, 0, 0},
            {0, 1, 0},
            {1, 1, 0}
          };

Post-processing plugins
=======================

Post-processing plugins permit to extend the functionality of Gmsh's post-processing module. The difference between regular post-processing options (see Post-processing options list) and post-processing plugins is that regular post-processing options only change the way the data is displayed, while post-processing plugins either create new post-processing views, or modify the data stored in a view (in a destructive, non-reversible way).

Plugins are available in the GUI by right-clicking on a view button (or by clicking on the black arrow next to the view button) and then selecting the `Plugin' submenu.

Here is the list of the plugins that are shipped by default with Gmsh:

     [file opt_plugin.texi not included]

Post-processing options
=======================

General post-processing option names have the form `PostProcessing.STRING'. Options peculiar to post-processing views take two forms.

 1. options that should apply to all views can be set through `View.STRING', before any view is loaded;

 2. options that should apply only to the N-th view take the form `View[N].STRING' (N = 0, 1, 2, ...), after the N-th view is loaded.

The list of all post-processing and view options is given in Post-processing options list.  See t8.geo, and t9.geo, for some examples.

File formats
************

This chapter describes Gmsh's native ``MSH'' file format, used to store meshes and associated post-processing datasets. The MSH format exists in two flavors: ASCII and binary. The format has a version number (currently: 2.2) that is independent of Gmsh's main version number.

(Remember that for small post-processing datasets you can also use human-readable ``parsed'' post-processing views, as described in Post-processing commands. Such ``parsed'' views do not require an underlying mesh, and can therefore be easier to use in some cases.)

MSH ASCII file format
=====================

The MSH ASCII file format contains one mandatory section giving information about the file ($MeshFormat), followed by several optional sections defining the nodes ($Nodes), elements ($Elements), region names ($PhysicalName), periodicity relations ($Periodic) and post-processing datasets ($NodeData, $ElementData, $ElementNodeData).

When $Elements are given, $Nodes should also be provided, before the $Elements section. Currently only one $Nodes and one $Elements section are allowed per file. (This might/will change in the future.)

Any section with an unrecognized header is simply ignored: you can thus add comments in a .msh file by putting them e.g. inside a $Comments/$EndComments section.

Sections can be repeated in the same file, and post-processing sections can be put into separate files (e.g. one file per time step).  Nodes are assumed to be defined before elements.

The format is defined as follows:

     $MeshFormat
     VERSION-NUMBER FILE-TYPE DATA-SIZE
     $EndMeshFormat
     $Nodes
     NUMBER-OF-NODES
     NODE-NUMBER X-COORD Y-COORD Z-COORD
     ...
     $EndNodes
     $Elements
     NUMBER-OF-ELEMENTS
     ELM-NUMBER ELM-TYPE NUMBER-OF-TAGS < TAG > ... NODE-NUMBER-LIST
     ...
     $EndElements
     $Periodic
     NUMBER-OF-PERIODIC-ENTITIES
     DIMENSION SLAVE-ENTITY-TAG MASTER-ENTITY-TAG
     NUMBER-OF-NODES
     SLAVE-NODE-NUMBER MASTER-NODE-NUMBER
     ...
     $EndPeriodic
     $PhysicalNames
     NUMBER-OF-NAMES
     PHYSICAL-DIMENSION PHYSICAL-NUMBER "PHYSICAL-NAME"
     ...
     $EndPhysicalNames
     $NodeData
     NUMBER-OF-STRING-TAGS
     < "STRING-TAG" >
     ...
     NUMBER-OF-REAL-TAGS
     < REAL-TAG >
     ...
     NUMBER-OF-INTEGER-TAGS
     < INTEGER-TAG >
     ...
     NODE-NUMBER VALUE ...
     ...
     $EndNodeData
     $ElementData
     NUMBER-OF-STRING-TAGS
     < "STRING-TAG" >
     ...
     NUMBER-OF-REAL-TAGS
     < REAL-TAG >
     ...
     NUMBER-OF-INTEGER-TAGS
     < INTEGER-TAG >
     ...
     ELM-NUMBER VALUE ...
     ...
     $EndElementData
     $ElementNodeData
     NUMBER-OF-STRING-TAGS
     < "STRING-TAG" >
     ...
     NUMBER-OF-REAL-TAGS
     < REAL-TAG >
     ...
     NUMBER-OF-INTEGER-TAGS
     < INTEGER-TAG >
     ...
     ELM-NUMBER NUMBER-OF-NODES-PER-ELEMENT VALUE ...
     ...
     $EndElementNodeData
     $InterpolationScheme
     "NAME"
     NUMBER-OF-ELEMENT-TOPOLOGIES
     ELM-TOPOLOGY
     NUMBER-OF-INTERPOLATION-MATRICES
     NUM-ROWS NUM-COLUMNS VALUE ...
     ...
     $EndInterpolationScheme

where

VERSION-NUMBER
     is a real number equal to 2.2

FILE-TYPE
     is an integer equal to 0 in the ASCII file format.

DATA-SIZE
     is an integer equal to the size of the floating point numbers used in the file (currently only DATA-SIZE = sizeof(double) is supported).

NUMBER-OF-NODES
     is the number of nodes in the mesh.

NODE-NUMBER
     is the number (index) of the N-th node in the mesh; NODE-NUMBER must be a postive (non-zero) integer. Note that the NODE-NUMBERs do not necessarily have to form a dense nor an ordered sequence.

X-COORD Y-COORD Z-COORD
     are the floating point values giving the X, Y and Z coordinates of the N-th node.

NUMBER-OF-ELEMENTS
     is the number of elements in the mesh.

ELM-NUMBER
     is the number (index) of the N-th element in the mesh; ELM-NUMBER must be a postive (non-zero) integer. Note that the ELM-NUMBERs do not necessarily have to form a dense nor an ordered sequence.

ELM-TYPE
     defines the geometrical type of the N-th element:

     1
          2-node line.

     2
          3-node triangle.

     3
          4-node quadrangle.

     4
          4-node tetrahedron.

     5
          8-node hexahedron.

     6
          6-node prism.

     7
          5-node pyramid.

     8
          3-node second order line (2 nodes associated with the vertices and 1 with the edge).

     9
          6-node second order triangle (3 nodes associated with the vertices and 3 with the edges).

     10
          9-node second order quadrangle (4 nodes associated with the vertices, 4 with the edges and 1 with the face).

     11
          10-node second order tetrahedron (4 nodes associated with the vertices and 6 with the edges).

     12
          27-node second order hexahedron (8 nodes associated with the vertices, 12 with the edges, 6 with the faces and 1 with the volume).

     13
          18-node second order prism (6 nodes associated with the vertices, 9 with the edges and 3 with the quadrangular faces).

     14
          14-node second order pyramid (5 nodes associated with the vertices, 8 with the edges and 1 with the quadrangular face).

     15
          1-node point.

     16
          8-node second order quadrangle (4 nodes associated with the vertices and 4 with the edges).

     17
          20-node second order hexahedron (8 nodes associated with the vertices and 12 with the edges).

     18
          15-node second order prism (6 nodes associated with the vertices and 9 with the edges).

     19
          13-node second order pyramid (5 nodes associated with the vertices and 8 with the edges).

     20
          9-node third order incomplete triangle (3 nodes associated with the vertices, 6 with the edges)

     21
          10-node third order triangle (3 nodes associated with the vertices, 6 with the edges, 1 with the face)

     22
          12-node fourth order incomplete triangle (3 nodes associated with the vertices, 9 with the edges)

     23
          15-node fourth order triangle (3 nodes associated with the vertices, 9 with the edges, 3 with the face)

     24
          15-node fifth order incomplete triangle (3 nodes associated with the vertices, 12 with the edges)

     25
          21-node fifth order complete triangle (3 nodes associated with the vertices, 12 with the edges, 6 with the face)

     26
          4-node third order edge (2 nodes associated with the vertices, 2 internal to the edge)

     27
          5-node fourth order edge (2 nodes associated with the vertices, 3 internal to the edge)

     28
          6-node fifth order edge (2 nodes associated with the vertices, 4 internal to the edge)

     29
          20-node third order tetrahedron (4 nodes associated with the vertices, 12 with the edges, 4 with the faces)

     30
          35-node fourth order tetrahedron (4 nodes associated with the vertices, 18 with the edges, 12 with the faces, 1 in the volume)

     31
          56-node fifth order tetrahedron (4 nodes associated with the vertices, 24 with the edges, 24 with the faces, 4 in the volume)

     92
          64-node third order hexahedron (8 nodes associated with the vertices, 24 with the edges, 24 with the faces, 8 in the volume)

     93
          125-node fourth order hexahedron (8 nodes associated with the vertices, 36 with the edges, 54 with the faces, 27 in the volume)

     See below for the ordering of the nodes.

NUMBER-OF-TAGS
     gives the number of integer tags that follow for the N-th element. By default, the first TAG is the number of the physical entity to which the element belongs; the second is the number of the elementary geometrical entity to which the element belongs; the third is the number of mesh partitions to which the element belongs, followed by the partition ids (negative partition ids indicate ghost cells). A zero tag is equivalent to no tag.

NODE-NUMBER-LIST
     is the list of the node numbers of the N-th element. The ordering of the nodes is given in Node ordering.

NUMBER-OF-STRING-TAGS
     gives the number of string tags that follow. By default the first STRING-TAG is interpreted as the name of the post-processing view and the second as the name of the interpolation scheme. The interpolation scheme is provided in the $InterpolationScheme section (see below).

NUMBER-OF-REAL-TAGS
     gives the number of real number tags that follow. By default the first REAL-TAG is interpreted as a time value associated with the dataset.

NUMBER-OF-INTEGER-TAGS
     gives the number of integer tags that follow. By default the first INTEGER-TAG is interpreted as a time step index (starting at 0), the second as the number of field components of the data in the view (1, 3 or 9), the third as the number of entities (nodes or elements) in the view, and the fourth as the partition index for the view data (0 for no partition).

NUMBER-OF-NODES-PER-ELEMENTS
     gives the number of node values for an element in an element-based view.

VALUE
     is a real number giving the value associated with a node or an element. For NodeData (respectively ElementData) views, there are NCOMP values per node (resp. per element), where NCOMP is the number of field components. For ElementNodeData views, there are NCOMP times NUMBER-OF-NODES-PER-ELEMENTS values per element.

NUMBER-OF-ELEMENT-TOPOLOGIES
     is the number of element topologies for which interpolation matrices are provided

ELM-TOPOLOGY
     is the id tag of a given element topology: 1 for points, 2 for lines, 3 for triangles, 4 for quadrangles, 5 for tetrahedra, 6 for pyramids, 7 for prisms, 8 for hexahedra, 9 for polygons and 10 for polyhedra.

NUMBER-OF-INTERPOLATION-MATRICES
     is the number of interpolation matrices provided for this element topology. Currently you should provide 2 matrices, i.e., the matrices that specify how to interpolate the data (they have the same meaning as in Post-processing commands).  The matrices are specified by 2 integers (NUM-ROWS and NUM-COLUMNS) followed by the values.

Below is a small example (a mesh consisting of two quadrangles with an associated nodal scalar dataset; the comments are not part of the actual file!):

     $MeshFormat
     2.2 0 8
     $EndMeshFormat
     $Nodes
     6                      six mesh nodes:
     1 0.0 0.0 0.0            node #1: coordinates (0.0, 0.0, 0.0)
     2 1.0 0.0 0.0            node #2: coordinates (1.0, 0.0, 0.0)
     3 1.0 1.0 0.0            etc.
     4 0.0 1.0 0.0
     5 2.0 0.0 0.0
     6 2.0 1.0 0.0
     $EndNodes
     $Elements
     2                      two elements:
     1 3 2 99 2 1 2 3 4       quad #1: type 3, physical 99, elementary 2, nodes 1 2 3 4
     2 3 2 99 2 2 5 6 3       quad #2: type 3, physical 99, elementary 2, nodes 2 5 6 3
     $EndElements
     $NodeData
     1                      one string tag:
     "A scalar view"          the name of the view ("A scalar view")
     1                      one real tag:
     0.0                      the time value (0.0)
     3                      three integer tags:
     0                        the time step (0; time steps always start at 0)
     1                        1-component (scalar) field
     6                        six associated nodal values
     1 0.0                  value associated with node #1 (0.0)
     2 0.1                  value associated with node #2 (0.1)
     3 0.2                  etc.
     4 0.0
     5 0.2
     6 0.4
     $EndNodeData

MSH binary file format
======================

The binary file format is similar to the ASCII format described above:

     $MeshFormat
     VERSION-NUMBER FILE-TYPE DATA-SIZE
     ONE-BINARY
     $EndMeshFormat
     $Nodes
     NUMBER-OF-NODES
     NODES-BINARY
     $EndNodes
     $Elements
     NUMBER-OF-ELEMENTS
     ELEMENT-HEADER-BINARY
     ELEMENTS-BINARY
     ELEMENT-HEADER-BINARY
     ELEMENTS-BINARY
     ...
     $EndElements

     [ all other sections are identical to ASCII, except that NODE-NUMBER,
       ELM-NUMBER, NUMBER-OF-NODES-PER-ELEMENT and VALUES are written in
       binary format ]

where

VERSION-NUMBER
     is a real number equal to 2.2.

FILE-TYPE
     is an integer equal to 1.

DATA-SIZE
     has the same meaning as in the ASCII file format. Currently only DATA-SIZE = sizeof(double) is supported.

ONE-BINARY
     is an integer of value 1 written in binary form. This integer is used for detecting if the computer on which the binary file was written and the computer on which the file is read are of the same type (little or big endian).

     Here is a pseudo C code to write ONE-BINARY:

          int one = 1;
          fwrite(&one, sizeof(int), 1, file);

NUMBER-OF-NODES
     has the same meaning as in the ASCII file format.

NODES-BINARY
     is the list of nodes in binary form, i.e., a array of NUMBER-OF-NODES * (4 + 3 * DATA-SIZE) bytes. For each node, the first 4 bytes contain the node number and the next (3 * DATA-SIZE) bytes contain the three floating point coordinates.

     Here is a pseudo C code to write NODES-BINARY:

          for(i = 0; i < number_of_nodes; i++){
            fwrite(&num_i, sizeof(int), 1, file);
            double xyz[3] = {node_i_x, node_i_y, node_i_z};
            fwrite(&xyz, sizeof(double), 3, file);
          }

NUMBER-OF-ELEMENTS
     has the same meaning as in the ASCII file format.

ELEMENT-HEADER-BINARY
     is a list of 3 integers in binary form, i.e., an array of (3 * 4) bytes: the first four bytes contain the type of the elements that follow (same as ELM-TYPE in the ASCII format), the next four contain the number of elements that follow, and the last four contain the number of tags per element (same as NUMBER-OF-TAGS in the ASCII format).

     Here is a pseudo C code to write ELEMENT-HEADER-BINARY:

          int header[3] = {elm_type, num_elm_follow, num_tags};
          fwrite(&header, sizeof(int), 2, file);

ELEMENTS-BINARY
     is a list of elements in binary form, i.e., an array of ``number of elements that follow'' * (4 + NUMBER-OF-TAGS * 4 + #NODE-NUMBER-LIST * 4) bytes. For each element, the first four bytes contain the element number, the next (NUMBER-OF-TAGS * 4) contain the tags, and the last (#NODE-NUMBER-LIST * 4) contain the node indices.

     Here is a pseudo C code to write ELEMENTS-BINARY for triangles with the 2 standard tags (the physical and elementary regions):

          for(i = 0; i < number_of_triangles; i++){
            int data[6] = {num_i, physical, elementary,
                           node_i_1, node_i_2, node_i_3};
            fwrite(data, sizeof(int), 6, file);
          }

Node ordering
=============

Historically, Gmsh developpers have started by implementing linear elements (lines, triangles, quads, tets, prisms and hexes). Then, second and sometimes third order elements have been hardcoded. We here distinguish ``low order elements'' that have been hardcoded initially and ``high order elements'' that have been coded in a general fashion, theoretically valid for any order.

Low order elements
------------------

For all mesh and post-processing file formats, the reference elements are defined as follows.

     Line:                   Line3:           Line4:

     0----------1 --> u      0-----2----1     0----2----3----1

     Triangle:               Triangle6:          Triangle9/10:          Triangle12/15:

     v
     ^                                                                   2
     |                                                                   | \
     2                       2                    2                      9   8
     |`\                     |`\                  | \                    |     \
     |  `\                   |  `\                7   6                 10 (14)  7
     |    `\                 5    `4              |     \                |         \
     |      `\               |      `\            8  (9)  5             11 (12) (13) 6
     |        `\             |        `\          |         \            |             \
     0----------1 --> u      0-----3----1         0---3---4---1          0---3---4---5---1

     Quadrangle:            Quadrangle8:            Quadrangle9:

           v
           ^
           |
     3-----------2          3-----6-----2           3-----6-----2
     |     |     |          |           |           |           |
     |     |     |          |           |           |           |
     |     +---- | --> u    7           5           7     8     5
     |           |          |           |           |           |
     |           |          |           |           |           |
     0-----------1          0-----4-----1           0-----4-----1

     Tetrahedron:                          Tetrahedron10:

                        v
                      .
                    ,/
                   /
                2                                     2
              ,/|`\                                 ,/|`\
            ,/  |  `\                             ,/  |  `\
          ,/    '.   `\                         ,6    '.   `5
        ,/       |     `\                     ,/       8     `\
      ,/         |       `\                 ,/         |       `\
     0-----------'.--------1 --> u         0--------4--'.--------1
      `\.         |      ,/                 `\.         |      ,/
         `\.      |    ,/                      `\.      |    ,9
            `\.   '. ,/                           `7.   '. ,/
               `\. |/                                `\. |/
                  `3                                    `3
                     `\.
                        ` w

     Hexahedron:             Hexahedron20:          Hexahedron27:

            v
     3----------2            3----13----2           3----13----2
     |\     ^   |\           |\         |\          |\         |\
     | \    |   | \          | 15       | 14        |15    24  | 14
     |  \   |   |  \         9  \       11 \        9  \ 20    11 \
     |   7------+---6        |   7----19+---6       |   7----19+---6
     |   |  +-- |-- | -> u   |   |      |   |       |22 |  26  | 23|
     0---+---\--1   |        0---+-8----1   |       0---+-8----1   |
      \  |    \  \  |         \  17      \  18       \ 17    25 \  18
       \ |     \  \ |         10 |        12|        10 |  21    12|
        \|      w  \|           \|         \|          \|         \|
         4----------5            4----16----5           4----16----5

     Prism:                      Prism15:               Prism18:

                w
                ^
                |
                3                       3                      3
              ,/|`\                   ,/|`\                  ,/|`\
            ,/  |  `\               12  |  13              12  |  13
          ,/    |    `\           ,/    |    `\          ,/    |    `\
         4------+------5         4------14-----5        4------14-----5
         |      |      |         |      8      |        |      8      |
         |    ,/|`\    |         |      |      |        |    ,/|`\    |
         |  ,/  |  `\  |         |      |      |        |  15  |  16  |
         |,/    |    `\|         |      |      |        |,/    |    `\|
        ,|      |      |\        10     |      11       10-----17-----11
      ,/ |      0      | `\      |      0      |        |      0      |
     u   |    ,/ `\    |    v    |    ,/ `\    |        |    ,/ `\    |
         |  ,/     `\  |         |  ,6     `7  |        |  ,6     `7  |
         |,/         `\|         |,/         `\|        |,/         `\|
         1-------------2         1------9------2        1------9------2

     Pyramid:                     Pyramid13:                   Pyramid14:

                    4                            4                            4
                  ,/|\                         ,/|\                         ,/|\
                ,/ .'|\                      ,/ .'|\                      ,/ .'|\
              ,/   | | \                   ,/   | | \                   ,/   | | \
            ,/    .' | `.                ,/    .' | `.                ,/    .' | `.
          ,/      |  '.  \             ,7      |  12  \             ,7      |  12  \
        ,/       .' w |   \          ,/       .'   |   \          ,/       .'   |   \
      ,/         |  ^ |    \       ,/         9    |    11      ,/         9    |    11
     0----------.'--|-3    `.     0--------6-.'----3    `.     0--------6-.'----3    `.
      `\        |   |  `\    \      `\        |      `\    \     `\        |      `\    \
        `\     .'   +----`\ - \ -> v  `5     .'        10   \      `5     .' 13     10   \
          `\   |    `\     `\  \        `\   |           `\  \       `\   |           `\  \
            `\.'      `\     `\`          `\.'             `\`         `\.'             `\`
               1----------------2            1--------8-------2           1--------8-------2
                         `\
                            u

High order elements
-------------------

The node ordering of a higher order (possibly curved) element is compatible with the numbering of low order element (it is a generalization). We number nodes in the following order:

  -- the element principal or corner vertices;

  -- the internal nodes for each edge;

  -- the internal nodes for each face;

  -- the volume internal nodes.

The numbering for internal nodes is recursive, ie. the numbering follows that of the nodes of an embedded edge/face/volume of lower order. The higher order nodes are assumed to be equispaced. Edges and faces are numbered following the lowest order template that generates a single high-order on this edge/face. Furthermore, an edge is oriented from the vertex with the lowest to the highest index. The orientation of a face is such that the computed normal points outward; the starting point is the vertex with the lowest index.

Legacy formats
==============

This section describes Gmsh's older native file formats. Future versions of Gmsh will continue to support these formats, but we recommend that you do not use them in new applications.

MSH file format version 1.0 (Legacy)
------------------------------------

The MSH file format version 1.0 is Gmsh's old native mesh file format, now superseded by the format described in MSH ASCII file format. It is defined as follows:

     $NOD
     NUMBER-OF-NODES
     NODE-NUMBER X-COORD Y-COORD Z-COORD
     ...
     $ENDNOD
     $ELM
     NUMBER-OF-ELEMENTS
     ELM-NUMBER ELM-TYPE REG-PHYS REG-ELEM NUMBER-OF-NODES NODE-NUMBER-LIST
     ...
     $ENDELM

where

NUMBER-OF-NODES
     is the number of nodes in the mesh.

NODE-NUMBER
     is the number (index) of the N-th node in the mesh; NODE-NUMBER must be a postive (non-zero) integer. Note that the NODE-NUMBERs do not necessarily have to form a dense nor an ordered sequence.

X-COORD Y-COORD Z-COORD
     are the floating point values giving the X, Y and Z coordinates of the N-th node.

NUMBER-OF-ELEMENTS
     is the number of elements in the mesh.

ELM-NUMBER
     is the number (index) of the N-th element in the mesh; ELM-NUMBER must be a postive (non-zero) integer. Note that the ELM-NUMBERs do not necessarily have to form a dense nor an ordered sequence.

ELM-TYPE
     defines the geometrical type of the N-th element:

     1
          2-node line.

     2
          3-node triangle.

     3
          4-node quadrangle.

     4
          4-node tetrahedron.

     5
          8-node hexahedron.

     6
          6-node prism.

     7
          5-node pyramid.

     8
          3-node second order line (2 nodes associated with the vertices and 1 with the edge).

     9
          6-node second order triangle (3 nodes associated with the vertices and 3 with the edges).

     10
          9-node second order quadrangle (4 nodes associated with the vertices, 4 with the edges and 1 with the face).

     11
          10-node second order tetrahedron (4 nodes associated with the vertices and 6 with the edges).

     12
          27-node second order hexahedron (8 nodes associated with the vertices, 12 with the edges, 6 with the faces and 1 with the volume).

     13
          18-node second order prism (6 nodes associated with the vertices, 9 with the edges and 3 with the quadrangular faces).

     14
          14-node second order pyramid (5 nodes associated with the vertices, 8 with the edges and 1 with the quadrangular face).

     15
          1-node point.

     16
          8-node second order quadrangle (4 nodes associated with the vertices and 4 with the edges).

     17
          20-node second order hexahedron (8 nodes associated with the vertices and 12 with the edges).

     18
          15-node second order prism (6 nodes associated with the vertices and 9 with the edges).

     19
          13-node second order pyramid (5 nodes associated with the vertices and 8 with the edges).

     See below for the ordering of the nodes.

REG-PHYS
     is the number of the physical entity to which the element belongs; REG-PHYS must be a postive integer, or zero. If REG-PHYS is equal to zero, the element is considered not to belong to any physical entity.

REG-ELEM
     is the number of the elementary entity to which the element belongs; REG-ELEM must be a postive (non-zero) integer.

NUMBER-OF-NODES
     is the number of nodes for the N-th element. This is redundant, but kept for backward compatibility.

NODE-NUMBER-LIST
     is the list of the NUMBER-OF-NODES node numbers of the N-th element. The ordering of the nodes is given in Node ordering.

POS ASCII file format (Legacy)
------------------------------

The POS ASCII file is Gmsh's old native post-processing format, now superseded by the format described in MSH ASCII file format. It is defined as follows:

     $PostFormat
     1.4 FILE-TYPE DATA-SIZE
     $EndPostFormat
     $View
     VIEW-NAME NB-TIME-STEPS
     NB-SCALAR-POINTS NB-VECTOR-POINTS NB-TENSOR-POINTS
     NB-SCALAR-LINES NB-VECTOR-LINES NB-TENSOR-LINES
     NB-SCALAR-TRIANGLES NB-VECTOR-TRIANGLES NB-TENSOR-TRIANGLES
     NB-SCALAR-QUADRANGLES NB-VECTOR-QUADRANGLES NB-TENSOR-QUADRANGLES
     NB-SCALAR-TETRAHEDRA NB-VECTOR-TETRAHEDRA NB-TENSOR-TETRAHEDRA
     NB-SCALAR-HEXAHEDRA NB-VECTOR-HEXAHEDRA NB-TENSOR-HEXAHEDRA
     NB-SCALAR-PRISMS NB-VECTOR-PRISMS NB-TENSOR-PRISMS
     NB-SCALAR-PYRAMIDS NB-VECTOR-PYRAMIDS NB-TENSOR-PYRAMIDS
     NB-SCALAR-LINES2 NB-VECTOR-LINES2 NB-TENSOR-LINES2
     NB-SCALAR-TRIANGLES2 NB-VECTOR-TRIANGLES2 NB-TENSOR-TRIANGLES2
     NB-SCALAR-QUADRANGLES2 NB-VECTOR-QUADRANGLES2 NB-TENSOR-QUADRANGLES2
     NB-SCALAR-TETRAHEDRA2 NB-VECTOR-TETRAHEDRA2 NB-TENSOR-TETRAHEDRA2
     NB-SCALAR-HEXAHEDRA2 NB-VECTOR-HEXAHEDRA2 NB-TENSOR-HEXAHEDRA2
     NB-SCALAR-PRISMS2 NB-VECTOR-PRISMS2 NB-TENSOR-PRISMS2
     NB-SCALAR-PYRAMIDS2 NB-VECTOR-PYRAMIDS2 NB-TENSOR-PYRAMIDS2
     NB-TEXT2D NB-TEXT2D-CHARS NB-TEXT3D NB-TEXT3D-CHARS
     TIME-STEP-VALUES
     < SCALAR-POINT-VALUE > ... < VECTOR-POINT-VALUE > ...
         < TENSOR-POINT-VALUE > ...
     < SCALAR-LINE-VALUE > ... < VECTOR-LINE-VALUE > ...
         < TENSOR-LINE-VALUE > ...
     < SCALAR-TRIANGLE-VALUE > ... < VECTOR-TRIANGLE-VALUE > ...
         < TENSOR-TRIANGLE-VALUE > ...
     < SCALAR-QUADRANGLE-VALUE > ... < VECTOR-QUADRANGLE-VALUE > ...
         < TENSOR-QUADRANGLE-VALUE > ...
     < SCALAR-TETRAHEDRON-VALUE > ... < VECTOR-TETRAHEDRON-VALUE > ...
         < TENSOR-TETRAHEDRON-VALUE > ...
     < SCALAR-HEXAHEDRON-VALUE > ... < VECTOR-HEXAHEDRON-VALUE > ...
         < TENSOR-HEXAHEDRON-VALUE > ...
     < SCALAR-PRISM-VALUE > ... < VECTOR-PRISM-VALUE > ...
         < TENSOR-PRISM-VALUE > ...
     < SCALAR-PYRAMID-VALUE > ... < VECTOR-PYRAMID-VALUE > ...
         < TENSOR-PYRAMID-VALUE > ...
     < SCALAR-LINE2-VALUE > ... < VECTOR-LINE2-VALUE > ...
         < TENSOR-LINE2-VALUE > ...
     < SCALAR-TRIANGLE2-VALUE > ... < VECTOR-TRIANGLE2-VALUE > ...
         < TENSOR-TRIANGLE2-VALUE > ...
     < SCALAR-QUADRANGLE2-VALUE > ... < VECTOR-QUADRANGLE2-VALUE > ...
         < TENSOR-QUADRANGLE2-VALUE > ...
     < SCALAR-TETRAHEDRON2-VALUE > ... < VECTOR-TETRAHEDRON2-VALUE > ...
         < TENSOR-TETRAHEDRON2-VALUE > ...
     < SCALAR-HEXAHEDRON2-VALUE > ... < VECTOR-HEXAHEDRON2-VALUE > ...
         < TENSOR-HEXAHEDRON2-VALUE > ...
     < SCALAR-PRISM2-VALUE > ... < VECTOR-PRISM2-VALUE > ...
         < TENSOR-PRISM2-VALUE > ...
     < SCALAR-PYRAMID2-VALUE > ... < VECTOR-PYRAMID2-VALUE > ...
         < TENSOR-PYRAMID2-VALUE > ...
     < TEXT2D > ... < TEXT2D-CHARS > ...
     < TEXT3D > ... < TEXT3D-CHARS > ...
     $EndView

where

FILE-TYPE
     is an integer equal to 0 in the ASCII file format.

DATA-SIZE
     is an integer equal to the size of the floating point numbers used in the file (usually, DATA-SIZE = sizeof(double)).

VIEW-NAME
     is a string containing the name of the view (max. 256 characters).

NB-TIME-STEPS
     is an integer giving the number of time steps in the view.

NB-SCALAR-POINTS

NB-VECTOR-POINTS

...
     are integers giving the number of scalar points, vector points, ..., in the view.

NB-TEXT2D

NB-TEXT3D
     are integers giving the number of 2D and 3D text strings in the view.

NB-TEXT2D-CHARS

NB-TEXT3D-CHARS
     are integers giving the total number of characters in the 2D and 3D strings.

TIME-STEP-VALUES
     is a list of NB-TIME-STEPS double precision numbers giving the value of the time (or any other variable) for which an evolution was saved.

SCALAR-POINT-VALUE

VECTOR-POINT-VALUE

...
     are lists of double precision numbers giving the node coordinates and the values associated with the nodes of the NB-SCALAR-POINTS scalar points, NB-VECTOR-POINTS vector points, ..., for each of the TIME-STEP-VALUES.

     For example, VECTOR-TRIANGLE-VALUE is defined as:

          COORD1-NODE1 COORD1-NODE2 COORD1-NODE3
          COORD2-NODE1 COORD2-NODE2 COORD2-NODE3
          COORD3-NODE1 COORD3-NODE2 COORD3-NODE3
          COMP1-NODE1-TIME1 COMP2-NODE1-TIME1 COMP3-NODE1-TIME1
          COMP1-NODE2-TIME1 COMP2-NODE2-TIME1 COMP3-NODE2-TIME1
          COMP1-NODE3-TIME1 COMP2-NODE3-TIME1 COMP3-NODE3-TIME1
          COMP1-NODE1-TIME2 COMP2-NODE1-TIME2 COMP3-NODE1-TIME2
          COMP1-NODE2-TIME2 COMP2-NODE2-TIME2 COMP3-NODE2-TIME2
          COMP1-NODE3-TIME2 COMP2-NODE3-TIME2 COMP3-NODE3-TIME2
          ...

     The ordering of the nodes is given in Node ordering.

TEXT2D
     is a list of 4 double precision numbers:

          COORD1 COORD2 STYLE INDEX

     where COORD1 and COORD2 give the X-Y position of the 2D string in screen coordinates (measured from the top-left corner of the window) and where INDEX gives the starting index of the string in TEXT2D-CHARS. If COORD1 (respectively COORD2) is negative, the position is measured from the right (respectively bottom) edge of the window. If COORD1 (respectively COORD2) is larger than 99999, the string is centered horizontally (respectively vertically).  If STYLE is equal to zero, the text is aligned bottom-left and displayed using the default font and size. Otherwise, STYLE is converted into an integer whose eight lower bits give the font size, whose eight next bits select the font (the index corresponds to the position in the font menu in the GUI), and whose eight next bits define the text alignment (0=bottom-left, 1=bottom-center, 2=bottom-right, 3=top-left, 4=top-center, 5=top-right, 6=center-left, 7=center-center, 8=center-right).

TEXT2D-CHARS
     is a list of NB-TEXT2D-CHARS characters. Substrings are separated with the null `\0' character.

TEXT3D
     is a list of 5 double precision numbers

          COORD1 COORD2 COORD3 STYLE INDEX

     where COORD1, COORD2 and COORD3 give the XYZ coordinates of the string in model (real world) coordinates, INDEX gives the starting index of the string in TEXT3D-CHARS, and STYLE has the same meaning as in TEXT2D.

TEXT3D-CHARS
     is a list of NB-TEXT3D-CHARS chars. Substrings are separated with the null `\0' character.

POS binary file format (Legacy)
-------------------------------

The POS binary file format is the same as the POS ASCII file format described in POS ASCII file format, except that:

 1. FILE-TYPE equals 1.

 2. all lists of floating point numbers and characters are written in binary format

 3. there is an additional integer, of value 1, written before TIME-STEP-VALUES. This integer is used for detecting if the computer on which the binary file was written and the computer on which the file is read are of the same type (little or big endian).

Here is a pseudo C code to write a post-processing file in binary format:

     int one = 1;

     fprintf(file, "$PostFormat\n");
     fprintf(file, "%g %d %d\n", 1.4, 1, sizeof(double));
     fprintf(file, "$EndPostFormat\n");
     fprintf(file, "$View\n");
     fprintf(file, "%s %d "
       "%d %d %d %d %d %d %d %d %d "
       "%d %d %d %d %d %d %d %d %d "
       "%d %d %d %d %d %d %d %d %d "
       "%d %d %d %d %d %d %d %d %d "
       "%d %d %d %d %d %d %d %d %d "
       "%d %d %d %d\n",
       view-name, nb-time-steps,
       nb-scalar-points, nb-vector-points, nb-tensor-points,
       nb-scalar-lines, nb-vector-lines, nb-tensor-lines,
       nb-scalar-triangles, nb-vector-triangles, nb-tensor-triangles,
       nb-scalar-quadrangles, nb-vector-quadrangles, nb-tensor-quadrangles,
       nb-scalar-tetrahedra, nb-vector-tetrahedra, nb-tensor-tetrahedra,
       nb-scalar-hexahedra, nb-vector-hexahedra, nb-tensor-hexahedra,
       nb-scalar-prisms, nb-vector-prisms, nb-tensor-prisms,
       nb-scalar-pyramids, nb-vector-pyramids, nb-tensor-pyramids,
       nb-scalar-lines2, nb-vector-lines2, nb-tensor-lines2,
       nb-scalar-triangles2, nb-vector-triangles2, nb-tensor-triangles2,
       nb-scalar-quadrangles2, nb-vector-quadrangles2, nb-tensor-quadrangles2,
       nb-scalar-tetrahedra2, nb-vector-tetrahedra2, nb-tensor-tetrahedra2,
       nb-scalar-hexahedra2, nb-vector-hexahedra2, nb-tensor-hexahedra2,
       nb-scalar-prisms2, nb-vector-prisms2, nb-tensor-prisms2,
       nb-scalar-pyramids2, nb-vector-pyramids2, nb-tensor-pyramids2,
       nb-text2d, nb-text2d-chars, nb-text3d, nb-text3d-chars);
     fwrite(&one, sizeof(int), 1, file);
     fwrite(time-step-values, sizeof(double), nb-time-steps, file);
     fwrite(all-scalar-point-values, sizeof(double), ..., file);
     ...
     fprintf(file, "\n$EndView\n");

In this pseudo-code, ALL-SCALAR-POINT-VALUES is the array of double precision numbers containing all the SCALAR-POINT-VALUE lists, put one after each other in order to form a long array of doubles. The principle is the same for all other kinds of values.

Tutorial
********

The following examples introduce new features gradually, starting with t1.geo. The files corresponding to these examples are available in the tutorial directory of the Gmsh distribution.

To learn how to run Gmsh on your computer, see Running Gmsh on your system. Screencasts that show how to use the GUI are available on http://geuz.org/gmsh/screencasts/.

t1.geo
======

     [file t1.geo not included]

t2.geo
======

     [file t2.geo not included]

t3.geo
======

     [file t3.geo not included]

t4.geo
======

     [file t4.geo not included]

t5.geo
======

     [file t5.geo not included]

t6.geo
======

     [file t6.geo not included]

t7.geo
======

     [file t7.geo not included]

t8.geo
======

     [file t8.geo not included]

t9.geo
======

     [file t9.geo not included]

t10.geo
=======

     [file t10.geo not included]

t11.geo
=======

     [file t11.geo not included]

t12.geo
=======

     [file t12.geo not included]

t13.geo
=======

     [file t13.geo not included]

t14.geo
=======

     [file t14.geo not included]

Options
*******

This appendix lists all the available options.  Gmsh's default behavior is to save some of these options in a per-user ``session resource'' file (cf. ``Saved in: General.SessionFileName'' in the lists below) every time Gmsh is shut down. This permits for example to automatically remember the size and location of the windows or which fonts to use. A second set of options can be saved (automatically or manually with the `File->Save Options->As Default' menu) in a per-user ``option'' file (cf. ``Saved in: General.OptionsFileName'' in the lists below), automatically loaded by Gmsh every time it starts up. Finally, other options are only saved to disk manually, either by explicitely saving an option file with `File->Save As', or when saving per-model options with `File->Save Options->For Current File' (cf. ``Saved in: -'' in the lists below).

To reset all options to their default values, use the `Restore default options' button in `Tools->Options->General->Advanced', or erase the General.SessionFileName and General.OptionsFileName files by hand.

General options list
====================

     [file opt_general.texi not included]

     [file opt_print.texi not included]

Geometry options list
=====================

     [file opt_geometry.texi not included]

Mesh options list
=================

     [file opt_mesh.texi not included]

Solver options list
===================

     [file opt_solver.texi not included]

Post-processing options list
============================

     [file opt_post.texi not included]

     [file opt_view.texi not included]

Information for developers
**************************

Gmsh is written in C++, the scripting language is parsed using Lex and Yacc (actually, Flex and Bison), and the GUI relies on OpenGL for the 3D graphics and FLTK (http://www.fltk.org) for the widget set. Gmsh's build system is based on CMake (http://www.cmake.org). Practical notes on how to compile Gmsh's source code are included in the distribution. See Frequently asked questions, for more information.

Getting the source
==================

Stable releases and nightly source snapshots are available from http://geuz.org/gmsh/src/.

You can also access the subversion repository directly:

 1. The first time you want to download the latest full source, type:

          svn co https://geuz.org/svn/gmsh/trunk gmsh

     You will be asked to accept the security certificate and to provide your username and password. (Use gmsh/gmsh for read-only access.)

 2. To update your local version to the latest and greatest, go in the gmsh directory and type:

          svn update

 3. If you have write access, to commit your changes to the central repository, go in the gmsh directory and type:

          svn commit

Source code structure
=====================

Gmsh's code is structured in several subdirectories, roughly separated between the four core modules (Geo, Mesh, Solver, Post) and associated utilities (Common, Numeric) on one hand, and the graphics (Graphics) and interface (Fltk, Parser) code on the other.

The geometry and mesh modules are based on an object-oriented model class (Geo/GModel.h), built upon abstract geometrical entity classes (Geo/GVertex.h, Geo/GEdge.h, Geo/GFace.h and Geo/GRegion.h). Concrete implementations of the geometrical entity classes are provided for each supported CAD kernel (e.g. Geo/gmshVertex.h for geometry points in Gmsh's native CAD format, or Geo/OCCVertex.h for geometry points from OpenCASCADE). The post-processing module is based on the concept of views (Post/PView.h) and abstract data containers (derived from Post/PViewData.h).

Coding style
============

If you plan to contribute code to the Gmsh project, here are some easy rules to make the code easy to read/debug/maintain:

 1. Please enable full warnings for your compiler (e.g. -Wall with g++) and don't commit until there is no warning left.

 2. Use memory checking tools to detect memory leaks and other nasty memory problems. For example, you can use

       * Valgrind on Linux:

               valgrind --leak-check=yes --show-reachable=yes gmsh file.geo -3

       * GMALLOC on Mac OS X:

               (gdb) set env DYLD_INSERT_LIBRARIES /usr/lib/libgmalloc.dylib

       * LIBNJAMD:

               export LD_PRELOAD=libnjamd.so
               kill -USR1

       * Purify

       * Memprof

       * ...

 3. always use the Msg:: class to print information or errors

 4. indent your files (2 spaces) and convert all tabs to spaces

 5. follow the style used in the existing code when adding something new (spaces after commas, opening braces for functions on a separate line, opening braces for loops and tests on the same line, etc.)

Adding a new option
===================

To add a new option in Gmsh:

 1. create the option in the CTX class (Common/Context.h) if it's a classical option, or in the PViewOptions class (Post/PViewOptions.h) if it's a post-processing view-dependent option;

 2. in Common/DefaultOptions.h, give a name (for the parser to be able to access it), a reference to a handling routine (i.e. opt_XXX) and a default value for this option;

 3. create the handling routine opt_XXX in Common/Options.cpp (and add the prototype in Common/Options.h);

 4. optional: create the associated widget in Fltk/optionWindow.cpp;

Frequently asked questions
**************************

The basics
==========

 1. What is Gmsh?

     Gmsh is an automatic three-dimensional finite element mesh generator with built-in pre- and post-processing facilities. With Gmsh you can create or import 1D, 2D and 3D geometrical models, mesh them, launch external finite element solvers and visualize solutions. Gmsh can be used either as a stand-alone program (graphical or not) or as a C++ library.

 2. What are the terms and conditions of use?

     Gmsh is distributed under the terms of the GNU General Public License, with an exception to allow for easier linking with external libraries. See License for more information.

 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 extension.

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

 4. Where can I find more information?

     http://geuz.org/gmsh is the primary location to obtain information about Gmsh. There you will for example find the complete reference manual, a bug tracking database and a searchable archive of the Gmsh mailing list (gmsh@geuz.org).

Installation problems
=====================

 1. Which OSes does Gmsh run on?

     Gmsh runs on Windows, Mac OS X, Linux and most Unix variants.

 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.

 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.

 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 $APPDATA (on Windows) or $HOME (on other OSes), then in $TMP, and finally in $TEMP, in that order. If none of these variables are defined, Gmsh will try to save/load its configuration files from the current working directory.

General questions
=================

 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 source code.

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

     Disable opaque move in your window manager.

 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).

 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).

 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 type myfile.jpg in the dialog and Gmsh will automatically create a JPEG image file.

 6. How can I save MPEG, AVI, ..., animations?

     Using a script. Have a look at tutorial/t8.geo or demos/anim.script for some examples.

 7. Can I change values in input fields with the mouse in the GUI?

     Yes: dragging the mouse in a numeric input field slides the value! The left button moves one step per pixel, the middle by `10*step', and the right button by `100*step'.

 8. Can I copy messages to the clipboard?

     Yes: selecting the content of an input field, or lines in the message console (`Tools->Message Console'), copies the selected text to the clipboard.

Geometry module
===============

 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.

 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.).

 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. Can I edit STEP/IGES/BRep models?

     Not yet. At the moment you can only change mesh element sizes, 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.).

 5. How can I build modular geometries?

     Define common geometrical objects and options in separate files, reusable in all your problem definition structures. Then Include the files in your main project file.

Mesh module
===========

 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 file a bug report with the version of your operating system and the full geometry.

 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 mesh element sizes in your input file so that the surface mesh better matches the geometrical details of the model.

     If nothing works, file a bug report with the version of your operating system and and the full geometry.

 3. My 2D meshes of IGES files present gaps between surfaces

     IGES files do not contain the topology of the model, and tolerance problems can thus appear when the OpenCASCADE importer cannot identify two (close) curves as actually being identical.

     The best solution is to not use IGES and use STEP instead. If you really have to use IGES, check that you don't have duplicate curves (e.g. by displaying their numbers in the GUI with `Tools->Options->Geometry->Visibility->Line numbers'). If there are duplicates, try to change the geometrical tolerance and sew the faces (see options in `Tools->Options->Geometry->General').

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

     Use `Optimize quality' in the mesh menu.

 5. 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.

 6. Does Gmsh automatically couple unstructured tetrahedral meshes and structured hexahedral meshed using pyramids?

     No. We need your help to implement this.

 7. 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.

 8. 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).

 9. Does Gmsh support curved elements?

     Yes, Gmsh can generate both 1st order and 2nd order elements. To generate second order elements, click on `High 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.

 10. 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.

 11. 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.

 12. How can I display only the mesh associated with selected geometrical entities?

     See ``How can I display only selected parts of my model?''.

 13. 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.

 14. 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.

 15. 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'.

Solver module
=============

 1. How do I integrate my own solver with Gmsh?

     Gmsh uses the ONELAB interface (http://www.onelab.info) to interact with external solvers. Have a look at the GetDP finite element solver (http://geuz.org/getdp) to see how this is done.

 2. 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 ``How do I integrate my own solver with Gmsh?'' 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.

Post-processing module
======================

 1. How do I compute a section of a plot?

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

 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.

 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).

 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.

 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.

 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. 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'.

 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.

 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.

 10. Is there a way to visualize only certain components of vector/tensor fields?

     Yes, by using either the ``Force field'' options in `Tools->Options->View->Visibility', or by using `Tools->Plugins->MathEval'.

 11. Can I do arithmetic operations on a view? Can I perform operations involving different views?

     Yes, with the Evaluate plugin.

 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. In 3D you can use Plugin(Tetrahedralize).

       * 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.

 13. How can I see ``inside'' a complicated post-processing view?

     Use `Tools->Clipping Planes'.

     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.

 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'.

Version history
***************

     [file VERSIONS.txt not included]

Copyright and credits
*********************

     [file CREDITS.txt not included]

License
*******

     [file LICENSE.txt not included]