\input texinfo.tex @c -*-texinfo-*-
@c Gmsh - Copyright (C) 1997-2018 C. Geuzaine, J.-F. Remacle
@c
@c See the LICENSE.txt file for license information. Please report all
@c issues on https://gitlab.onelab.info/gmsh/gmsh/issues
@c
@c =========================================================================
@c
@c This is the Gmsh documentation texinfo source file
@c
@c Things to do -> "Ctrl+s todo:"
@c
@c Indexing:
@c
@c * @cindex = concept index, e.g. "File formats"
@c * @tindex + @findex = type + function index, e.g. "Sqrt(expression)"
@c
@c Before release, run C-u C-c C-u C-a in GNU Emacs. This updates all node
@c pointers and menus.
@c
@c =========================================================================
@c %**starts of header
@setfilename gmsh.info
@set GMSH-VERSION 4.0
@set COPYRIGHT @copyright{} 1997-2018 Christophe Geuzaine, Jean-Fran@,{c}ois Remacle
@settitle Gmsh @value{GMSH-VERSION}
@footnotestyle separate
@setchapternewpage odd
@paragraphindent 0
@finalout
@c %**end of header

@c merge function index into type index
@syncodeindex fn tp

@c =========================================================================
@c Info directives
@c =========================================================================

@ifinfo
@dircategory Math
@direntry
* Gmsh: (gmsh).  3D finite element mesh generator with built-in pre- and
post-processing facilities
@end direntry
@noindent
This is the @cite{Gmsh Reference Manual} for Gmsh @value{GMSH-VERSION}
(@today{}).
@noindent
Copyright @value{COPYRIGHT}
@end ifinfo

@c =========================================================================
@c Title page
@c =========================================================================

@shorttitlepage Gmsh

@titlepage

@title Gmsh Reference Manual

@subtitle The documentation for Gmsh @value{GMSH-VERSION}
@subtitle A finite element mesh generator with built-in pre- and post-processing facilities
@subtitle
@subtitle @today{}

@author Christophe Geuzaine
@author Jean-Fran@,{c}ois Remacle

@page
@vskip 0pt plus 1filll
Copyright @value{COPYRIGHT}
@sp 1
Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on
all copies.

@end titlepage

@c =========================================================================
@c Table of contents
@c =========================================================================

@ifnothtml
@summarycontents
@end ifnothtml
@contents

@c =========================================================================
@c Top node (for all output, except TeX)
@c =========================================================================

@ifnottex
@node Top, Obtaining Gmsh, (dir), (dir)
@top Gmsh

Christophe Geuzaine and Jean-Fran@,{c}ois Remacle

Gmsh is an automatic 3D finite element mesh generator with build-in pre-
and post-processing facilities. This is the @cite{Gmsh Reference Manual}
for Gmsh @value{GMSH-VERSION} (@today{}).
@end ifnottex

@c =========================================================================
@c Master menu
@c =========================================================================

@menu
* Obtaining Gmsh::              Where to get your copy of Gmsh
* Copying conditions::          Terms and conditions of use
* Overview::                    What is Gmsh?
* How to read this manual?::    Which parts of this manual should you read (if any)?
* Running Gmsh on your system::  How can you run Gmsh on your machine?
* General tools::               Description of general commands and options
* Geometry module::             Description of all Geometry commands
* Mesh module::                 Description of all Mesh commands
* Solver module::               Description of all Solver commands
* Post-processing module::      Description of all Post-Processing commands
* File formats::                Input and output file formats
* Tutorial::                    A step-by-step tutorial
* Options::                     List of all available options
* Compiling the source code::   Information on how to comile Gmsh from source
* Gmsh API::                    Gmsh Application Programming Interface
* Information for developers::  Information for Gmsh developers
* Frequently asked questions::  The Gmsh FAQ
* Version history::             Changelog
* Copyright and credits::       Copyright information and list of contributors
* License::                     Complete copy of the license
* Concept index::               Index of concepts
* Syntax index::                Index of reserved keywords in the Gmsh language
@end menu

@c =========================================================================
@c Obtaining Gmsh
@c =========================================================================

@node Obtaining Gmsh, Copying conditions, Top, Top
@unnumbered Obtaining Gmsh

@cindex Web site
@cindex Internet address
@cindex Download

The source code and various pre-compiled versions of Gmsh (for Windows,
Mac and Unix) can be downloaded from @uref{http://gmsh.info}.
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, @emph{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
@uref{http://gmsh.info}.

@c =========================================================================
@c Copying Conditions
@c =========================================================================

@node Copying conditions, Overview, Obtaining Gmsh, Top
@unnumbered Copying conditions

@cindex Copyright
@cindex License

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 (@pxref{License}). Further
information about this license is available from the GNU Project webpage
@uref{http://www.gnu.org/copyleft/gpl-faq.html}.  Detailed copyright
information can be found in @ref{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 @uref{http://geuz.org, contact us
directly} for more information.

@c =========================================================================
@c Overview
@c =========================================================================

@node Overview, How to read this manual?, Copying conditions, Top
@chapter Overview

@cindex Introduction
@cindex 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
programming API is also available, for integrating Gmsh as a library in
your own C++, C, Python or Julia code: see @ref{Gmsh API}. A brief
description of the four modules is given hereafter.

@menu
* Geometry::
* Mesh::
* Solver::
* Post-processing::
* What Gmsh is pretty good at::
* and what Gmsh is not so good at::
* Bug reports::
@end menu

@c -------------------------------------------------------------------------
@c Geometry: geometrical entity definition
@c -------------------------------------------------------------------------

@node Geometry, Mesh, Overview, Overview
@section 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 curves (line segments, circles, ellipses, splines, @dots{}),
oriented surfaces (plane surfaces, surfaces, triangulated
surfaces, @dots{}) 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.

@c -------------------------------------------------------------------------
@c Mesh: finite element mesh generation
@c -------------------------------------------------------------------------

@node Mesh, Solver, Geometry, Overview
@section 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: curves are discretized first; the mesh of the curves
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 node 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 curve. But this also implies that the
discretization of an ``isolated'' (@var{n}-1)-th dimensional entity
inside an @var{n}-th dimensional entity does @emph{not} constrain the
@var{n}-th dimensional mesh---unless it is explicitly told to do so
(@pxref{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
@footnote{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.}.

@c -------------------------------------------------------------------------
@c Solver: external solver interface
@c -------------------------------------------------------------------------

@node Solver, Post-processing, Mesh, Overview
@section 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
(@uref{http://getdp.info}). Examples on how to interface other solvers
are available in the source distribution (in the
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/utils/solvers,utils/solvers}
directory).

@c -------------------------------------------------------------------------
@c Post-processing: scalar, vector and tensor field visualization
@c -------------------------------------------------------------------------

@node Post-processing, What Gmsh is pretty good at, Solver, Overview
@section 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 curves/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.

@c -------------------------------------------------------------------------
@c What Gmsh is pretty good at...
@c -------------------------------------------------------------------------

@node What Gmsh is pretty good at, and what Gmsh is not so good at, Post-processing, Overview
@section What Gmsh is pretty good at @dots{}

Here is a tentative list of what Gmsh does best:

@itemize @bullet
@item
quickly describe simple and/or ``repetitive'' geometries, thanks to
user-defined macros, loops, conditionals and includes (see
@ref{User-defined macros}, @ref{Loops and conditionals}, and @ref{General
commands});
@item
parametrize these geometries. Gmsh's scripting language enables all
commands and command arguments to depend on previous calculations (see
@ref{Expressions}, and @ref{Geometry commands}). Using the OpenCASCADE
geometry kernel, Gmsh gives access to all usual constructive solid
geometry operations;
@item
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 @ref{Mesh module});
@item
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 (@pxref{Mesh commands});
@item
create simple extruded geometries and meshes (see @ref{Geometry commands},
and @ref{Mesh commands});
@item
interact with external solvers through a simple client-server
architecture (@pxref{Solver module});
@item
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
(@pxref{Post-processing module}), can export plots in many different
formats (@pxref{General options list}), and can generate complex
animations (see @ref{General tools}, and @ref{t8.geo});
@item
run on low end machines and/or machines with no graphical
interface. Gmsh can be compiled with or without the GUI
(@pxref{Compiling the source code}), and all versions can be used either
interactively or directly from the command line (@pxref{Running Gmsh on
your system});
@item
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
@ref{Running Gmsh on your system} and @ref{Options});
@item
and do all the above on various platforms (Windows, Mac and Unix), for
free (@pxref{Copying conditions}), using simple script files and/or a
small but powerful GUI.
@end itemize

@c -------------------------------------------------------------------------
@c ... and what Gmsh is not so good at
@c -------------------------------------------------------------------------

@node and what Gmsh is not so good at, Bug reports, What Gmsh is pretty good at, Overview
@section @dots{} and what Gmsh is not so good at

Here are some known weaknesses of Gmsh:

@itemize @bullet
@item
Gmsh is not a multi-bloc mesh generator: all meshes produced by Gmsh are
conforming in the sense of finite element meshes;
@item
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).
@item
Gmsh's scripting language is quite limited, providing only very crude
loop controls and user-defined macros, with no local variables. For more
complex workflows, or for integrating Gmsh as a library directly in
other software tools, an application programming interface is available
(@pxref{Gmsh API}). This allows to directly access Gmsh features from
C++, C, Python or Julia. The C interface makes it relatively easy to
build interfaces to additional languages (e.g. Javascript, Java or Go).
@end itemize

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

@c -------------------------------------------------------------------------
@c Bug reports
@c -------------------------------------------------------------------------

@node Bug reports,  , and what Gmsh is not so good at, Overview
@section Bug reports

@cindex Bugs, reporting
@cindex Reporting bugs
@cindex Contact information
@cindex Mailing list
@cindex Authors, e-mail
@cindex E-mail, authors

If you think you have found a bug in Gmsh, please file an issue on
@url{https://gitlab.onelab.info/gmsh/gmsh/issues}. Please provided 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 (@pxref{Command-line
options} to see how to get this information).

See @ref{Frequently asked questions}, and the
@url{https://gitlab.onelab.info/gmsh/gmsh/issues,bug tracking system} to
see which problems we already know about.

@c =========================================================================
@c How to read this manual?
@c =========================================================================

@node How to read this manual?, Running Gmsh on your system, Overview, Top
@chapter How to read this reference manual?

Gmsh can be used at three levels:

@enumerate
@item
as a stand-alone graphical program, driven by an interactive graphical
user interface (GUI);
@item
as a stand-alone script-driven program;
@item
as a library.
@end enumerate

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 (@pxref{Running Gmsh on your system}) to learn how to
launch Gmsh on your system, then go experiment with the GUI and the
tutorial files (@pxref{Tutorial}) provided in the distribution.
Screencasts that show how to use the GUI are available here:
@uref{http://gmsh.info/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 @file{.geo} extension for geometry scripts,
and the @file{.pos} extension for parsed post-processing datasets. Once
you master the tutorial (read the source files: they are heavily
commented!), start reading chapter @ref{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 (@pxref{File formats}),
Gmsh can read/write many standard mesh files, depending on how it was
built: check the `File->Export' 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 Gmsh Application
Programming Interface (API). This API is available in C++, C, Python and
Julia: see @ref{Gmsh API} for more information.

@c -------------------------------------------------------------------------
@c Syntactic rules used in the manual
@c -------------------------------------------------------------------------

@menu
* Syntactic rules::
@end menu

@node Syntactic rules,  , How to read this manual?, How to read this manual?
@section Syntactic rules used in the manual

@cindex Syntax, rules
@cindex Rules, syntactic
@cindex Document syntax

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

@enumerate
@item
Keywords and literal symbols are printed like @code{this}.
@item
Metasyntactic variables (i.e., text bits that are not part of the syntax,
but stand for other text bits) are printed like @var{this}.
@item
A colon (@code{:}) after a metasyntactic variable separates the variable
from its definition.
@item
Optional rules are enclosed in @code{<} @code{>} pairs.
@item
Multiple choices are separated by @code{|}.
@item
Three dots (@dots{}) indicate a possible (multiple) repetition of the
preceding rule.
@end enumerate

@c =========================================================================
@c Running Gmsh on your system
@c =========================================================================

@node Running Gmsh on your system, General tools, How to read this manual?, Top
@chapter Running Gmsh on your system

@cindex Operating system
@cindex Running Gmsh

@menu
* Interactive mode::
* Non-interactive mode::
* Command-line options::
* Mouse actions::
* Keyboard shortcuts::
@end menu

@c -------------------------------------------------------------------------
@c Interactive mode
@c -------------------------------------------------------------------------

@node Interactive mode, Non-interactive mode, Running Gmsh on your system, Running Gmsh on your system
@section Interactive mode

@cindex Interactive mode

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

@example
> gmsh
@end example

@noindent 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 (@pxref{Tutorial}), select the
`File->Open' menu, and choose
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t1.geo,t1.geo}. When
using a terminal, you can specify the file name directly on the command
line, i.e.:

@example
> gmsh t1.geo
@end example

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
curves; `2D' will mesh all the surfaces---as well as all the curves 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->Export' 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@footnote{Nearly all the
interactive commands have keyboard shortcuts: see @ref{Keyboard
shortcuts}, or select `Help->Keyboard and Mouse Usage' in the menu. For
example, to quickly save a mesh, you can press @kbd{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 @kbd{e} to finish the selection (or
@kbd{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 curves,
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
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/view1.pos,view1.pos}
and
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/view5.msh,view5.msh}
together with the geometry of the first tutorial @ref{t1.geo}, you can
type the following command:

@example
> gmsh t1.geo view1.pos view5.msh
@end example

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 @file{.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->Export'.

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


@c -------------------------------------------------------------------------
@c Non-interactive mode
@c -------------------------------------------------------------------------

@node Non-interactive mode, Command-line options, Interactive mode, Running Gmsh on your system
@section Non-interactive mode

@cindex Non-interactive mode

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

@example
> gmsh t1.geo -2
@end example

To mesh the same example, but with the background mesh available in the
file
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/bgmesh.pos,bgmesh.pos},
type:

@example
> gmsh t1.geo -2 -bgm bgmesh.pos
@end example

For the list of all command-line options, see @ref{Command-line
options}. In particular, any complicated workflow can be written in a
@code{.geo} file, and this file can be executed as a script using

@example
> gmsh script.geo -
@end example

The script can contain e.g. meshing commands, like @code{Mesh 3;}.

@c -------------------------------------------------------------------------
@c Command-line options
@c -------------------------------------------------------------------------

@node Command-line options, Mouse actions, Non-interactive mode, Running Gmsh on your system
@section Command-line options

@cindex Command-line options
@cindex Options, command-line

@include commandline.texi

@c -------------------------------------------------------------------------
@c Mouse actions
@c -------------------------------------------------------------------------

@node Mouse actions, Keyboard shortcuts, Command-line options, Running Gmsh on your system
@section Mouse actions

@cindex Mouse, actions
@cindex Bindings, mouse

@include mouse.texi

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.

@c -------------------------------------------------------------------------
@c Keyboard shortcuts
@c -------------------------------------------------------------------------

@node Keyboard shortcuts,  , Mouse actions, Running Gmsh on your system
@section Keyboard shortcuts

@cindex Keyboard, shortcuts
@cindex Shortcuts, keyboard
@cindex Bindings, keyboard

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

@include shortcuts.texi

@c =========================================================================
@c General tools
@c =========================================================================

@node General tools, Geometry module, Running Gmsh on your system, Top
@chapter 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
@ref{Geometry module}, @ref{Mesh module}, @ref{Solver module}, and
@ref{Post-processing module}, respectively.

@menu
* Comments::
* Expressions::
* Operators::
* Built-in functions::
* User-defined macros::
* Loops and conditionals::
* General commands::
* General options::
@end menu

@c -------------------------------------------------------------------------
@c Comments
@c -------------------------------------------------------------------------

@node Comments, Expressions, General tools, General tools
@section Comments

@cindex Comments
@cindex File, comments

@findex /*, */
@findex //

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

@enumerate
@item
any text comprised between @code{/*} and @code{*/} pairs is ignored;
@item
the rest of a line after a double slash @code{//} is ignored.
@end enumerate

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.

@c -------------------------------------------------------------------------
@c Expressions
@c -------------------------------------------------------------------------

@node Expressions, Operators, Comments, General tools
@section Expressions

@cindex Expressions, definition
@cindex Constants

The two constant types used in Gmsh scripts are @var{real} and
@var{string} (there is no integer type).  These types have the same
meaning and syntax as in the C or C++ programming languages.

@menu
* Floating point expressions::
* Character expressions::
* Color expressions::
@end menu

@c .........................................................................
@c Floating point expressions
@c .........................................................................

@node Floating point expressions, Character expressions, Expressions, Expressions
@subsection Floating point expressions

@cindex Expressions, floating point
@cindex Real numbers
@cindex Numbers, real
@cindex Floating point numbers

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

@example
@var{expression}:
  @var{real} |
  @var{string} |
  @var{string} ~ @{ @var{expression} @}
  @var{string} [ @var{expression} ] |
  # @var{string} [ ] |
  ( @var{expression} ) |
  @var{operator-unary-left} @var{expression} |
  @var{expression} @var{operator-unary-right} |
  @var{expression} @var{operator-binary} @var{expression} |
  @var{expression} @var{operator-ternary-left} @var{expression} @var{operator-ternary-right} @var{expression} |
  @var{built-in-function} |
  @var{real-option} |
  Find(@var{expression-list-item}, @var{expression-list-item}) |
  StrFind(@var{char-expression}, @var{char-expression}) |
  StrCmp(@var{char-expression}, @var{char-expression}) |
  StrLen(@var{char-expression}) |
  TextAttributes(@var{char-expression}<,@var{char-expression}@dots{}>) |
  Exists(@var{string}) | Exists(@var{string}~@{ @var{expression} @}) |
  FileExists(@var{char-expression}) |
  StringToName(@var{char-expression}) | S2N(@var{char-expression}) |
  GetNumber(@var{char-expression} <,@var{expression}>) |
  GetValue("@var{string}", @var{expression}) |
  DefineNumber(@var{expression}, @var{onelab-options})
@end example

Such @w{@var{expression}s} are used in most of Gmsh's scripting
commands. When @code{~@{@var{expression}@}} is appended to a string
@var{string}, the result is a new string formed by the concatenation of
@var{string}, @code{_} (an underscore) and the value of the
@var{expression}. This is most useful in loops (@pxref{Loops and
conditionals}), where it permits to define unique strings
automatically. For example,
@example
For i In @{1:3@}
  x~@{i@} = i;
EndFor
@end example
is the same as
@example
x_1 = 1;
x_2 = 2;
x_3 = 3;
@end example

The brackets @code{[]} permit to extract one item from a list
(parentheses can also be used instead of brackets). The @code{#} permits
to get the size of a list. The operators @var{operator-unary-left},
@var{operator-unary-right}, @var{operator-binary},
@var{operator-ternary-left} and @var{operator-ternary-right} are defined
in @ref{Operators}. For the definition of @w{@var{built-in-function}s},
see @ref{Built-in functions}. The various @w{@var{real-option}s} are
listed in @ref{Options}.  @code{Find} searches for occurrences of the
first expression in the second (both of which can be lists).
@code{StrFind} searches the first @var{char-expression} for any
occurrence of the second @var{char-expression}. @code{StrCmp} compares
the two strings (returns an integer greater than, equal to, or less than
0, according as the first string is greater than, equal to, or less than
the second string). @code{StrCmp} returns the length of the
string. @code{TextAttributes} creates attributes for text
strings. @code{Exists} checks if a variable with the given name exists
(i.e., has been defined previously), and @code{FileExists} checks if the
file with the given name exists.  @code{StringToName} creates a name
from the provided string.  @code{GetNumber} allows to get the value of a
ONELAB variable (the optional second argument is the default value
returned if the variable does not exist). @code{GetValue} allows to ask
the user for a value interactively (the second argument is the value
returned in non-interactive mode). For example, inserting
@code{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 @code{General.NoPopup} is set
(@pxref{General options list}), no question is asked and the default
value is automatically used.

@code{DefineNumber} allows to define a ONELAB variable in-line. The
@var{expression} given as the first argument is the default value; this
is followed by the various ONELAB options. See
@uref{https://gitlab.onelab.info/doc/tutorials/wikis/ONELAB-syntax-for-Gmsh-and-GetDP}
for more information.

@cindex Expressions, lists

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

@example
@var{expression-list}:
  @var{expression-list-item} <, @var{expression-list-item}> @dots{}
@end example

@noindent with

@example
@var{expression-list-item}:
  @var{expression} |
  @var{expression} : @var{expression} |
  @var{expression} : @var{expression} : @var{expression} |
  @var{string} [ ] |  @var{string} ( ) |
  List [ @var{string} ] |
  List [ @var{expression-list-item} ] |
  List [ @{ @var{expression-list} @} ] |
  Unique [ @var{expression-list-item} ] |
  Abs [ @var{expression-list-item} ] |
  ListFromFile [ @var{expression-char} ] |
  LinSpace[ @var{expression}, @var{expression}, @var{expression} ] |
  LogSpace[ @var{expression}, @var{expression}, @var{expression} ] |
  @var{string} [ @{ @var{expression-list} @} ] |
  Point @{ @var{expression} @} |
  @var{transform} |
  @var{extrude} |
  @var{boolean} |
  Point|Curve|Surface|Volume In BoundingBox @{ @var{expression-list} @} |
  BoundingBox Point|Curve|Surface|Volume @{ @var{expression-list} @}
  Point @{ @var{expression} @} |
  Physical Point|Curve|Surface|Volume @{ @var{expression-list} @} |
  <Physical> Point|Curve|Surface|Volume @{ : @} |
@c  @var{duplicata} - already implemented: should we explain this?
@end example

The second case in this last definition permits to create a list
containing the range of numbers comprised between two
@w{@var{expression}s}, with a unit incrementation step. The third case
also permits to create a list containing the range of numbers comprised
between two @w{@var{expression}s}, but with a positive or negative
incrementation step equal to the third @var{expression}. The fourth,
fifth and sixth cases permit to reference an expression list
(parentheses can also be used instead of brackets).  @code{Unique} sorts
the entries in the list and removes all duplicates.  @code{Abs} takes
the absolute value of all entries in the list. @code{ListFromFile} reads
a list of numbers from a file. @code{LinSpace} and @code{LogSpace}
construct lists using linear or logarithmic spacing. The next two cases
permit to reference an expression sublist (whose elements are those
corresponding to the indices provided by the @var{expression-list}).
The next cases permit to retrieve the indices of entities created
through geometrical transformations, extrusions and boolean operations
(see @ref{Transformations}, @ref{Extrusions} and @ref{Boolean
operations}). The next two cases allow to retrieve entities in a given
bounding box, or get the bounding box of a given entity. The last three
cases permit to retrieve the coordinates of a given geometry point
(@pxref{Points}), to retrieve the elementary entities making up physical
groups, and to retrieve the tags of all (physical or elementary) points,
curves, surfaces or volumes in the model,

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

For some commands it makes sense to specify all the possible expressions
in a list. This is achieved with @var{expression-list-or-all}, defined
as:

@example
@var{expression-list-or-all}:
  @var{expression-list} | :
@end example

The meaning of ``all'' (@code{:}) depends on context. For example,
@code{Curve @{ : @}} will get the ids of all the existing curves in the
model, while @code{Surface @{ : @}} will get the ids of all existing
surfaces.

@c .........................................................................
@c Character expressions
@c .........................................................................

@node Character expressions, Color expressions, Floating point expressions, Expressions
@subsection Character expressions

@cindex Expressions, character
@cindex Strings

Character expressions are defined as:

@example
@var{char-expression}:
  "@var{string}" |
  @var{string} | @var{string}[ @var{expression} ] |
  Today | OnelabAction | GmshExecutableName |
  CurrentDirectory | CurrentDir
  StrPrefix ( @var{char-expression} ) |
  StrRelative ( @var{char-expression} ) |
  StrCat ( @var{char-expression} <,@dots{}> ) |
  Str ( @var{char-expression} <,@dots{}> ) |
  StrChoice ( @var{expression}, @var{char-expression}, @var{char-expression} ) |
  StrSub( @var{char-expression}, @var{expression}, @var{expression} ) |
  StrSub( @var{char-expression}, @var{expression} ) |
  UpperCase ( @var{char-expression} ) |
  AbsolutePath ( @var{char-expression} ) |
  DirName ( @var{char-expression} ) |
  Sprintf ( @var{char-expression} , @var{expression-list} ) |
  Sprintf ( @var{char-expression} ) |
  Sprintf ( @var{char-option} ) |
  GetEnv ( @var{char-expression} ) |
  GetString ( @var{char-expression} <,@var{char-expression}>) |
  GetStringValue ( @var{char-expression} , @var{char-expression} ) |
  StrReplace ( @var{char-expression} , @var{char-expression} , @var{char-expression} )
  NameToString ( @var{string} ) | N2S ( @var{string} ) |
  DefineString(@var{char-expression}, @var{onelab-options})
@end example

@code{Today} returns the current date. @code{OnelabAction} returns the
current ONELAB action (e.g. @code{check} or
@code{compute}). @code{GmshExecutableName} returns the full path of the
Gmsh executable.  @code{CurrentDirectory} and @code{CurrentDir} return
the directory of the @code{.geo} file.  @code{StrPrefix} and
@code{StrRelative} permit to take the prefix (e.g. to remove the
extension) or the relative path of a file name. @code{StrCat} and
@code{Str} permit to concatenate character expressions (@code{Str} adds
a newline character after each string except the last).
@code{StrChoice} returns the first or second @var{char-expression}
depending on the value of @var{expression}.  @code{StrSub} returns the
portion of the string that starts at the character position given by the
first @var{expression} and spans the number of characters given by the
second @var{expression} or until the end of the string (whichever comes
first; or always if the second @var{expression} is not
provided). @code{UpperCase} converts the @var{char-expression} to upper
case. @code{AbsolutePath} returns the absolute path of a
file. @code{DirName} returns the directory of a file.  @code{Sprintf} is
equivalent to the @code{sprintf} C function (where @var{char-expression}
is a format string that can contain floating point formatting
characters: @code{%e}, @code{%g}, etc.) The various
@w{@var{char-option}s} are listed in @ref{Options}. @code{GetEnvThe}
gets the value of an environment variable from the operating
system. @code{GetString} allows to get a ONELAB string value (the second
optional argument is the default value returned if the variable does not
exist).  @code{GetStringValue} asks the user for a value interactively
(the second argument is the value used in non-interactive
mode). @code{StrReplace}'s arguments are: input string, old substring,
new substring (brackets can be used instead of parentheses in @code{Str}
and @code{Sprintf}). @code{NameToString} converts a variable name into a
string.

@code{DefineString} allows to define a ONELAB variable in-line. The
@var{char-expression} given as the first argument is the default value;
this is followed by the various ONELAB options. See
@uref{https://gitlab.onelab.info/doc/tutorial/wikis/ONELAB-syntax-for-Gmsh-and-GetDP}
for more information.

Character expressions are mostly used to specify non-numeric options and
input/output file names. See @ref{t8.geo}, for an interesting usage of
@w{@var{char-expression}s} in an animation script.

List of character expressions are defined as:

@example
@var{char-expression-list}:
  @var{char-expression} <,@dots{}>
@end example


@c .........................................................................
@c Color expressions
@c .........................................................................

@node Color expressions,  , Character expressions, Expressions
@subsection Color expressions

@cindex Expressions, color
@cindex Colors

Colors expressions are hybrids between fixed-length braced
@w{@var{expression-list}s} and @w{@var{string}s}:

@example
@var{color-expression}:
  @var{char-expression} |
  @{ @var{expression}, @var{expression}, @var{expression} @} |
  @{ @var{expression}, @var{expression}, @var{expression}, @var{expression} @} |
  @var{color-option}
@end example

@noindent The first case permits to use the X Windows names to refer to colors,
e.g., @code{Red}, @code{SpringGreen}, @code{LavenderBlush3}, @dots{}
(see
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Common/Colors.h,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 @var{color-option} as a @var{color-expression}. The
various @w{@var{color-option}s} are listed in @ref{Options}.

See @ref{t3.geo}, for an example of the use of color expressions.

@c -------------------------------------------------------------------------
@c Operators
@c -------------------------------------------------------------------------

@node Operators, Built-in functions, Expressions, General tools
@section Operators

@cindex Operators, definition
@cindex Unary operators
@cindex Binary operators
@cindex Ternary operators
@findex @var{operator-unary-left}
@findex @var{operator-unary-right}
@findex @var{operator-binary}
@findex @var{operator-unary-left}
@findex @var{operator-ternary-left}
@findex @var{operator-ternary-right}

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.

@noindent
@var{operator-unary-left}:
@ftable @code
@item -
Unary minus.
@item !
Logical not.
@end ftable

@noindent
@var{operator-unary-right}:
@ftable @code
@item ++
Post-incrementation.
@item --
Post-decrementation.
@end ftable

@noindent
@var{operator-binary}:
@ftable @code
@item ^
Exponentiation.
@item *
Multiplication.
@item /
Division.
@item %
Modulo.
@item +
Addition.
@item -
Subtraction.
@item ==
Equality.
@item !=
Inequality.
@item >
Greater.
@item >=
Greater or equality.
@item <
Less.
@item <=
Less or equality.
@item &&
Logical `and'.
@item ||
Logical `or'. (Warning: the logical `or' always implies the evaluation of
both arguments.  That is, unlike in C or C++, the second operand of
@code{||} is evaluated even if the first one is true).
@end ftable

@noindent
@var{operator-ternary-left}:
@ftable @code
@item ?
@end ftable
@var{operator-ternary-right}:
@ftable @code
@item :
The only ternary operator, formed by @var{operator-ternary-left} and
@var{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.
@end ftable

@cindex Evaluation order
@cindex Order, evaluation
@cindex Operator precedence
@cindex Precedence, operators

@findex ()

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

@enumerate
@item @code{()}, @code{[]}, @code{.}, @code{#}
@item @code{^}
@item @code{!}, @code{++}, @code{--}, @code{-} (unary)
@item @code{*}, @code{/}, @code{%}
@item @code{+}, @code{-}
@item @code{<}, @code{>}, @code{<=}, @code{>=}
@item @code{==}, @code{!=}
@item @code{&&}
@item @code{||}
@item @code{?:}
@item @code{=}, @code{+=}, @code{-=}, @code{*=}, @code{/=}
@end enumerate


@c -------------------------------------------------------------------------
@c Built-in functions
@c -------------------------------------------------------------------------

@node Built-in functions, User-defined macros, Operators, General tools
@section Built-in functions

@cindex Functions, built-in
@findex @var{build-in-function}

A built-in function is composed of an identifier followed by a pair of
parentheses containing an @var{expression-list}, the list of its
arguments. This list of arguments can also be provided in between
brackets, instead of parentheses. Here is the list of the built-in
functions currently implemented:

@noindent
@var{build-in-function}:

@ftable @code
@item Acos ( @var{expression} )
Arc cosine (inverse cosine) of an @var{expression} in [-1,1]. Returns a value
in [0,Pi].

@item Asin ( @var{expression} )
Arc sine (inverse sine) of an @var{expression} in [-1,1]. Returns a value in
[-Pi/2,Pi/2].

@item Atan ( @var{expression} )
Arc tangent (inverse tangent) of @var{expression}. Returns a value in
[-Pi/2,Pi/2].

@item Atan2 ( @var{expression}, @var{expression} )
Arc tangent (inverse tangent) of the first @var{expression} divided by the
second. Returns a value in [-Pi,Pi].

@item Ceil ( @var{expression} )
Rounds @var{expression} up to the nearest integer.

@item Cos ( @var{expression} )
Cosine of @var{expression}.

@item Cosh ( @var{expression} )
Hyperbolic cosine of @var{expression}.

@item Exp ( @var{expression} )
Returns the value of e (the base of natural logarithms) raised to the power
of @var{expression}.

@item Fabs ( @var{expression} )
Absolute value of @var{expression}.

@item Fmod ( @var{expression}, @var{expression} )
Remainder of the division of the first @var{expression} by the second, with
the sign of the first.

@item Floor ( @var{expression} )
Rounds @var{expression} down to the nearest integer.

@item Hypot ( @var{expression}, @var{expression} )
Returns the square root of the sum of the square of its two arguments.

@item Log ( @var{expression} )
Natural logarithm of @var{expression} (@var{expression} > 0).

@item Log10 ( @var{expression} )
Base 10 logarithm of @var{expression} (@var{expression} > 0).

@item Modulo ( @var{expression}, @var{expression} )
see @code{Fmod( @var{expression}, @var{expression} )}.

@item Rand ( @var{expression} )
Random number between zero and @var{expression}.

@item Round ( @var{expression} )
Rounds @var{expression} to the nearest integer.

@item Sqrt ( @var{expression} )
Square root of @var{expression} (@var{expression} >= 0).

@item Sin ( @var{expression} )
Sine of @var{expression}.

@item Sinh ( @var{expression} )
Hyperbolic sine of @var{expression}.

@item Tan ( @var{expression} )
Tangent of @var{expression}.

@item Tanh ( @var{expression} )
Hyperbolic tangent of @var{expression}.
@end ftable

@c -------------------------------------------------------------------------
@c User-defined macros
@c -------------------------------------------------------------------------

@node User-defined macros, Loops and conditionals, Built-in functions, General tools
@section User-defined macros

@cindex Macros, user-defined

User-defined macros take no arguments, and are evaluated as if a file
containing the macro body was included at the location of the @code{Call}
statement.

@ftable @code
@item Macro @var{string} | @var{char-expression}
Begins the declaration of a user-defined macro named @var{string}. The
body of the macro starts on the line after `@code{Macro @var{string}}',
and can contain any Gmsh command.  A synonym for @code{Macro} is
@code{Function}.

@item Return
Ends the body of the current user-defined macro. Macro declarations
cannot be imbricated.

@item Call @var{string} | @var{char-expression} ;
Executes the body of a (previously defined) macro named @var{string}.
@end ftable

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

@c -------------------------------------------------------------------------
@c Loops and conditionals
@c -------------------------------------------------------------------------

@node Loops and conditionals, General commands, User-defined macros, General tools
@section Loops and conditionals

@cindex Loops
@cindex Conditionals

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

@ftable @code
@item For ( @var{expression} : @var{expression} )
Iterates from the value of the first @var{expression} to the value of the
second @var{expression}, with a unit incrementation step. At each iteration,
the commands comprised between `@code{For ( @var{expression} :
@var{expression} )}' and the matching @code{EndFor} are executed.

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

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

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

@item EndFor
Ends a matching @code{For} command.

@item If ( @var{expression} )
The body enclosed between `@code{If ( @var{expression} )}' and the matching
@code{ElseIf}, @code{Else} or @code{EndIf}, is evaluated if @var{expression}
is non-zero.

@item ElseIf ( @var{expression} )
The body enclosed between `@code{ElseIf ( @var{expression} )}' and the next
matching @code{ElseIf}, @code{Else} or @code{EndIf}, is evaluated if
@var{expression} is non-zero and none of the @var{expression} of the
previous matching codes @code{If} and @code{ElseIf} were non-zero.

@item Else
The body enclosed between @code{Else} and the matching @code{EndIf} is evaluated
if none of the @var{expression} of the previous matching codes
@code{If} and @code{ElseIf} were non-zero.

@item EndIf
Ends a matching @code{If} command.
@end ftable

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

@c -------------------------------------------------------------------------
@c General commands
@c -------------------------------------------------------------------------

@node General commands, General options, Loops and conditionals, General tools
@section General commands

@cindex General commands
@cindex Commands, general
@cindex Expressions, affectation
@cindex Expressions, identifiers

@findex =
@findex +=
@findex -=
@findex *=
@findex /=

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

@ftable @code

@item @var{string} = @var{expression};
Creates a new expression identifier @var{string}, or affects
@var{expression} to an existing expression identifier. Thirteen expression
identifiers are predefined (hardcoded in Gmsh's parser):

@ftable @code
@item Pi
Returns 3.1415926535897932.

@item GMSH_MAJOR_VERSION
Returns Gmsh's major version number.

@item GMSH_MINOR_VERSION
Returns Gmsh's minor version number.

@item GMSH_PATCH_VERSION
Returns Gmsh's patch version number.

@item MPI_Size
Returns the number of processors on which Gmsh is running. It is always
1, except if you compiled Gmsh with @code{ENABLE_MPI}
(@pxref{Compiling the source code}).

@item MPI_Rank
Returns the rank of the current processor.

@item Cpu
Returns the current CPU time (in seconds).

@item Memory
Returns the current memory usage (in Mb).

@item TotalMemory
Returns the total memory available (in Mb).

@item newp
Returns the next available point tag. As explained in @ref{Geometry
module}, a unique tag must be associated with every geometrical point:
@code{newp} permits to know the highest tag already attributed (plus
one). This is mostly useful when writing user-defined macros
(@pxref{User-defined macros}) or general geometric primitives, when one
does not know @emph{a priori} which tags are already attributed, and
which ones are still available.

@item newl
Returns the next available curve tag.

@item news
Returns the next available surface tag.

@item newv
Returns the next available volume tag.

@item newll
Returns the next available curve loop tag.

@item newsl
Returns the next available surface loop tag.

@item newreg
Returns the next available region tag. That is, @code{newreg} returns
the maximum of @code{newp}, @code{newl}, @code{news}, @code{newv},
@code{newll}, @code{newsl} and all physical group tags@footnote{For
compatibility purposes, the behavior of @code{newl}, @code{news},
@code{newv} and @code{newreg} can be modified with the
@code{Geometry.OldNewReg} option (@pxref{Geometry options list}).}.
@end ftable

@item @var{string} = @{ @};
Creates a new expression list identifier @code{@var{string}} with an
empty list.

@item @var{string}[] = @{ @var{expression-list} @};
Creates a new expression list identifier @code{@var{string}} with the
list @var{expression-list}, or affects @var{expression-list} to an
existing expression list identifier. Parentheses are also allowed
instead of square brackets; although not recommended, brackets and
parentheses can also be completely ommitted.

@item @var{string} [ @{ @var{expression-list} @} ] = @{ @var{expression-list} @};
Affects each item in the right hand side @var{expression-list} to the
elements (indexed by the left hand side @var{expression-list}) of an
existing expression list identifier. The two @w{@var{expression-list}s}
must contain the same number of items. Parentheses can also be used
instead of brackets.

@item @var{string} += @var{expression};
Adds and affects @var{expression} to an existing expression identifier.

@item @var{string} -= @var{expression};
Subtracts and affects @var{expression} to an existing expression identifier.

@item @var{string} *= @var{expression};
Multiplies and affects @var{expression} to an existing expression identifier.

@item @var{string} /= @var{expression};
Divides and affects @var{expression} to an existing expression identifier.

@item @var{string} += @{ @var{expression-list} @};
Appends @var{expression-list} to an existing expression list or creates
a new expression list with @var{expression-list}.

@item @var{string} -= @{ @var{expression-list} @};
Removes the items in @var{expression-list} from the existing expression list.

@item @var{string} [ @{ @var{expression-list} @} ] += @{ @var{expression-list} @};
Adds and affects, item per item, the right hand side
@var{expression-list} to an existing expression list
identifier. Parentheses can also be used instead of brackets.

@item @var{string} [ @{ @var{expression-list} @} ] -= @{ @var{expression-list} @};
Subtracts and affects, item per item, the right hand side
@var{expression-list} to an existing expression list identifier.
Parentheses can also be used instead of brackets.

@item @var{string} [ @{ @var{expression-list} @} ] *= @{ @var{expression-list} @};
Multiplies and affects, item per item, the right hand side
@var{expression-list} to an existing expression list
identifier. Parentheses can also be used instead of brackets.

@item @var{string} [ @{ @var{expression-list} @} ] /= @{ @var{expression-list} @};
Divides and affects, item per item, the right hand side
@var{expression-list} to an existing expression list
identifier. Parentheses can also be used instead of brackets.

@item @var{string} = @var{char-expression};
Creates a new character expression identifier @code{@var{string}} with a
given @var{char-expression}.

@item @var{string}[] = Str( @var{char-expression-list} ) ;
Creates a new character expression list identifier @code{@var{string}}
with a given @var{char-expression-list}. Parentheses can also be used
instead of brackets.

@item @var{string}[] += Str( @var{char-expression-list} ) ;
Appends a character expression list to an existing list. Parentheses can
also be used instead of brackets.

@item DefineConstant[ @var{string} = @var{expression}|@var{char-expression} <, ...>];
Creates a new expression identifier @var{string}, with value
@var{expression}, only if has not been defined before.

@item DefineConstant[ @var{string} = @{ @var{expression}|@var{char-expression}, @var{onelab-options} @} <, ...>];
Same as the previous case, except that the variable is also exchanged
with the ONELAB database if it has not been defined before. See
@uref{https://gitlab.onelab.info/doc/tutorial/wikis/ONELAB-syntax-for-Gmsh-and-GetDP}
for more information.

@item SetNumber( @var{char-expression} , @var{expression} );
Sets the value a numeric ONELAB variable @var{char-expression}.

@item SetString( @var{char-expression} , @var{char-expression} );
Sets the value a string ONELAB variable @var{char-expression}.

@item @var{real-option} = @var{expression};
Affects @var{expression} to a real option.

@item @var{char-option} = @var{char-expression};
Affects @var{char-expression} to a character option.

@item @var{color-option} = @var{color-expression};
Affects @var{color-expression} to a color option.

@item @var{real-option} += @var{expression};
Adds and affects @var{expression} to a real option.

@item @var{real-option} -= @var{expression};
Subtracts and affects @var{expression} to a real option.

@item @var{real-option} *= @var{expression};
Multiplies and affects @var{expression} to a real option.

@item @var{real-option} /= @var{expression};
Divides and affects @var{expression} to a real option.

@item Abort;
Aborts the current script.

@item Exit;
Exits Gmsh.

@item CreateDir @var{char-expression};
Create the directory @var{char-expression}.

@item Printf ( @var{char-expression} <, @var{expression-list}> );
Prints a character expression in the information window and/or on the
terminal. @code{Printf} is equivalent to the @code{printf} C function:
@var{char-expression} is a format string that can contain formatting
characters (@code{%f}, @code{%e}, etc.). Note that all @w{@var{expression}s}
are evaluated as floating point values in Gmsh (@pxref{Expressions}), so
that only valid floating point formatting characters make sense in
@var{char-expression}. See @ref{t5.geo}, for an example of the use of
@code{Printf}.

@item Printf ( @var{char-expression} , @var{expression-list} ) > @var{char-expression};
Same as @code{Printf} above, but output the expression in a file.

@item Printf ( @var{char-expression} , @var{expression-list} ) >> @var{char-expression};
Same as @code{Printf} above, but appends the expression at the end of
the file.

@item Error ( @var{char-expression} <, @var{expression-list}> );
Same as @code{Printf}, but raises an error.

@item Merge @var{char-expression};
Merges a file named @var{char-expression}. This command is equivalent to
the `File->Merge' menu in the GUI. If the path in @var{char-expression}
is not absolute, @var{char-expression} is appended to the path of the
current file.

@item ShapeFromFile( @var{char-expression} );
Merges a BREP or STEP file and returns the tags of the
highest-dimensional entities. Only available with the OpenCASCADE
geometry kernel.

@item Draw;
Redraws the scene.

@item SetChanged;
Force the mesh and post-processing vertex arrays to be
regenerated. Useful e.g. for creating animations with changing clipping
planes, etc.

@item 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:
@enumerate
@item
If there is a mesh (i.e., at least one mesh node), the bounding
box is taken as the box enclosing all the mesh nodes;
@item
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;
@item
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.
@end enumerate

@item BoundingBox @{ @var{expression}, @var{expression}, @var{expression}, @var{expression}, @var{expression}, @var{expression} @};
Forces the bounding box of the scene to the given @w{@var{expression}s} (X
min, X max, Y min, Y max, Z min, Z max).

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

@item Delete Physicals;
Deletes all physical groups.

@item Delete Variables;
Deletes all the expressions.

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

@item Delete @var{string};
Deletes the expression @var{string}.

@item Print @var{char-expression};
Prints the graphic window in a file named @var{char-expression}, using
the current @code{Print.Format} (@pxref{General options list}). If the
path in @var{char-expression} is not absolute, @var{char-expression} is
appended to the path of the current file.

@item Sleep @var{expression};
Suspends the execution of Gmsh during @var{expression} seconds.

@item SystemCall @var{char-expression};
Executes a (blocking) system call.

@item NonBlockingSystemCall @var{char-expression};
Executes a (non-blocking) system call.

@item OnelabRun ( @var{char-expression} <, @var{char-expression} > )
Runs a ONELAB client (first argument is the client name, second optional
arguement is the command line).

@item SetName @var{char-expression};
Changes the name of the current model.

@item SetFactory(@var{char-expression});
Changes the current geometry kernel (i.e. determines the CAD kernel that
is used for all subsequent geometrical commands). Currently available
kernels: @code{"Built-in"} and @code{"OpenCASCADE"}.

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

@item NewModel;
Creates a new current model.

@item Include @var{char-expression};
Includes the file named @var{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 @var{char-expression} is not absolute, @var{char-expression} is
appended to the path of the current file.
@end ftable

@c -------------------------------------------------------------------------
@c General options
@c -------------------------------------------------------------------------

@node General options,  , General commands, General tools
@section General options

The list of all the general @w{@var{char-option}s},
@w{@var{real-option}s} and @w{@var{color-option}s} (in that
order---check the default values to see the actual types) is given in
@ref{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.

@c =========================================================================
@c Geometry module
@c =========================================================================

@node Geometry module, Mesh module, General tools, Top
@chapter Geometry module

@cindex Geometry, module
@cindex Module, geometry

Geometries can be constructed in Gmsh using different underlying CAD
kernels, specified in @code{.geo} files with the @code{SetFactory}
command.

The built-in CAD kernel (@code{SetFactory("built-in")}) provides a
simple CAD engine based on a boundary representation (``BRep'')
approach: you need to first define points (using the @code{Point}
command: see below), then curves (using @code{Line}, @code{Circle},
@code{Spline}, @dots{}, commands or by extruding points), then surfaces
(using for example the @code{Plane Surface} or @code{Surface} commands,
or by extruding curves), and finally volumes (using the @code{Volume}
command or by extruding surfaces). The OpenCASCADE CAD kernel
(@code{SetFactory("OpenCASCADE")}) uses the open source OpenCASCADE

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

@enumerate
@item each elementary point must possess a unique tag;
@item each elementary curve must possess a unique tag;
@item each elementary surface must possess a unique tag;
@item each elementary volume must possess a unique tag.
@end enumerate

@noindent Elementary geometrical entities can then be manipulated in various
ways, for example using the @code{Translate}, @code{Rotate},
@code{Scale} or @code{Symmetry} commands. They can be deleted with the
@code{Delete} command, provided that no higher-dimension entity
references them. Zero or negative tags are reserved by the system for
special uses: do not use them in your scripts.

Groups of elementary geometrical entities can also be defined and are
called ``physical'' groups. These physical groups cannot be modified
by geometry commands: their only purpose is to assemble elementary
entities into larger groups 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 curve, physical surface or physical volume must
be assigned a unique tag. See @ref{Mesh module}, for more information
about how physical groups affect the way meshes are saved.

@menu
* Geometry commands::
* Geometry options::
@end menu

@c -------------------------------------------------------------------------
@c Geometry commands
@c -------------------------------------------------------------------------

@node Geometry commands, Geometry options, Geometry module, Geometry module
@section Geometry commands

@cindex Geometry commands
@cindex Commands, geometry

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 @var{expression} defines a new entity, it
is enclosed between parentheses. If an @var{expression} refers to a
previously defined entity, it is enclosed between braces.''

@menu
* Points::
* Curves::
* Surfaces::
* Volumes::
* Extrusions::
* Boolean operations::
* Transformations::
* Miscellaneous geometry commands::
@end menu

@c .........................................................................
@c Points
@c .........................................................................

@node Points, Curves, Geometry commands, Geometry commands
@subsection Points

@cindex Elementary points
@cindex Points, elementary
@cindex Physical points
@cindex Points, physical

@ftable @code
@item Point ( @var{expression} ) = @{ @var{expression}, @var{expression}, @var{expression} <, @var{expression} > @};
Creates an elementary point. The @var{expression} inside the parentheses
is the point's tag; the three first @w{@var{expression}s} 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
@var{expression} sets the prescribed mesh element size at that
point. See @ref{Specifying mesh element sizes}, for more information
about how this value is used in the meshing process.

@item Physical Point ( @var{expression} | @var{char-expression} <, @var{expression}> ) <+|->= @{ @var{expression-list} @};
Creates a physical point. The @var{expression} inside the parentheses is
the physical point's tag; the @var{expression-list} on the right hand
side should contain the tags of all the elementary points that need to
be grouped inside the physical point.  If a @var{char-expression} is
given instead instead of @var{expression} inside the parentheses, a
string label is associated with the physical tag, which can be either
provided explicitly (after the comma) or not (in which case a unique
tag is automatically created).

@end ftable

@c .........................................................................
@c Curves
@c .........................................................................

@node Curves, Surfaces, Points, Geometry commands
@subsection Curves

@cindex Elementary curves
@cindex Curves, elementary
@cindex Physical curves
@cindex Curves, physical
@cindex Lines

@ftable @code
@item Line ( @var{expression} ) = @{ @var{expression}, @var{expression} @};
Creates a straight line segment. The @var{expression} inside the
parentheses is the line segment's tag; the two @w{@var{expression}s}
inside the braces on the right hand side give tags of the start and end
points of the segment.
@c todo: multi-lines not authorized yet

@item Bezier ( @var{expression} ) = @{ @var{expression-list} @};
Creates a Bezier curve. The @var{expression-list} contains the
tags of the control points.

@item BSpline ( @var{expression} ) = @{ @var{expression-list} @};
Creates a cubic BSpline. The @var{expression-list} contains the tags of
the control points. Creates a periodic curve if the first and last
points are identical.

@item Spline ( @var{expression} ) = @{ @var{expression-list} @};
Creates a spline going through the points in @var{expression-list}. With
the built-in geometry kernel this constructs a Catmull-Rom spline. With
the OpenCASCADE kernel, this constructs a C2 BSpline. Creates a periodic
curve if the first and last points are identical.

@item Circle ( @var{expression} ) = @{ @var{expression}, @var{expression}, @var{expression} <, ...> @};
Creates a circle arc. The three @var{expression}s on the right-hand-side
define the start point, the center and the end point of the arc. With
the built-in geometry kernel the arc should be strictly smaller than Pi.
With the OpenCASCADE kernel additional @var{expression}s can be provided
to define a full circle (4th expression is the radius) or a circle arc
between two angles (next 2 expressions).
@c todo: document < Plane @{ @var{expression}, @var{expression}, @var{expression} @}; >

@item Ellipse ( @var{expression} ) = @{ @var{expression}, @var{expression}, @var{expression}, @var{expression} <, ...> @};
Creates an ellipse arc. The four @var{expression}s on the
right-hand-side define the start point, the center point, a major axis
point and the end point of the ellipse. The third point can be omitted
with the OpenCASCADE kernel. With the OpenCASCADE kernel additional
@var{expression}s can be provided to define a full ellipse (4th and 5th
expressions define the radii along X and Y) or en ellipse arc (next 2
expressions).

@item Curve Loop ( @var{expression} ) = @{ @var{expression-list} @};
Creates an oriented loop of curves, i.e. a closed wire. The
@var{expression} inside the parentheses is the curve loop's tag; the
@var{expression-list} on the right hand side should contain the tags of
all the elementary curves that constitute the curve loop. A curve loop must
be a closed loop, and the elementary curves should be ordered and
oriented (using negative tags 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 curve loops (or
subloops) in a single @code{Curve Loop} command. (Curve loops are used
to create surfaces: see @ref{Surfaces}.)

@item Wire ( @var{expression} ) = @{ @var{expression-list} @};
Creates a path made of curves. Wires are only available with the
OpenCASCADE kernel. They are used to create @code{ThruSections} and
extrusions along paths.

@item Physical Curve ( @var{expression} | @var{char-expression} <, @var{expression}> ) <+|->= @{ @var{expression-list} @};
Creates a physical curve. The @var{expression} inside the parentheses is
the physical curve's tag; the @var{expression-list} on the right hand
side should contain the tags of all the elementary curves that need to be
grouped inside the physical curve. If a @var{char-expression} is given
instead instead of @var{expression} inside the parentheses, a string
label is associated with the physical tag, which can be either provided
explicitly (after the comma) or not (in which case a unique tag is
automatically created). Specifying negative tags in the
@var{expression-list} will reverse the orientation of the mesh elements
belonging to the corresponding elementary curves in the saved mesh file.

@end ftable

@c .........................................................................
@c Surfaces
@c .........................................................................

@node Surfaces, Volumes, Curves, Geometry commands
@subsection Surfaces

@cindex Elementary surfaces
@cindex Surfaces, elementary
@cindex Physical surfaces
@cindex Surfaces, physical

@ftable @code
@item Plane Surface ( @var{expression} ) = @{ @var{expression-list} @};
Creates a plane surface. The @var{expression} inside the parentheses is
the plane surface's tag; the @var{expression-list} on the right hand
side should contain the tags of all the curve loops defining the
surface. The first curve loop defines the exterior boundary of the
surface; all other curve loops define holes in the surface.  A curve loop
defining a hole should not have any curves in common with the exterior
curve loop (in which case it is not a hole, and the two surfaces should
be defined separately). Likewise, a curve loop defining a hole should not
have any curves in common with another curve loop defining a hole in the
same surface (in which case the two curve loops should be combined).

@item Surface ( @var{expression} ) = @{ @var{expression-list} @} < In Sphere @{ @var{expression} @} >;
Creates a surface filling. With the built-in kernel, the first curve loop
should be composed of either three or four elementary curves. With the
built-in kernel, the optional @code{In Sphere} argument forces the
surface to be a spherical patch (the extra parameter gives the
tag of the center of the sphere).

@item Disk ( @var{expression} ) = @{ @var{expression-list} @};
Creates a disk. When four expressions are provided on the right hand
side (3 coordinates of the center and the radius), the disk is circular.
A fifth expression defines the radius along Y, leading to an ellipse.
@code{Disk} is only available with the OpenCASCADE kernel.

@item Rectangle ( @var{expression} ) = @{ @var{expression-list} @};
Creates a rectangle. The 3 first expressions define the lower-left
corner; the next 2 define the width and height. If a 6th expression is
provided, it defines a radius to round the rectangle
corners. @code{Rectangle} is only available with the OpenCASCADE kernel.

@item Surface Loop ( @var{expression} ) = @{ @var{expression-list} @};
Creates a surface loop (a shell). The @var{expression} inside the
parentheses is the surface loop's tag; the @var{expression-list} on the
right hand side should contain the tags 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 tags to specify reverse
orientation). (Surface loops are used to create volumes: see
@ref{Volumes}.)

@item Physical Surface ( @var{expression} | @var{char-expression} <, @var{expression}> ) <+|->= @{ @var{expression-list} @};
Creates a physical surface. The @var{expression} inside the parentheses
is the physical surface's tag; the
@var{expression-list} on the right hand side should contain the
tags of all the elementary surfaces that need to be
grouped inside the physical surface.  If a @var{char-expression} is
given instead instead of @var{expression} inside the parentheses, a
string label is associated with the physical tag,
which can be either provided explicitly (after the comma) or not (in
which case a unique tag is automatically created).
Specifying negative tags in the @var{expression-list}
will reverse the orientation of the mesh elements belonging to the
corresponding elementary surfaces in the saved mesh file.

@end ftable

@c .........................................................................
@c Volumes
@c .........................................................................

@node Volumes, Extrusions, Surfaces, Geometry commands
@subsection Volumes

@cindex Elementary volumes
@cindex Volumes, elementary
@cindex Physical volumes
@cindex Volumes, physical

@ftable @code
@item Volume ( @var{expression} ) = @{ @var{expression-list} @};
Creates a volume. The @var{expression} inside the parentheses is the
volume's tag; the @var{expression-list} on the right hand
side should contain the tags 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).

@item Sphere ( @var{expression} ) = @{ @var{expression-list} @};
Creates a sphere, defined by the 3 coordinates of its center and a
radius. Additional expressions define 3 angle limits. @code{Sphere} is
only available with the OpenCASCADE kernel.

@item Box ( @var{expression} ) = @{ @var{expression-list} @};
Creates a box, defined by the 3 coordinates of a point and the 3
extents. @code{Box} is only available with the OpenCASCADE kernel.

@item Cylinder ( @var{expression} ) = @{ @var{expression-list} @};
Creates a cylinder, defined by the 3 coordinates of the center of the
first circular face, the 3 components of the vector defining its axis
and its radius. An additional expression defines the angular
opening. @code{Cylinder} is only available with the OpenCASCADE kernel.

@item Torus ( @var{expression} ) = @{ @var{expression-list} @};
Creates a torus, defined by the 3 coordinates of its center and 2 radii.
An additional expression defines the angular opening. @code{Torus} is
only available with the OpenCASCADE kernel.

@item Cone ( @var{expression} ) = @{ @var{expression-list} @};
Creates a cone, defined by the 3 coordinates of the center of the first
circular face, the 3 components of the vector defining its axis and the
two radii of the faces (these radii can be zero). An additional
expression defines the angular opening. @code{Cone} is only available
with the OpenCASCADE kernel.

@item Wedge ( @var{expression} ) = @{ @var{expression-list} @};
Creates a right angular wedge, defined by the 3 coordinates of the
right-angle point and the 3 extends. An additional parameter defines the
top X extent (zero by default). @code{Wedge} is only available with the
OpenCASCADE kernel.

@item ThruSections ( @var{expression} ) = @{ @var{expression-list} @};
Creates a volume defined through curve loops. @code{ThruSections} is only
available with the OpenCASCADE kernel.

@item Ruled ThruSections ( @var{expression} ) = @{ @var{expression-list} @};
Same as @code{ThruSections}, but the surfaces created on the boundary
are forced to be ruled. @code{Ruled ThruSections} is only available with
the OpenCASCADE kernel.

@c @item ThickSolid ( @var{expression} ) = @{ @var{expression-list} @};
@c todo: @code{ThickSolid} is only available with the OpenCASCADE kernel.

@item Physical Volume ( @var{expression} | @var{char-expression} <, @var{expression}> ) <+|->= @{ @var{expression-list} @};
Creates a physical volume. The @var{expression} inside the parentheses
is the physical volume's tag; the @var{expression-list} on the right
hand side should contain the tags of all the elementary volumes that
need to be grouped inside the physical volume. If a
@var{char-expression} is given instead instead of @var{expression}
inside the parentheses, a string label is associated with the physical
tag, which can be either provided explicitly (after the comma) or not
(in which case a unique tag is automatically created).

@end ftable

@c .........................................................................
@c Extrusions
@c .........................................................................

@node Extrusions, Boolean operations, Volumes, Geometry commands
@subsection Extrusions

@cindex Extrusion, geometry
@cindex Geometry, extrusion
@findex @var{extrude}

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

@var{extrude}:
@ftable @code
@item Extrude @{ @var{expression-list} @}  @{ @var{extrude-list} @}
Extrudes all elementary entities (points, curves or surfaces) in
@var{extrude-list} using a translation. The @var{expression-list} should
contain three @w{@var{expression}s} giving the X, Y and Z components of
the translation vector.

@item Extrude @{ @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} @{ @var{extrude-list} @}
Extrudes all elementary entities (points, curves or surfaces) in
@var{extrude-list} using a rotation. The first @var{expression-list}
should contain three @w{@var{expression}s} giving the X, Y and Z
direction of the rotation axis; the second @var{expression-list} should
contain three @w{@var{expression}s} giving the X, Y and Z components of
any point on this axis; the last @var{expression} should contain the
rotation angle (in radians).

@item Extrude @{ @{ @var{expression-list} @}, @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} @{ @var{extrude-list} @}
Extrudes all elementary entities (points, curves or surfaces) in
@var{extrude-list} using a translation combined with a rotation (to
produce a ``twist''). The first @var{expression-list} should contain
three @w{@var{expression}s} giving the X, Y and Z components of the
translation vector; the second @var{expression-list} should contain
three @w{@var{expression}s} giving the X, Y and Z direction of the
rotation axis, which should match the direction of the translation; the
third @var{expression-list} should contain three @w{@var{expression}s}
giving the X, Y and Z components of any point on this axis; the last
@var{expression} should contain the rotation angle (in radians).

@item Extrude @{ @var{extrude-list} @}
Extrudes entities in @var{extrude-list} using a translation along their
normal. Only available with the built-in geometry kernel.

@item Extrude @{ @var{extrude-list} @} Using Wire @{ @var{expression-list} @}
Extrudes entities in @var{extrude-list} along the give wire. Only
available with the OpenCASCADE geometry kernel.

@item ThruSections @{ @var{expression-list} @}
Creates surfaces through the given curve loops or
wires. @code{ThruSections} is only available with the OpenCASCADE
kernel.

@item Ruled ThruSections @{ @var{expression-list} @}
Creates ruled surfaces through the given curve loops or
wires. @code{Ruled ThruSections} is only available with the OpenCASCADE
kernel.

@item Fillet @{ @var{expression-list} @} @{ @var{expression-list} @} @{ @var{expression-list} @}
Fillets volumes (first list) on some curves (second list), using the
provided radii (third list). The radius list can either contain a single
radius, as many radii as curves, or twice as many as curves (in which
case different radii are provided for the begin and end points of the
curves). @code{Fillet} is only available with the OpenCASCADE kernel.

@item Chamfer @{ @var{expression-list} @} @{ @var{expression-list} @} @{ @var{expression-list} @} @{ @var{expression-list} @}
Chamfer volumes (first list) on some curves (second list), using the
provided distance (fourth list) measured on the given surfaces (third
list). The distance list can either contain a single distance, as many
distances as curves, or twice as many as curves (in which case the first
in each pair is measured on the given corresponding
surface). @code{Chamfer} is only available with the OpenCASCADE kernel.
@end ftable

@noindent with

@example
@var{extrude-list}:
  <Physical> Point | Curve | Surface @{ @var{expression-list-or-all} @}; @dots{}
@end example

As explained in @ref{Floating point expressions}, @var{extrude} can be
used in an expression, in which case it returns a list of tags. 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:

@example
  Point(1) = @{0,0,0@};
  Point(2) = @{1,0,0@};
  Line(1) = @{1, 2@};
  out[] = Extrude@{0,1,0@}@{ Curve@{1@}; @};
  Printf("top curve = %g", out[0]);
  Printf("surface = %g", out[1]);
  Printf("side curves = %g and %g", out[2], out[3]);
@end example

This behaviour can be changed with the
@code{Geometry.ExtrudeReturnLateralEntities} option (@pxref{Geometry
options list}).

@c .........................................................................
@c Boolean operations
@c .........................................................................

@node Boolean operations, Transformations, Extrusions, Geometry commands
@subsection Boolean operations

@cindex Boolean operations, geometry
@cindex Geometry, boolean operations
@cindex Geometry, intersection
@cindex Geometry, difference
@cindex Geometry, union
@cindex Geometry, fragments
@findex @var{boolean}

Boolean operations can be applied on curves, surfaces and volumes. All
boolean operation act on two lists of elementary entities. The first
list represents the object; the second represents the tool. The general
syntax for boolean operations is as follows:

@var{boolean}:
@ftable @code
@item BooleanIntersection @{ @var{boolean-list} @} @{ @var{boolean-list} @}
Computes the intersection of the object and the tool.
@item BooleanUnion @{ @var{boolean-list} @} @{ @var{boolean-list} @}
Computes the union of the object and the tool.
@item BooleanDifference @{ @var{boolean-list} @} @{ @var{boolean-list} @}
Subtract the tool from the object.
@item BooleanFragments @{ @var{boolean-list} @} @{ @var{boolean-list} @}
Computes all the fragments resulting from the intersection of the
entities in the object and in the tool, and makes all interfaces unique.
@end ftable

with

@example
@var{boolean-list}:
  <Physical> Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} |
  Delete ;
@end example

If @code{Delete} is specified in the @var{boolean-list}, the tool and/or
the object is deleted.

As explained in @ref{Floating point expressions}, @var{boolean} can be
used in an expression, in which case it returns the list of
tags of the highest dimensional entities created by
the boolean operation.  See
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/demos/boolean/,demos/boolean}
for examples.

An alternative syntax exists for boolean operations, which can be used
when it is known beforehand that the operation will result in a single
(highest-dimensional) entity:

@var{boolean-explicit}:
@ftable @code
@item BooleanIntersection ( @var{expression} ) = @{ @var{boolean-list} @} @{ @var{boolean-list} @};
Computes the intersection of the object and the tool and assign the
result the tag @var{expression}.
@item BooleanUnion @{ @var{boolean-list} @} @{ @var{boolean-list} @}
Computes the union of the object and the tool and assign the result
the tag @var{expression}.
@item BooleanDifference @{ @var{boolean-list} @} @{ @var{boolean-list} @}
Subtract the tool from the object and assign the result the
tag @var{expression}.
@end ftable

Again, see
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/demos/boolean/,demos/boolean}
for examples.

Boolean operations are only available with the OpenCASCADE geometry kernel.

@c .........................................................................
@c Transformations
@c .........................................................................

@node Transformations, Miscellaneous geometry commands, Boolean operations, Geometry commands
@subsection Transformations

@cindex Transformations, geometry
@cindex Geometry, transformations
@cindex Rotation
@cindex Scale
@cindex Symmetry
@cindex Translation
@findex @var{transform}

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

@var{transform}:
@ftable @code
@item Dilate @{ @{ @var{expression-list} @}, @var{expression} @} @{ @var{transform-list} @}
Scales all elementary entities in @var{transform-list} by a factor
@var{expression}. The @var{expression-list} should contain three
@w{@var{expression}s} giving the X, Y, and Z coordinates of the center
of the homothetic transformation.

@item Dilate @{ @{ @var{expression-list} @}, @{ @var{expression}, @var{expression}, @var{expression} @} @} @{ @var{transform-list} @}
Scales all elementary entities in @var{transform-list} using different
factors along X, Y and Z (the three @var{expression}s). The
@var{expression-list} should contain three @w{@var{expression}s} giving
the X, Y, and Z coordinates of the center of the homothetic
transformation.

@item Rotate @{ @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @}  @{ @var{transform-list} @}
Rotates all elementary entities in @var{transform-list} by an angle of
@var{expression} radians. The first @var{expression-list} should contain
three @w{@var{expression}s} giving the X, Y and Z direction of the
rotation axis; the second @var{expression-list} should contain three
@w{@var{expression}s} giving the X, Y and Z components of any point on
this axis.

@item Symmetry @{ @var{expression-list} @} @{ @var{transform-list} @}
Transforms all elementary entities symmetrically to a plane. The
@var{expression-list} should contain four @w{@var{expression}s} giving
the coefficients of the plane's equation.

@item Translate @{ @var{expression-list} @} @{ @var{transform-list} @}
Translates all elementary entities in @var{transform-list}. The
@var{expression-list} should contain three @w{@var{expression}s} giving
the X, Y and Z components of the translation vector.

@item Boundary @{ @var{transform-list} @}
(Not a transformation per-se.) Returns the entities on the boundary of
the elementary entities in @var{transform-list}, with signs indicating
their orientation in the boundary. To get unsigned tags (e.g. to reuse
the output in other commands), apply the @code{Abs} function on the
returned list.

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

@item PointsOf @{ @var{transform-list} @}
(Not a transformation per-se.) Returns all the geometrical points on the
boundary of the elementary entities. Useful to compute the boundary of a
complex part.

@c @item Intersect Curve @{ @var{expression-list} @} Surface @{ @var{expression} @}
@c (Not a transformation per-se.) Returns the intersections of the curves
@c given in @var{expression-list} with the specified surface.
@end ftable

@noindent with

@example
@var{transform-list}:
  <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} |
  Duplicata @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @} |
  @var{transform}
@end example

@c .........................................................................
@c Miscellaneous
@c .........................................................................

@node Miscellaneous geometry commands,  , Transformations, Geometry commands
@subsection Miscellaneous

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

@ftable @code
@item Coherence;
Removes all duplicate elementary geometrical entities (e.g., points
having identical coordinates). Note that with the built-in geometry
kernel Gmsh executes the @code{Coherence} command automatically after
each geometrical transformation, unless @code{Geometry.AutoCoherence} is
set to zero (@pxref{Geometry options list}). With the OpenCASCADE
geoemtry kernel, @code{Coherence} is simply a shortcut for a
@code{BooleanFragments} operation on all entities.

@item < Recursive > Delete @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Deletes all elementary entities whose tags are given
in @var{expression-list-or-all}. If an entity is linked to another
entity (for example, if a point is used as a control point of a curve),
@code{Delete} has no effect (the curve will have to be deleted before the
point can). The @code{Recursive} variant deletes the entities as well as
all its sub-entities of lower dimension.

@item < Recursive > Hide @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Hide the entities listed in @var{expression-list-or-all}, if
@code{General.VisibilityMode} is set to @code{0} or @code{1}.

@item Hide @{ : @}
Hide all entities, if @code{General.VisibilityMode} is set to @code{0}
or @code{1}.

@item < Recursive > Show @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Show the entities listed in @var{expression-list-or-all}, if
@code{General.VisibilityMode} is set to @code{0} or @code{1}.

@item Show @{ : @}
Show all entities, if @code{General.VisibilityMode} is set to @code{0}
or @code{1}.

@end ftable

@c -------------------------------------------------------------------------
@c Geometry options
@c -------------------------------------------------------------------------

@node Geometry options,  , Geometry commands, Geometry module
@section Geometry options

@cindex Options, geometry
@cindex 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  @ref{Geometry options list}.

@c =========================================================================
@c Mesh module
@c =========================================================================

@node Mesh module, Solver module, Geometry module, Top
@chapter Mesh module

@cindex Mesh, module
@cindex Module, Mesh

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

@itemize @bullet
@item
The 2D @emph{unstructured} algorithms generate triangles or both
triangles and quadrangles (when @code{Recombine Surface} is used: see
@ref{Miscellaneous mesh commands}). The 3D @emph{unstructured}
algorithms generate tetrahedra.
@item
The 2D @emph{structured} algorithms (transfinite and extrusion) generate
triangles by default, but quadrangles can be obtained by using the
@code{Recombine} commands (see @ref{Structured grids}, and
@ref{Miscellaneous mesh commands}). The 3D @emph{structured} algorithms
generate tetrahedra, hexahedra, prisms and pyramids, depending on the
type of the surface meshes they are based on.
@end itemize

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

@c todo: explain what happens if we have a degenerate geometry (incorrect
@c holes with surfaces in contact with the exterior shell, intersecting
@c primitives, etc.)

@menu
* Choosing the right unstructured algorithm::
* Elementary entities vs physical groups::
* Mesh commands::
* Mesh options::
@end menu

@c -------------------------------------------------------------------------
@c Choosing the right unstructured algorithm
@c -------------------------------------------------------------------------

@node Choosing the right unstructured algorithm, Elementary entities vs physical groups, Mesh module, Mesh module
@section 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@footnote{R. A. Dwyer, @emph{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@footnote{N. P. Weatherill,
@emph{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:

@enumerate
@item
The ``MeshAdapt'' algorithm@footnote{C. Geuzaine and J.-F. Remacle,
@emph{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.
@item
The ``Delaunay'' algorithm is inspired by the work of the GAMMA team at
INRIA@footnote{P.-L. George and P. Frey, @emph{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.
@item
The ``Frontal'' algorithm is inspired by the work of
S. Rebay@footnote{S. Rebay, @emph{Efficient unstructured mesh generation
by means of Delaunay triangulation and Bowyer-Watson algorithm},
J. Comput.  Phys. 106, pp. 25--138, 1993.}.
@end enumerate

These algorithms can be ranked as follows:

@example
              Robustness        Performance      Element quality
MeshAdapt         1                  3                 2
Delaunay          2                  1                 2
Frontal           3                  2                 1
@end example

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.8, the
``Automatic'' algorithm selects ``Delaunay'' for plane surfaces and
``MeshAdapt'' for all other surfaces.

In 3D two unstructured algorithms are available:

@enumerate
@item
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@footnote{H. Si, @emph{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.
@item
The ``Frontal'' algorithm uses J. Schoeberl's Netgen algorithm
@footnote{J. Schoeberl, @emph{Netgen, an advancing front 2d/3d-mesh
generator based on abstract rules}, Comput. Visual. Sci., 1, pp. 41--52,
1997.}.
@end enumerate

The ``Delaunay'' algorithm is the most robust and the fastest, and is
the only one that supports the @code{Field} mechanism to specify element
sizes (@pxref{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.

@c -------------------------------------------------------------------------
@c Elementary entities vs. physical groups
@c -------------------------------------------------------------------------

@node Elementary entities vs physical groups, Mesh commands, Choosing the right unstructured algorithm, Mesh module
@section Elementary entities vs. physical groups

It is usually convenient to combine geometrical entities into more
meaningful groups, e.g. to define some mathematical (``domain'',
``boundary with Neumann condition''), functional (``left wing'',
``fuselage'') or material (``steel'', ``carbon'') properties.  Such
grouping is done in Gmsh's geometry module (@pxref{Geometry module})
through ``physical groups''.

By default in the MSH file format (@pxref{File formats}), if physical
groups are defined, the output mesh only contains those elements that
belong to at least one physical group. (Other file formats each treat
physical groups in slightly different ways, depending on their
capability to define groups.)

To save all mesh element wether or not physical groups are defined, use
 the @code{Mesh.SaveAll} option (@pxref{Mesh options list}) or specify
 @code{-save_all} on the command line.

@c -------------------------------------------------------------------------
@c Mesh commands
@c -------------------------------------------------------------------------

@node Mesh commands, Mesh options, Elementary entities vs physical groups, Mesh module
@section Mesh commands

@cindex Mesh commands
@cindex Commands, mesh

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 curves'', ``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 @ref{Running Gmsh on
your system}, and @ref{Command-line options}).

@menu
* Specifying mesh element sizes::
* Structured grids::
* Miscellaneous mesh commands::
@end menu

@c .........................................................................
@c Specifying mesh element sizes
@c .........................................................................

@node Specifying mesh element sizes, Structured grids, Mesh commands, Mesh commands
@subsection Specifying mesh element sizes

@cindex Characteristic lengths
@cindex Mesh, element size
@cindex Size, elements
@cindex Mesh, background
@cindex Background mesh

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

@enumerate
@item
First, if @code{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 @code{Point} command: see
@ref{Points}). The size of the mesh elements will then be computed by
linearly interpolating these values on the initial mesh (see
@ref{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 @ref{Structured grids}).
@item
Second, if @code{Mesh.CharacteristicLengthFromCurvature} is set (it is
not by default), the mesh will be adapted with respect to the curvature
of the geometrical entities.
@item
Finally, you can specify general mesh size ``fields''. Various fields
exist:
@itemize @bullet
@item
A @code{PostView} field specifies an explicit background mesh in the
form of a scalar post-processing view (see @ref{Post-processing
commands}, and @ref{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 (@file{.pos}) files
can currently be used as background meshes (@file{.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 @code{-bgm} option (@pxref{Command-line options}), or in
the GUI by selecting `Apply as background mesh' in the post-processing
view option menu.)
@item
A @code{Box} field specifies the size of the elements inside and outside
of a parallelepipedic region.
@item
A @code{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 curves specified by an @code{Attractor} field.
@item
A @code{MathEval} field specifies the size of the mesh using an explicit
mathematical function.
@item
A @code{Min} field specifies the size as the minimum of the sizes
computed using other fields
@item
@dots{}
@end itemize

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

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
@code{Mesh.CharacteristicLengthMin}, @code{Mesh.CharacteristicLengthMax}
and @code{Mesh.CharacteristicLengthFactor} options (@pxref{Mesh options
list})

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

@ftable @code
@item Characteristic Length @{ @var{expression-list} @} = @var{expression};
Modify the prescribed mesh element size of the points whose
tags are listed in @var{expression-list}. The new
value is given by @var{expression}.
@item Field[@var{expression}] = @var{string};
Create a new field (with tag @var{expression}), of type
@var{string}.
@item Field[@var{expression}].@var{string} = @var{char-expression} | @var{expression} | @var{expression-list};
Set the option @var{string} of the @var{expression}-th field.
@item Background Field = @var{expression};
Select the @var{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 @code{Min} or @code{Max} field (see below).
@end ftable

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

@include opt_fields.texi

@c .........................................................................
@c Structured grids
@c .........................................................................

@node Structured grids, Miscellaneous mesh commands, Specifying mesh element sizes, Mesh commands
@subsection Structured grids

@cindex Extrusion, mesh
@cindex Mesh, extrusion
@cindex Transfinite, mesh
@cindex Mesh, transfinite

@ftable @code
@item Extrude @{ @var{expression-list} @} @{ @var{extrude-list} @var{layers} @}
Extrudes both the geometry and the mesh using a translation
(@pxref{Extrusions}). The @var{layers} option determines how the mesh is
extruded and has the following syntax:

@example
@var{layers}:
@group
  Layers @{ @var{expression} @} |
  Layers @{ @{ @var{expression-list} @}, @{ @var{expression-list} @} @} |
  Recombine < @var{expression} >; @dots{}
  QuadTriNoNewVerts <RecombLaterals>; |
  QuadTriAddVerts <RecombLaterals>; ...
@end group
@end example

In the first @code{Layers} form, @var{expression} gives the number of
elements to be created in the (single) layer. In the second form, the
first @var{expression-list} defines how many elements should be created
in each extruded layer, and the second @var{expression-list} gives the
normalized height of each layer (the list should contain a sequence of
@var{n} numbers 0 < @var{h1} < @var{h2} < @dots{} < @var{hn} <= 1). See
@ref{t3.geo}, for an example.

For curve extrusions, the @code{Recombine} option will recombine triangles
into quadrangles when possible.  For surface extrusions, the
@code{Recombine} option will recombine tetrahedra into prisms, hexahedra or
pyramids.

Please note that, starting with Gmsh 2.0, region tags cannot be
specified explicitly anymore in @code{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 tag of the new ``top''
surface in @code{num[0]} and the tag of the new volume in @code{num[1]}:
@example
num[] = Extrude @{0,0,1@} @{ Surface@{1@}; Layers@{10@}; @};
@end example

@code{QuadTriNoNewVerts} and @code{QuadTriAddVerts} allow to connect
structured, extruded volumes containing quadrangle-faced elements to
structured or unstructured tetrahedral volumes, by subdividing into
triangles any quadrangles on boundary surfaces shared with tetrahedral
volumes. (They have no effect for 1D or 2D extrusions.)
@code{QuadTriNoNewVerts} subdivides any of the region's quad-faced 3D
elements that touch these boundary triangles into pyramids, prisms, or
tetrahedra as necessary, all WITHOUT adding new
nodes. @code{QuadTriAddVerts} works in a simular way, but subdivides
3D elements touching the boundary triangles by adding a new node
inside each element at the node-based centroid. Either method results
in a structured extrusion with an outer layer of subdivided elements
that interface the inner, unmodified elements to the triangle-meshed
region boundaries.

In some rare cases, due to certain lateral boundary conditions, it may
not be possible make a valid element subdivision with
@code{QuadTriNoNewVerts} without adding additional nodes. In this
case, an internal node is created at the node-based centroid of the
element. The element is then divided using that node. When an internal
node is created with @code{QuadTriNoNewVerts}, the user is alerted by
a warning message sent for each instance; however, the mesh will still
be valid and conformal.

Both @code{QuadTriNoNewVerts} and @code{QuadTriAddVerts} can be used
with the optional @code{RecombLaterals} keyword. By default, the QuadTri
algorithms will mesh any free laterals as triangles, if
possible. @code{RecombLaterals} forces any free laterals to remain as
quadrangles, if possible. Lateral surfaces between two QuadTri regions
will always be meshed as quadrangles.

Note that the QuadTri algorithms will handle all potential meshing
conflicts along the lateral surfaces of the extrusion.  In other words,
QuadTri will not subdivide a lateral that must remain as quadrangles,
nor will it leave a lateral as quadrangles if it @emph{must} be divided.
The user should therefore feel free to mix different types of
neighboring regions with a QuadTri meshed region; the mesh should work.
However, be aware that the top surface of the QuadTri extrusion will
always be meshed as triangles, unless it is extruded back onto the
original source in a toroidal loop (a case which also works with
QuadTri).

@code{QuadTriNoNewVerts} and @code{QuadTriAddVerts} may be used
interchangeably, but @code{QuadTriAddVerts} often gives better element
quality.

If the user wishes to interface a structured extrusion to a tetrahedral
volume without modifying the original structured mesh, the user may
create dedicated interface volumes around the structured geometry and
apply a QuadTri algorithm to those volumes only.

@item Extrude @{ @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} @{ @var{extrude-list} @var{layers} @}
Extrudes both the geometry and the mesh using a rotation
(@pxref{Extrusions}). The @var{layers} option is defined as above.

@item Extrude @{ @{ @var{expression-list} @}, @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} @{ @var{extrude-list} @var{layers} @}
Extrudes both the geometry and the mesh using a combined translation and
rotation (@pxref{Extrusions}). The @var{layers} option is defined as
above.

@item Extrude @{ Surface @{ @var{expression-list} @}; @var{layers} < Using Index[@var{expr}]; > < Using View[@var{expr}]; > < ScaleLastLayer; > @}
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).

@code{ScaleLastLayer} scales the height of the last (top) layer of each
normal's extrusion by the average length of the edges in all the source
elements that contain the source node (actually, the average of the
averages for each element--edges actually touching the source node are
counted twice). This allows the height of the last layer to vary along
with the size of the source elements in order to achieve better element
quality. For example, in a boundary layer extruded with the Layers
definition 'Layers@{ @{1,4,2@}, @{0.5, 0.6, 1.6@} @},' a source node
adjacent to elements with an overall average edge length of 5.0 will
extrude to have a last layer height = (1.6-0.6) * 5.0 = 5.0.


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

@item Transfinite Surface @{ @var{expression-list-or-all}  @}  < = @{ @var{expression-list} @} > < Left | Right | Alternate | AlternateRight | AlternateLeft > ;
Selects surfaces to be meshed with the 2D transfinite algorithm. The
@var{expression-list} on the right-hand-side should contain the
tags of three or four points on the boundary of the
surface that define the corners of the transfinite interpolation. If no
tags 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. (@code{Alternate} is a synonym for @code{AlternateRight}).

@item Transfinite Volume @{ @var{expression-list} @} < = @{ @var{expression-list} @} > ;
Selects five- or six-face volumes to be meshed with the 3D transfinite
algorithm.  The @var{expression-list} on the right-hand-side should
contain the tags of the six or eight points on the
boundary of the volume that define the corners of the transfinite
interpolation. If no tags are given, the transfinite
algorithm will try to find the corners automatically.

@item TransfQuadTri @{ @var{expression-list} @} ;

Applies the transfinite QuadTri algorithm on the @var{expression-list}
list of volumes.  A transfinite volume with any combination of
recombined and un-recombined transfinite boundary surfaces is valid when
meshed with @code{TransfQuadTri}. When applied to non-Transfinite
volumes, TransfQuadTri has no effect on those volumes.

@end ftable

@c .........................................................................
@c Levelsets
@c .........................................................................

@c TODO document levelsets; explain use e.g. with AdaptMesh

@c .........................................................................
@c Miscellaneous
@c .........................................................................

@node Miscellaneous mesh commands,  , Structured grids, Mesh commands
@subsection Miscellaneous

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

@ftable @code
@item Mesh @var{expression};
Generates @var{expression}-D mesh.

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

@item OptimizeMesh @var{char-expression};
Optimizes the current mesh with the given algorithm (currently
@code{"Gmsh"} or @code{"Netgen"}).

@item AdaptMesh @{ @var{expression-list} @} @{ @var{expression-list} @} @{ @{ @var{expression-list} < , @dots{} >  @} @};
Performs adaptive mesh generation. Documentation not yet available.

@item RelocateMesh Point | Curve | Surface @{ @var{expression-list-or-all} @};
Relocates the mesh nodes on the given entities using the parametric
coordinates stored in the nodes. Useful for creating perturbation of
meshes e.g. for sensitivity analyzes.

@item SetOrder @var{expression};
Changes the order of the elements in the current mesh.

@item PartitionMesh @var{expression};
Partitions the mesh into @var{expression}, using current partitioning options.

@item Point | Curve @{ @var{expression-list} @} In Surface @{ @var{expression} @};
Embed the point(s) or curve(s) in the given surface. The surface mesh
will conform to the mesh of the point(s) or curves(s).

@item Point | Curve | Surface @{ @var{expression-list} @} In Volume @{ @var{expression} @};
Embed the point(s), curve(s) or surface(s) in the given volume. The
volume mesh will conform to the mesh of the corresponding point(s),
curve(s) or surface(s). This is only supported with the 3D Delaunay
algorithm.

@item Periodic Curve @{ @var{expression-list} @} = @{ @var{expression-list} @} ;
Force mesh of curves on the left-hand side (slaves) to match the mesh of
the curves on the right-hand side (masters).

@item Periodic Surface @var{expression} @{ @var{expression-list} @} = @var{expression} @{ @var{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).

@item Periodic Curve | Surface @{ @var{expression-list} @} = @{ @var{expression-list} @} Affine | Translate @{ @var{expression-list} @} ;
Force mesh of curves or surfaces on the left-hand side (slaves) to match
the mesh of the curves on the right-hand side (masters), using
prescribed geometrical transformations. @code{Affine} takes a 4 x 4 (or
4 x 3) affine transformation matrix given by row; @code{Translate} takes
the 3 components of the translation as in @ref{Transformations}.

@item Periodic Curve | Surface @{ @var{expression-list} @} = @{ @var{expression-list} @} Rotate @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} ;
Force mesh of curves or surfaces on the left-hand side (slaves) to match
the mesh of the curves on the right-hand side (masters), using
a rotation specified as in @ref{Transformations}.

@item Coherence Mesh;
Removes all duplicate mesh nodes.

@item CreateTopology;
Creates a boundary representation from the mesh if the model does not
have one (e.g. when imported from mesh file formats with no BRep
representation of the underlying model).

@item CreateGeometry;
Creates a parametrization for curves and surfaces that do not have one
(i.e. discrete curves and surfaces represented solely by meshes, without
an underlying CAD description).

@item RenumberMeshNodes;
Renumbers the node tags in the current mesh in a contiunous sequence.

@item RenumberMeshElements;
Renumbers the elements tags in the current mesh in a contiunous sequence.

@item SetPartition @var{expression} @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Sets the partition tag of the mesh elements in the entities in @var{expression-list} to @var{expression}.

@item < Recursive > Color @var{color-expression} @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Sets the mesh color of the entities in @var{expression-list} to @var{color-expression}.

@item < Recursive > Hide @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Hides the mesh of the entities in @var{expression-list}, if
@code{General.VisibilityMode} is set to @code{0} or @code{2}.

@item Hide @{ : @}
Hide the mesh of all entities, if @code{General.VisibilityMode} is set
to @code{0} or @code{2}.

@item Recombine Surface @{ @var{expression-list-or-all} @}  < = @var{expression} >;
Recombines the triangular meshes of the surfaces listed in
@var{expression-list} into mixed triangular/quadrangular meshes. The
optional @var{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).

@item MeshAlgorithm Surface @{ @var{expression-list} @} = @var{expression};
Forces the meshing algorithm per surface.

@item Compound Curve | Surface @{ @var{expression-list-or-all} @} ;
Treats the given entities as a single entity when meshing, i.e. perform
cross-patch meshing of the entities.

@item ReverseMesh Curve | Surface @{ @var{expression-list-or-all} @} ;
Reverses the mesh of the given curve(s) or surface(s).

@item ReorientMesh Volume @{ @var{expression-list} @} ;
Reorients the meshes of the bounding surfaces of the given volumes so
that the normals point outward to the volumes. Currently only available
with the OpenCASCADE kernel, as it relies on the STL triangulation.

@item Save @var{char-expression};
Saves the mesh in a file named @var{char-expression}, using the current
@code{Mesh.Format} (@pxref{Mesh options list}). If the path in
@var{char-expression} is not absolute, @var{char-expression} is appended
to the path of the current file.

@item < Recursive > Show @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Shows the mesh of the entities in @var{expression-list}, if
@code{General.VisibilityMode} is set to @code{0} or @code{2}.

@item Show @{ : @};
Shows the mesh of all entities, if @code{General.VisibilityMode} is set
to @code{0} or @code{2}.

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

@item Homology ( @{ @var{expression-list} @} ) @{ @{ @var{expression-list} @} , @{ @var{expression-list} @} @};
Compute a basis representation for homology spaces after a mesh has
been generated. The first @var{expression-list} is a list of
dimensions whose homology bases are computed; if empty, all bases are
computed. The second @var{expression-list} is a list physical groups
that constitute the computation domain; if empty, the whole mesh is
the domain. The third @var{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.

@item Cohomology ( @{ @var{expression-list} @} ) @{ @{ @var{expression-list} @} , @{ @var{expression-list} @} @};
Similar to command @code{Homology}, but computes a basis representation
for cohomology spaces instead.

@end ftable

@c -------------------------------------------------------------------------
@c Mesh options
@c -------------------------------------------------------------------------

@node Mesh options,  , Mesh commands, Mesh module
@section Mesh options

@cindex Options, mesh
@cindex 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
@ref{Mesh options list}.

@c =========================================================================
@c Solver module
@c =========================================================================

@node Solver module, Post-processing module, Mesh module, Top
@chapter Solver module

@cindex Solver, module
@cindex Module, Solver

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

The client-server API for the solver interface is defined in the
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Common/onelab.h,onelab.h}
header. See
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/utils/solvers/c++/solver.cpp,utils/solvers/c++/solver.cpp}
for a simple example on how to use the ONELAB programming interface. See
the sources of GetDP (@url{http://getdp.info}) for a more comprehensive
example.

@menu
* Solver options::
@end menu

@c -------------------------------------------------------------------------
@c Solver options
@c -------------------------------------------------------------------------

@node Solver options,  , Solver module, Solver module
@section Solver options

@cindex Solver commands
@cindex Options, geometry

The list of all the solver options is given in @ref{Solver options list}.

@c =========================================================================
@c Post-processing module
@c =========================================================================

@node Post-processing module, File formats, Solver module, Top
@chapter Post-processing module

@cindex Post-processing, module
@cindex Module, Post-processing
@cindex 2D plots
@cindex 3D plots
@cindex Plots
@cindex Graphs
@cindex Views

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 @file{.pos} extension), in native MSH files (ASCII
or binary files with @file{.msh} extensions: see @ref{File formats}), or
in standard third-party formats (like MED:
@uref{http://www.code-aster.org/outils/med/}).

Once loaded into Gmsh, scalar fields can be displayed as iso-value curves
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 @code{Force scalar} or
@code{Force vector} options, or use @code{Plugin(MathEval)}: see
@ref{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 @code{PostProcessing.Link} option in
@ref{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, curves,
triangles, tetrahedra, etc.) in 3D space. But Gmsh can also represent each
post-processing view containing @emph{scalar points} as two-dimensional
(``X-Y'') plots, either space- or time-oriented:

@itemize @bullet
@item
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;
@item
in a `2D time' plot, one curve is drawn for each scalar point in the view
and the abscissa is the time step.
@end itemize

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., @ref{t8.geo}, and @ref{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
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial,tutorial}
directory of Gmsh's distribution (@file{.pos} and @file{.msh}
files). The ``parsed'' format is defined in the next section (cf. the
@code{View} command); the MSH format is defined in @ref{File formats}.

@menu
* Post-processing commands::
* Post-processing plugins::
* Post-processing options::
@end menu

@c -------------------------------------------------------------------------
@c Post-processing commands
@c -------------------------------------------------------------------------

@node Post-processing commands, Post-processing plugins, Post-processing module, Post-processing module
@section Post-processing commands

@cindex Post-processing commands
@cindex Commands, post-processing

@ftable @code
@item Alias View[@var{expression}];
Creates an alias of the @var{expression}-th post-processing view.

Note that @code{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.

@item AliasWithOptions View[@var{expression}];
Creates an alias of the @var{expression}-th post-processing view and copies
all the options of the @var{expression}-th view to the new aliased view.

@item CopyOptions View[@var{expression}, @var{expression}];
Copy all the options from the first @var{expression}-th post-processing
view to the second one.

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

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

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

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

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

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

@item Delete View[@var{expression}];
Deletes (removes) the @var{expression}-th post-processing view. Note that
post-processing view indices start at 0.

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

@item Background Mesh View[@var{expression}];
Applies the @var{expression}-th post-processing view as the current
background mesh. Note that post-processing view indices start at 0.

@item Plugin (@var{string}) . Run;
Executes the plugin @var{string}. The list of default plugins is given in
@ref{Post-processing plugins}.

@item Plugin (@var{string}) . @var{string} = @var{expression} | @var{char-expression};
Sets an option for a given plugin. See @ref{Post-processing plugins}, for a
list of default plugins and @ref{t9.geo}, for some examples.

@item Save View[@var{expression}] @var{char-expression};
Saves the @var{expression}-th post-processing view in a file named
@var{char-expression}. If the path in @var{char-expression} is not absolute,
@var{char-expression} is appended to the path of the current file.

@item SendToServer View[@var{expression}] @var{char-expression};
Sends the @var{expression}-th post-processing view to the ONELAB server,
with parameter name @var{char-expression}.

@item View "@var{string}" @{ @var{string} < ( @var{expression-list} ) > @{ @var{expression-list} @}; @dots{} @};
Creates a new post-processing view, named @code{"@var{string}"}.  This
is an easy and quite powerful way to import post-processing data: all
the values are @var{expressions}, you can embed datasets directly into
your geometrical descriptions (see, e.g., @ref{t4.geo}), the data can be
easily generated ``on-the-fly'' (there is no header containing @emph{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 @ref{File
formats}, or use one of the standard formats like MED.

More explicitly, the syntax for a parsed @code{View} is the following

@example
@group
View "@var{string}" @{
  @var{type} ( @var{list-of-coords} ) @{ @var{list-of-values} @}; @dots{}
  < TIME @{ @var{expression-list} @}; >
  < INTERPOLATION_SCHEME @{ @var{val-coef-matrix} @} @{ @var{val-exp-matrix} @}
                  < @{ @var{geo-coef-matrix} @} @{ @var{geo-exp-matrix} @} > ; >
@};
@end group
@end example

where the 47 object @w{@var{type}s} that can be displayed are:

@smallexample
                              @var{type}  #@var{list-of-coords}  #@var{list-of-values}
--------------------------------------------------------------------
Scalar point                  SP    3            1  * @var{nb-time-steps}
Vector point                  VP    3            3  * @var{nb-time-steps}
Tensor point                  TP    3            9  * @var{nb-time-steps}
Scalar line                   SL    6            2  * @var{nb-time-steps}
Vector line                   VL    6            6  * @var{nb-time-steps}
Tensor line                   TL    6            18 * @var{nb-time-steps}
Scalar triangle               ST    9            3  * @var{nb-time-steps}
Vector triangle               VT    9            9  * @var{nb-time-steps}
Tensor triangle               TT    9            27 * @var{nb-time-steps}
Scalar quadrangle             SQ    12           4  * @var{nb-time-steps}
Vector quadrangle             VQ    12           12 * @var{nb-time-steps}
Tensor quadrangle             TQ    12           36 * @var{nb-time-steps}
Scalar tetrahedron            SS    12           4  * @var{nb-time-steps}
Vector tetrahedron            VS    12           12 * @var{nb-time-steps}
Tensor tetrahedron            TS    12           36 * @var{nb-time-steps}
Scalar hexahedron             SH    24           8  * @var{nb-time-steps}
Vector hexahedron             VH    24           24 * @var{nb-time-steps}
Tensor hexahedron             TH    24           72 * @var{nb-time-steps}
Scalar prism                  SI    18           6  * @var{nb-time-steps}
Vector prism                  VI    18           18 * @var{nb-time-steps}
Tensor prism                  TI    18           54 * @var{nb-time-steps}
Scalar pyramid                SY    15           5  * @var{nb-time-steps}
Vector pyramid                VY    15           15 * @var{nb-time-steps}
Tensor pyramid                TY    15           45 * @var{nb-time-steps}
2D text                       T2    3            arbitrary
3D text                       T3    4            arbitrary
@end smallexample

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

@itemize @bullet
@item
@code{(@var{coord1}, @var{coord2}, @var{coord3})} for a point,
@item
@code{(@var{coord1-node1}, @var{coord2-node1}, @var{coord3-node1},}@*
@code{ @var{coord1-node2}, @var{coord2-node2}, @var{coord3-node2})} for a line,
@item
@code{(@var{coord1-node1}, @var{coord2-node1}, @var{coord3-node1},}@*
@code{ @var{coord1-node2}, @var{coord2-node2}, @var{coord3-node2},}@*
@code{ @var{coord1-node3}, @var{coord2-node3}, @var{coord3-node3})} for a triangle,
@item
etc.
@end itemize

The ordering of the nodes is given in @ref{Node ordering}.

The values are given by time step, by node and by component, i.e.:
@example
@var{comp1-node1-time1}, @var{comp2-node1-time1}, @var{comp3-node1-time1},
@var{comp1-node2-time1}, @var{comp2-node2-time1}, @var{comp3-node2-time1},
@var{comp1-node3-time1}, @var{comp2-node3-time1}, @var{comp3-node3-time1},
@var{comp1-node1-time2}, @var{comp2-node1-time2}, @var{comp3-node1-time2},
@var{comp1-node2-time2}, @var{comp2-node2-time2}, @var{comp3-node2-time2},
@var{comp1-node3-time2}, @var{comp2-node3-time2}, @var{comp3-node3-time2},
@dots{}
@end example

For the 2D text objects, the two first @w{@var{expression}s} in
@var{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) @var{expression} is negative, the position is measured
from the right (respectively bottom) edge of the window. If the value of the
first (respectively second) @var{expression} is larger than 99999, the
string is centered horizontally (respectively vertically). If the third
@var{expression} is equal to zero, the text is aligned bottom-left and
displayed using the default font and size. Otherwise, the third
@var{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 @w{@var{expression}s} in
@var{list-of-coords} give the XYZ position of the string in model (real
world) coordinates.  The fourth @var{expression} has the same meaning as the
third @var{expression} in 2D text objects.

For both 2D and 3D text objects, the @var{list-of-values} can contain an
arbitrary number of @w{@var{char-expression}s}. If the
@var{char-expression} starts with @code{file://}, the remainder of the
string is interpreted as the name of an image file, and the image is
displayed instead of the string. A format string in the form
@code{@@wxh} or @code{@@wxh,wx,wy,wz,hx,hy,hz}, where @code{w} and
@code{h} are the width and height (in model coordinates for @code{T3} or
in pixels for @code{T2}) of the image, @code{wx,wy,wz} is the direction
of the bottom edge of the image and @code{hx,hy,hz} is the direction of
the left edge of the image.

The optional @code{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 @code{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 @var{d} basis functions
@var{f}[@var{i}], @var{i}=0, ..., @var{d}-1 (the coefficients being
stored in @var{list-of-values}). Defining @var{f}[@var{i}] =
Sum(@var{j}=0, ..., @var{d}-1) @var{F}[@var{i}][@var{j}]
@var{p}[@var{j}], with @var{p}[@var{j}] = @var{u}^@var{P}[@var{j}][0]
@var{v}^@var{P}[@var{j}][1] @var{w}^@var{P}[@var{j}][2] (@var{u},
@var{v} and @var{w} being the coordinates in the element's parameter
space), then @var{val-coef-matrix} denotes the @var{d} x @var{d} matrix
@var{F} and @var{val-exp-matrix} denotes the @var{d} x @var{3} matrix
@var{P}.

In the same way, let us also assume that the coordinates @var{x},
@var{y} and @var{z} of the element are obtained through a geometrical
mapping from parameter space as a linear combination of @var{m} basis
functions @var{g}[@var{i}], @var{i}=0, ..., @var{m}-1 (the coefficients
being stored in @var{list-of-coords}). Defining @var{g}[@var{i}] =
Sum(@var{j}=0, ..., @var{m}-1) @var{G}[@var{i}][@var{j}]
@var{q}[@var{j}], with @var{q}[@var{j}] = @var{u}^@var{Q}[@var{j}][0]
@var{v}^@var{Q}[@var{j}][1] @var{w}^@var{Q}[@var{j}][2], then
@var{geo-coef-matrix} denotes the @var{m} x @var{m} matrix @var{G} and
@var{geo-exp-matrix} denotes the @var{m} x @var{3} matrix @var{Q}.

Here are for example the interpolation matrices for a first order
quadrangle:
@smallexample
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@}
@};
@end smallexample

@end ftable

@c -------------------------------------------------------------------------
@c Post-processing plugins
@c -------------------------------------------------------------------------

@node Post-processing plugins, Post-processing options, Post-processing commands, Post-processing module
@section Post-processing plugins

@cindex Post-processing plugins
@cindex Plugins, post-processing

Post-processing plugins permit to extend the functionality of Gmsh's
post-processing module. The difference between regular post-processing
options (@pxref{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:

@include opt_plugin.texi

@c -------------------------------------------------------------------------
@c Post-processing options
@c -------------------------------------------------------------------------

@node Post-processing options,  , Post-processing plugins, Post-processing module
@section Post-processing options

@cindex Post-processing, options
@cindex Options, post-processing

General post-processing option names have the form
`@code{PostProcessing.@var{string}}'. Options peculiar to post-processing
views take two forms.

@enumerate
@item options that should apply to all views can be set through
`@code{View.@var{string}}', @emph{before any view is loaded};
@item options that should apply only to the @var{n}-th
view take the form `@code{View[@var{n}].@var{string}}' (@var{n} = 0, 1, 2,
@dots{}), @emph{after the @var{n}-th view is loaded}.
@end enumerate

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

@c =========================================================================
@c File Formats
@c =========================================================================

@node File formats, Tutorial, Post-processing module, Top
@chapter File formats

@cindex 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 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
@ref{Post-processing commands}. Such ``parsed'' views do not require an
underlying mesh, and can therefore be easier to use in some
cases.)

@menu
* MSH file format (version 4)::
* Node ordering::
* Legacy formats::
@end menu

@c -------------------------------------------------------------------------
@c MSH file format (version 4)
@c -------------------------------------------------------------------------

@node MSH file format (version 4), Node ordering, File formats, File formats
@section MSH file format (version 4)

@cindex Mesh, file format
@cindex File format, mesh
@cindex MSH4 file

The MSH file format (version 4) contains one mandatory section giving
information about the file (@code{$MeshFormat}), followed by several
sections defining the physical group names (@code{$PhysicalName},
optional), the entities (@code{$Entities}), the partitioned entities
(@code{$PartitionedEntities}, optional), nodes (@code{$Nodes}), elements
(@code{$Elements}), periodicity relations (@code{$Periodic}, optional),
ghost elements (@code{$GhostElements}, optional) and post-processing
datasets (@code{$NodeData}, @code{$ElementData},
@code{$ElementNodeData}, all optional).

Important note about efficiency. Node and element tags can be "sparse",
i.e., do not have to constitute a continuous list of indexes starting at
1. However, using non-continuous tags will lead to performance
degradation. For meshes, non-continuous indexing forces Gmsh to use a
map instead of a vector to access nodes and elements. The performance
hit is on speed. For post-processing datasets, which always use vectors
to access data, the performance hit is on memory. A @code{$NodeData} with
two nodes, tagged 1 and 1000000, will allocate a (mostly empty) vector
of 1000000 elements.

Any section with an unrecognized header is simply ignored: you can thus
add comments in a @file{.msh} file by putting them e.g. inside a
@code{$Comments}/@code{$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.

In binary mode (@code{Mesh.Binary=1} or @code{-bin} on the command
line), all the numerical values (integer and floating point) not marked
as ASCII in what follows are written in binary form. Note that the
binary mode will evolve in a future minor revision of the format to
allow for 64-bit node and element tags.

@example
$MeshFormat // same as MSH version 2
  version(ASCII double; currently 4.0) file-type(ASCII int; 1 for binary mode)
    data-size(ASCII int; currently unused)
  <int with value one; only in binary mode, to detect endianness>
$EndMeshFormat

<$PhysicalNames> // same as MSH version 2
  numPhysicalNames(ASCII int)
  dimension(ASCII int) tag(ASCII int) name(127 characters max)
  ...
<$EndPhysicalNames>

$Entities
  numPoints(unsigned long) numCurves(unsigned long)
    numSurfaces(unsigned long) numVolumes(unsigned long)
  // points
  tag(int) boxMinX(double) boxMinY(double) boxMinZ(double)
    boxMaxX(double) boxMaxY(double) boxMaxZ(double)
    numPhysicals(unsigned long) physicalTag(int) ...
  ...
  // curves
  tag(int) boxMinX(double) boxMinY(double) boxMinZ(double)
     boxMaxX(double) boxMaxY(double) boxMaxZ(double)
     numPhysicals(unsigned long) physicalTag(int) ...
     numBoundingPoints(unsigned long) tagPoint(int) ...
  ...
  // surfaces
  tag(int) boxMinX(double) boxMinY(double) boxMinZ(double)
    boxMaxX(double) boxMaxY(double) boxMaxZ(double)
    numPhysicals(unsigned long) physicalTag(int) ...
    numBoundingCurves(unsigned long) tagCurve(int) ...
  ...
  // volumes
  tag(int) boxMinX(double) boxMinY(double) boxMinZ(double)
    boxMaxX(double) boxMaxY(double) boxMaxZ(double)
    numPhysicals(unsigned long) physicalTag(int) ...
    numBoundngSurfaces(unsigned long) tagSurfaces(int) ...
  ...
$EndEntities

<$PartitionedEntities>
  numPartitions(int)
  numGhostEntities(int)
  ghostEntityTag(int) partition(int)
  ...
  numPoints(unsigned long) numCurves(unsigned long)
    numSurfaces(unsigned long) numVolumes(unsigned long)
  // points
  tag(int) parentDim(int) parentTag(int) numPartitions(int) partitionTag(int) ...
    boxMinX(double) boxMinY(double) boxMinZ(double)
    boxMaxX(double) boxMaxY(double) boxMaxZ(double)
    numPhysicals(unsigned long) physicalTag(int) ...
  ...
  // curves
  tag(int) parentDim(int) parentTag(int) numPartitions(int) partitionTag(int) ...
    boxMinX(double) boxMinY(double) boxMinZ(double)
    boxMaxX(double) boxMaxY(double) boxMaxZ(double)
    numPhysicals(unsigned long) physicalTag(int) ...
    numBoundingPoints(unsigned long) tagPoint(int) ...
  ...
  // surfaces
  tag(int) parentDim(int) parentTag(int) numPartitions(int) partitionTag(int) ...
    boxMinX(double) boxMinY(double) boxMinZ(double)
    boxMaxX(double) boxMaxY(double) boxMaxZ(double)
    numPhysicals(unsigned long) physicalTag(int) ...
    numBoundingCurves(unsigned long) tagCurve(int) ...
  ...
  // volumes
  tag(int) parentDim(int) parentTag(int) numPartitions(int) partitionTag(int) ...
    boxMinX(double) boxMinY(double) boxMinZ(double)
    boxMaxX(double) boxMaxY(double) boxMaxZ(double)
    numPhysicals(unsigned long) physicalTag(int) ...
    numBoundingSurfaces(unsigned long) tagSurfaces(int) ...
  ...
<$EndPartitionedEntities>

$Nodes
  numEntityBlocks(unsigned long) numNodes(unsigned long)
  tagEntity(int) dimEntity(int) parametric(int; see below) numNodes(unsigned long)
    tag(int) x(double) y(double) z(double)
       <u(double; if parametric and on curve or surface)>
       <v(double; if parametric and on surface)>
    ...
  ...
$EndNodes

$Elements
  numEntityBlocks(unsigned long) numElements(unsigned long)
  tagEntity(int) dimEntity(int) typeEle(int; see below) numElements(unsigned long)
    tag(int) numVert(int) ...
    ...
  ...
$EndElements

<$Periodic> // same as in MSH version 2
  numPeriodicLinks(int)
  slaveDim(int) slaveTag(int) masterTag(int)
    < Affine value(double) ... >
    correspondingVertexSize(unsigned long)
      numVert(int) numVert(int)
      ...
  ...
<$EndPeriodic>

<$GhostElements>
  numGhostElement(int)
  elementTag(int) partition(int) numGhostPartitions(int) ghostPartition(int) ...
<$EndGhostElements>

<$NodeData>
  numStringTags(ASCII int)
  stringTag(string) ...
  numRealTags(ASCII int)
  realTag(ASCII double) ...
  numIntegerTags(ASCII int)
  integerTag(ASCII int) ...
  nodeNumber(int) value(double) ...
<$EndNodeData>

<$ElementData>
  numStringTags(ASCII int)
  stringTag(string) ...
  numRealTags(ASCII int)
  realTag(ASCII double) ...
  numIntegerTags(ASCII int)
  integerTag(ASCII int) ...
  elementNumber(int) value(double) ...
<$EndElementData>

<$ElementNodeData>
  numStringTags(ASCII int)
  stringTag(string) ...
  numRealTags(ASCII int)
  realTag(ASCII double) ...
  numIntegerTags(ASCII int)
  integerTag(ASCII int) ...
  elementNumber(int) numNodesPerElement(int) value(double) ...
<$EndElementNodeData>

<$InterpolationScheme>
  name(string)
  numElementTopologies(ASCII int)
  elementTopology
  numInterpolationMatrices(ASCII int)
  numRows(ASCII int) numColumns(ASCII int) value(ASCII double) ...
<$EndInterpolationScheme>
@end example

@code{typeEle} is e.g.:
@table @code
@item 1
2-node line.
@item 2
3-node triangle.
@item 3
4-node quadrangle.
@item 4
4-node tetrahedron.
@item 5
8-node hexahedron.
@item 6
6-node prism.
@item 7
5-node pyramid.
@item 8
3-node second order line (2 nodes associated with the vertices and 1
with the edge).
@item 9
6-node second order triangle (3 nodes associated with the vertices and 3
with the edges).
@item 10
9-node second order quadrangle (4 nodes associated with the vertices, 4
with the edges and 1 with the face).
@item 11
10-node second order tetrahedron (4 nodes associated with the vertices
and 6 with the edges).
@item 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).
@item 13
18-node second order prism (6 nodes associated with the vertices, 9 with
the edges and 3 with the quadrangular faces).
@item 14
14-node second order pyramid (5 nodes associated with the vertices, 8
with the edges and 1 with the quadrangular face).
@item 15
1-node point.
@item 16
8-node second order quadrangle (4 nodes associated with the vertices and
4 with the edges).
@item 17
20-node second order hexahedron (8 nodes associated with the vertices
and 12 with the edges).
@item 18
15-node second order prism (6 nodes associated with the vertices and 9
with the edges).
@item 19
13-node second order pyramid (5 nodes associated with the vertices and 8
with the edges).
@item 20
9-node third order incomplete triangle (3 nodes associated with the vertices, 6
with the edges)
@item 21
10-node third order triangle (3 nodes associated with the vertices, 6
with the edges, 1 with the face)
@item 22
12-node fourth order incomplete triangle (3 nodes associated with the vertices, 9
with the edges)
@item 23
15-node fourth order triangle (3 nodes associated with the vertices, 9
with the edges, 3 with the face)
@item 24
15-node fifth order incomplete triangle (3 nodes associated with the vertices, 12
with the edges)
@item 25
21-node fifth order complete triangle (3 nodes associated with the vertices, 12
with the edges, 6 with the face)
@item 26
4-node third order edge (2 nodes associated with the vertices, 2
internal to the edge)
@item 27
5-node fourth order edge (2 nodes associated with the vertices, 3
internal to the edge)
@item 28
6-node fifth order edge (2 nodes associated with the vertices, 4
internal to the edge)
@item 29
20-node third order tetrahedron (4 nodes associated with the vertices,
12 with the edges, 4 with the faces)
@item 30
35-node fourth order tetrahedron (4 nodes associated with the vertices,
18 with the edges, 12 with the faces, 1 in the volume)
@item 31
56-node fifth order tetrahedron (4 nodes associated with the vertices,
24 with the edges, 24 with the faces, 4 in the volume)
@item 92
64-node third order hexahedron (8 nodes associated with the vertices, 24
with the edges, 24 with the faces, 8 in the volume)
@item 93
125-node fourth order hexahedron (8 nodes associated with the vertices, 36
with the edges, 54 with the faces, 27 in the volume)
@end table
See below for the ordering of the nodes.

The post-processing sections are identical to the ones in the version 2
file format (see below). These sections will be reworked in a future
minor revision of the version 4 format (e.g. version 4.1 or 4.2).

@c -------------------------------------------------------------------------
@c Node ordering
@c -------------------------------------------------------------------------

@node Node ordering, Legacy formats, MSH file format (version 4), File formats
@section Node ordering

@cindex Nodes, ordering

Historically, Gmsh developers 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.

@subsection Low order elements

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

@smallexample
@group
Line:                   Line3:           Line4:

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

@end group
@end smallexample

@smallexample
@group
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

@end group
@end smallexample

@smallexample
@group
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

@end group
@end smallexample

@smallexample
@group
Tetrahedron:                          Tetrahedron10:

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

@smallexample
@group
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

@end group
@end smallexample

@smallexample
@group
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

@end group
@end smallexample

@smallexample
@group
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
@end group
@end smallexample

@subsection 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:
@itemize --
@item the element principal or corner vertices;
@item the internal nodes for each edge;
@item the internal nodes for each face;
@item the volume internal nodes.
@end itemize

The numbering for internal nodes is recursive, i.e. 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
node 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 node with the lowest index.

@c -------------------------------------------------------------------------
@c Legacy formats
@c -------------------------------------------------------------------------

@node Legacy formats,  , Node ordering, File formats
@section 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.

@menu
* MSH file format version 2::
* MSH file format version 1::
* POS ASCII file format::
* POS binary file format::
@end menu

@c .........................................................................
@c MSH file format version 2
@c .........................................................................

@node MSH file format version 2, MSH file format version 1, Legacy formats, Legacy formats
@subsection MSH file format version 2

The MSH file format version 2 is Gmsh's previous native mesh file
format, now superseded by the format described in @ref{MSH file format
(version 4)}. It is defined as follows:

The format is defined as follows:

@example
$MeshFormat
@var{version-number} @var{file-type} @var{data-size}
$EndMeshFormat
$PhysicalNames
@var{number-of-names}
@var{physical-dimension} @var{physical-tag} "@var{physical-name}"
@dots{}
$EndPhysicalNames
$Nodes
@var{number-of-nodes}
@var{node-number} @var{x-coord} @var{y-coord} @var{z-coord}
@dots{}
$EndNodes
$Elements
@var{number-of-elements}
@var{elm-number} @var{elm-type} @var{number-of-tags} < @var{tag} > @dots{} @var{node-number-list}
@dots{}
$EndElements
$Periodic
@var{number-of-periodic-entities}
@var{dimension} @var{slave-entity-tag} @var{master-entity-tag}
@var{number-of-nodes}
@var{slave-node-number master-node-number}
@dots{}
$EndPeriodic
$NodeData
@var{number-of-string-tags}
< "@var{string-tag}" >
@dots{}
@var{number-of-real-tags}
< @var{real-tag} >
@dots{}
@var{number-of-integer-tags}
< @var{integer-tag} >
@dots{}
@var{node-number} @var{value} @dots{}
@dots{}
$EndNodeData
$ElementData
@var{number-of-string-tags}
< "@var{string-tag}" >
@dots{}
@var{number-of-real-tags}
< @var{real-tag} >
@dots{}
@var{number-of-integer-tags}
< @var{integer-tag} >
@dots{}
@var{elm-number} @var{value} @dots{}
@dots{}
$EndElementData
$ElementNodeData
@var{number-of-string-tags}
< "@var{string-tag}" >
@dots{}
@var{number-of-real-tags}
< @var{real-tag} >
@dots{}
@var{number-of-integer-tags}
< @var{integer-tag} >
@dots{}
@var{elm-number} @var{number-of-nodes-per-element} @var{value} @dots{}
@dots{}
$EndElementNodeData
$InterpolationScheme
"@var{name}"
@var{number-of-element-topologies}
@var{elm-topology}
@var{number-of-interpolation-matrices}
@var{num-rows} @var{num-columns} @var{value} @dots{}
@dots{}
$EndInterpolationScheme
@end example

@noindent
where
@table @code
@item @var{version-number}
is a real number equal to 2.2

@item @var{file-type}
is an integer equal to 0 in the ASCII file format.

@item @var{data-size}
is an integer equal to the size of the floating point numbers used in the
file (currently only @var{data-size} = sizeof(double) is supported).

@item @var{number-of-nodes}
is the number of nodes in the mesh.

@item @var{node-number}
is the number (index) of the @var{n}-th node in the mesh;
@var{node-number} must be a postive (non-zero) integer. Note that the
@w{@var{node-number}s} do not necessarily have to form a dense nor an
ordered sequence.

@item @var{x-coord} @var{y-coord} @var{z-coord}
are the floating point values giving the X, Y and Z coordinates of the
@var{n}-th node.

@item @var{number-of-elements}
is the number of elements in the mesh.

@item @var{elm-number}
is the number (index) of the @var{n}-th element in the mesh;
@var{elm-number} must be a postive (non-zero) integer. Note that the
@w{@var{elm-number}s} do not necessarily have to form a dense nor an
ordered sequence.

@item @var{elm-type}
defines the geometrical type of the @var{n}-th element: see @ref{MSH
file format (version 4)}.

@item @var{number-of-tags}
gives the number of integer tags that follow for the @var{n}-th
element. By default, the first @var{tag} is the tag of the physical
entity to which the element belongs; the second is the tag 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. Gmsh and most codes using the MSH 2 format
require at least the first two tags (physical and elementary tags).

@item @var{node-number-list}
is the list of the node numbers of the @var{n}-th element. The ordering of
the nodes is given in @ref{Node ordering}.

@item @var{number-of-string-tags}
gives the number of string tags that follow. By default the first
@var{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 @code{$InterpolationScheme}
section (see below).

@item @var{number-of-real-tags}
gives the number of real number tags that follow. By default the first
@var{real-tag} is interpreted as a time value associated with the
dataset.

@item @var{number-of-integer-tags}
gives the number of integer tags that follow. By default the first
@var{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).

@item @var{number-of-nodes-per-elements}
gives the number of node values for an element in an element-based view.

@item @var{value}
is a real number giving the value associated with a node or an
element. For @code{NodeData} (respectively @code{ElementData}) views,
there are @var{ncomp} values per node (resp. per element), where
@var{ncomp} is the number of field components. For
@code{ElementNodeData} views, there are @var{ncomp} times
@var{number-of-nodes-per-elements} values per element.

@item @var{number-of-element-topologies}
is the number of element topologies for which interpolation matrices are
provided

@item @var{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.

@item @var{number-of-interpolation-matrices}
is the number of interpolation matrices provided for the element
topology @var{elm-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 @ref{Post-processing commands}). The matrices are
specified by 2 integers (@var{num-rows} and @var{num-columns}) followed
by the values.

@end table

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!):

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

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

@example
$MeshFormat
@var{version-number} @var{file-type} @var{data-size}
@var{one-binary}
$EndMeshFormat
$Nodes
@var{number-of-nodes}
@var{nodes-binary}
$EndNodes
$Elements
@var{number-of-elements}
@var{element-header-binary}
@var{elements-binary}
@var{element-header-binary}
@var{elements-binary}
@dots{}
$EndElements

[ All other sections are identical to ASCII, except that @var{node-number},
  @var{elm-number}, @var{number-of-nodes-per-element} and @var{values} are written in
  binary format. Beware that all the $End tags must start on a new line. ]
@end example

@noindent
where
@table @code
@item @var{version-number}
is a real number equal to 2.2.

@item @var{file-type}
is an integer equal to 1.

@item @var{data-size}
has the same meaning as in the ASCII file format. Currently only
@var{data-size} = sizeof(double) is supported.

@item @var{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 @var{one-binary}:
@example
int one = 1;
fwrite(&one, sizeof(int), 1, file);
@end example

@item @var{number-of-nodes}
has the same meaning as in the ASCII file format.

@item @var{nodes-binary}
is the list of nodes in binary form, i.e., a array of
@var{number-of-nodes} * (4 + 3 * @var{data-size}) bytes. For each node,
the first 4 bytes contain the node number and the next (3 *
@var{data-size}) bytes contain the three floating point coordinates.

Here is a pseudo C code to write @var{nodes-binary}:
@example
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);
@}
@end example

@item @var{number-of-elements}
has the same meaning as in the ASCII file format.

@item @var{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 @var{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 @var{number-of-tags} in the ASCII format).

Here is a pseudo C code to write @var{element-header-binary}:
@example
int header[3] = @{elm_type, num_elm_follow, num_tags@};
fwrite(header, sizeof(int), 3, file);
@end example

@item @var{elements-binary}
is a list of elements in binary form, i.e., an array of ``number of
elements that follow'' * (4 + @var{number-of-tags} * 4 +
#@var{node-number-list} * 4) bytes. For each element, the first four
bytes contain the element number, the next (@var{number-of-tags} * 4)
contain the tags, and the last (#@var{node-number-list} * 4) contain the
node indices.

Here is a pseudo C code to write @var{elements-binary} for triangles
with the 2 standard tags (the physical and elementary regions):
@example
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);
@}
@end example
@end table

@c .........................................................................
@c MSH file format version 1
@c .........................................................................

@node MSH file format version 1, POS ASCII file format, MSH file format version 2, Legacy formats
@subsection MSH file format version 1

The MSH file format version 1 is Gmsh's original native mesh file
format, now superseded by the format described in @ref{MSH file
format (version 4)}. It is defined as follows:

@example
$NOD
@var{number-of-nodes}
@var{node-number} @var{x-coord} @var{y-coord} @var{z-coord}
@dots{}
$ENDNOD
$ELM
@var{number-of-elements}
@var{elm-number} @var{elm-type} @var{reg-phys} @var{reg-elem} @var{number-of-nodes} @var{node-number-list}
@dots{}
$ENDELM
@end example

@noindent
where
@table @code
@item @var{number-of-nodes}
is the number of nodes in the mesh.

@item @var{node-number}
is the number (index) of the @var{n}-th node in the mesh;
@var{node-number} must be a postive (non-zero) integer. Note that the
@w{@var{node-number}s} do not necessarily have to form a dense nor an
ordered sequence.

@item @var{x-coord} @var{y-coord} @var{z-coord}
are the floating point values giving the X, Y and Z coordinates of the
@var{n}-th node.

@item @var{number-of-elements}
is the number of elements in the mesh.

@item @var{elm-number}
is the number (index) of the @var{n}-th element in the mesh;
@var{elm-number} must be a postive (non-zero) integer. Note that the
@w{@var{elm-number}s} do not necessarily have to form a dense nor an
ordered sequence.

@item @var{elm-type}
defines the geometrical type of the @var{n}-th element:
@table @code
@item 1
2-node line.
@item 2
3-node triangle.
@item 3
4-node quadrangle.
@item 4
4-node tetrahedron.
@item 5
8-node hexahedron.
@item 6
6-node prism.
@item 7
5-node pyramid.
@item 8
3-node second order line (2 nodes associated with the vertices and 1
with the edge).
@item 9
6-node second order triangle (3 nodes associated with the vertices and 3
with the edges).
@item 10
9-node second order quadrangle (4 nodes associated with the vertices, 4
with the edges and 1 with the face).
@item 11
10-node second order tetrahedron (4 nodes associated with the vertices
and 6 with the edges).
@item 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).
@item 13
18-node second order prism (6 nodes associated with the vertices, 9 with
the edges and 3 with the quadrangular faces).
@item 14
14-node second order pyramid (5 nodes associated with the vertices, 8
with the edges and 1 with the quadrangular face).
@item 15
1-node point.
@item 16
8-node second order quadrangle (4 nodes associated with the vertices and
4 with the edges).
@item 17
20-node second order hexahedron (8 nodes associated with the vertices
and 12 with the edges).
@item 18
15-node second order prism (6 nodes associated with the vertices and 9
with the edges).
@item 19
13-node second order pyramid (5 nodes associated with the vertices and 8
with the edges).
@end table
See below for the ordering of the nodes.

@item @var{reg-phys}
is the tag of the physical entity to which the element belongs;
@var{reg-phys} must be a postive integer, or zero. If @var{reg-phys} is
equal to zero, the element is considered not to belong to any physical
entity.

@item @var{reg-elem}
is the tag of the elementary entity to which the element belongs;
@var{reg-elem} must be a postive (non-zero) integer.

@item @var{number-of-nodes}
is the number of nodes for the @var{n}-th element. This is redundant, but
kept for backward compatibility.

@item @var{node-number-list}
is the list of the @var{number-of-nodes} node numbers of the @var{n}-th
element. The ordering of the nodes is given in @ref{Node ordering}.
@end table

@c .........................................................................
@c POS ASCII file format
@c .........................................................................

@node POS ASCII file format, POS binary file format, MSH file format version 1, Legacy formats
@subsection POS ASCII file format (Legacy)

The POS ASCII file is Gmsh's old native post-processing format, now
superseded by the format described in @ref{MSH file format (version 4)}. It is
defined as follows:

@example
$PostFormat
1.4 @var{file-type} @var{data-size}
$EndPostFormat
$View
@var{view-name} @var{nb-time-steps}
@var{nb-scalar-points} @var{nb-vector-points} @var{nb-tensor-points}
@var{nb-scalar-lines} @var{nb-vector-lines} @var{nb-tensor-lines}
@var{nb-scalar-triangles} @var{nb-vector-triangles} @var{nb-tensor-triangles}
@var{nb-scalar-quadrangles} @var{nb-vector-quadrangles} @var{nb-tensor-quadrangles}
@var{nb-scalar-tetrahedra} @var{nb-vector-tetrahedra} @var{nb-tensor-tetrahedra}
@var{nb-scalar-hexahedra} @var{nb-vector-hexahedra} @var{nb-tensor-hexahedra}
@var{nb-scalar-prisms} @var{nb-vector-prisms} @var{nb-tensor-prisms}
@var{nb-scalar-pyramids} @var{nb-vector-pyramids} @var{nb-tensor-pyramids}
@var{nb-scalar-lines2} @var{nb-vector-lines2} @var{nb-tensor-lines2}
@var{nb-scalar-triangles2} @var{nb-vector-triangles2} @var{nb-tensor-triangles2}
@var{nb-scalar-quadrangles2} @var{nb-vector-quadrangles2} @var{nb-tensor-quadrangles2}
@var{nb-scalar-tetrahedra2} @var{nb-vector-tetrahedra2} @var{nb-tensor-tetrahedra2}
@var{nb-scalar-hexahedra2} @var{nb-vector-hexahedra2} @var{nb-tensor-hexahedra2}
@var{nb-scalar-prisms2} @var{nb-vector-prisms2} @var{nb-tensor-prisms2}
@var{nb-scalar-pyramids2} @var{nb-vector-pyramids2} @var{nb-tensor-pyramids2}
@var{nb-text2d} @var{nb-text2d-chars} @var{nb-text3d} @var{nb-text3d-chars}
@var{time-step-values}
< @var{scalar-point-value} > @dots{} < @var{vector-point-value} > @dots{}
    < @var{tensor-point-value} > @dots{}
< @var{scalar-line-value} > @dots{} < @var{vector-line-value} > @dots{}
    < @var{tensor-line-value} > @dots{}
< @var{scalar-triangle-value} > @dots{} < @var{vector-triangle-value} > @dots{}
    < @var{tensor-triangle-value} > @dots{}
< @var{scalar-quadrangle-value} > @dots{} < @var{vector-quadrangle-value} > @dots{}
    < @var{tensor-quadrangle-value} > @dots{}
< @var{scalar-tetrahedron-value} > @dots{} < @var{vector-tetrahedron-value} > @dots{}
    < @var{tensor-tetrahedron-value} > @dots{}
< @var{scalar-hexahedron-value} > @dots{} < @var{vector-hexahedron-value} > @dots{}
    < @var{tensor-hexahedron-value} > @dots{}
< @var{scalar-prism-value} > @dots{} < @var{vector-prism-value} > @dots{}
    < @var{tensor-prism-value} > @dots{}
< @var{scalar-pyramid-value} > @dots{} < @var{vector-pyramid-value} > @dots{}
    < @var{tensor-pyramid-value} > @dots{}
< @var{scalar-line2-value} > @dots{} < @var{vector-line2-value} > @dots{}
    < @var{tensor-line2-value} > @dots{}
< @var{scalar-triangle2-value} > @dots{} < @var{vector-triangle2-value} > @dots{}
    < @var{tensor-triangle2-value} > @dots{}
< @var{scalar-quadrangle2-value} > @dots{} < @var{vector-quadrangle2-value} > @dots{}
    < @var{tensor-quadrangle2-value} > @dots{}
< @var{scalar-tetrahedron2-value} > @dots{} < @var{vector-tetrahedron2-value} > @dots{}
    < @var{tensor-tetrahedron2-value} > @dots{}
< @var{scalar-hexahedron2-value} > @dots{} < @var{vector-hexahedron2-value} > @dots{}
    < @var{tensor-hexahedron2-value} > @dots{}
< @var{scalar-prism2-value} > @dots{} < @var{vector-prism2-value} > @dots{}
    < @var{tensor-prism2-value} > @dots{}
< @var{scalar-pyramid2-value} > @dots{} < @var{vector-pyramid2-value} > @dots{}
    < @var{tensor-pyramid2-value} > @dots{}
< @var{text2d} > @dots{} < @var{text2d-chars} > @dots{}
< @var{text3d} > @dots{} < @var{text3d-chars} > @dots{}
$EndView
@end example

@noindent
where
@table @code
@item @var{file-type}
is an integer equal to 0 in the ASCII file format.

@item @var{data-size}
is an integer equal to the size of the floating point numbers used in the
file (usually, @var{data-size} = sizeof(double)).

@item @var{view-name}
is a string containing the name of the view (max. 256 characters).

@item @var{nb-time-steps}
is an integer giving the number of time steps in the view.

@item @var{nb-scalar-points}
@item @var{nb-vector-points}
@item @dots{}
are integers giving the number of scalar points, vector points, @dots{}, in
the view.

@item @var{nb-text2d}
@item @var{nb-text3d}
are integers giving the number of 2D and 3D text strings in the
view.

@item @var{nb-text2d-chars}
@item @var{nb-text3d-chars}
are integers giving the total number of characters in the 2D and 3D strings.

@item @var{time-step-values}
is a list of @var{nb-time-steps} double precision numbers giving the value
of the time (or any other variable) for which an evolution was saved.

@item @var{scalar-point-value}
@item @var{vector-point-value}
@item @dots{}
are lists of double precision numbers giving the node coordinates and the
values associated with the nodes of the @var{nb-scalar-points} scalar
points, @var{nb-vector-points} vector points, @dots{}, for each of the
@var{time-step-values}.

For example, @var{vector-triangle-value} is defined as:
@example
@var{coord1-node1} @var{coord1-node2} @var{coord1-node3}
@var{coord2-node1} @var{coord2-node2} @var{coord2-node3}
@var{coord3-node1} @var{coord3-node2} @var{coord3-node3}
@var{comp1-node1-time1} @var{comp2-node1-time1} @var{comp3-node1-time1}
@var{comp1-node2-time1} @var{comp2-node2-time1} @var{comp3-node2-time1}
@var{comp1-node3-time1} @var{comp2-node3-time1} @var{comp3-node3-time1}
@var{comp1-node1-time2} @var{comp2-node1-time2} @var{comp3-node1-time2}
@var{comp1-node2-time2} @var{comp2-node2-time2} @var{comp3-node2-time2}
@var{comp1-node3-time2} @var{comp2-node3-time2} @var{comp3-node3-time2}
@dots{}
@end example

The ordering of the nodes is given in @ref{Node ordering}.

@item @var{text2d}
is a list of 4 double precision numbers:
@example
@var{coord1} @var{coord2} @var{style} @var{index}
@end example
where @var{coord1} and @var{coord2} give the X-Y position of the 2D string
in screen coordinates (measured from the top-left corner of the window) and
where @var{index} gives the starting index of the string in
@var{text2d-chars}. If @var{coord1} (respectively @var{coord2}) is negative,
the position is measured from the right (respectively bottom) edge of the
window. If @var{coord1} (respectively @var{coord2}) is larger than 99999,
the string is centered horizontally (respectively vertically).  If
@var{style} is equal to zero, the text is aligned bottom-left and displayed
using the default font and size. Otherwise, @var{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).

@item @var{text2d-chars}
is a list of @var{nb-text2d-chars} characters. Substrings are separated with
the null `@code{\0}' character.

@item @var{text3d}
is a list of 5 double precision numbers
@example
@var{coord1} @var{coord2} @var{coord3} @var{style} @var{index}
@end example
where @var{coord1}, @var{coord2} and @var{coord3} give the XYZ coordinates
of the string in model (real world) coordinates, @var{index} gives the
starting index of the string in @var{text3d-chars}, and @var{style} has the
same meaning as in @var{text2d}.

@item @var{text3d-chars}
is a list of @var{nb-text3d-chars} chars. Substrings are separated with the
null `@code{\0}' character.
@end table

@c .........................................................................
@c POS binary file format
@c .........................................................................

@node POS binary file format,  , POS ASCII file format, Legacy formats
@subsection POS binary file format (Legacy)

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

@enumerate
@item
@var{file-type} equals 1.
@item
all lists of floating point numbers and characters are written in binary
format
@item
there is an additional integer, of value 1, written before
@var{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).
@end enumerate

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

@example
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");
@end example
In this pseudo-code, @var{all-scalar-point-values} is the array of double
precision numbers containing all the @var{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.

@c =========================================================================
@c Tutorial
@c =========================================================================

@node Tutorial, Options, File formats, Top
@appendix Tutorial

@cindex Examples
@cindex Tutorial

The following examples introduce new features gradually, starting with
@ref{t1.geo}. The files corresponding to these examples are available in
the
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial,tutorial}
directory of the Gmsh distribution.

To learn how to run Gmsh on your computer, see @ref{Running Gmsh on your
system}. Screencasts that show how to use the GUI are available on
@uref{http://gmsh.info/screencasts/}.

@menu
* t1.geo::
* t2.geo::
* t3.geo::
* t4.geo::
* t5.geo::
* t6.geo::
* t7.geo::
* t8.geo::
* t9.geo::
* t10.geo::
* t11.geo::
* t12.geo::
* t13.geo::
* t14.geo::
* t15.geo::
* t16.geo::
@end menu

@c -------------------------------------------------------------------------
@c t1.geo
@c -------------------------------------------------------------------------

@node t1.geo, t2.geo, Tutorial, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t1.geo,t1.geo}

@verbatiminclude ../../tutorial/t1.geo

@c -------------------------------------------------------------------------
@c t2.geo
@c -------------------------------------------------------------------------

@node t2.geo, t3.geo, t1.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t2.geo,t2.geo}

@verbatiminclude ../../tutorial/t2.geo

@c -------------------------------------------------------------------------
@c t3.geo
@c -------------------------------------------------------------------------

@node t3.geo, t4.geo, t2.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t3.geo,t3.geo}

@verbatiminclude ../../tutorial/t3.geo

@c -------------------------------------------------------------------------
@c t4.geo
@c -------------------------------------------------------------------------

@node t4.geo, t5.geo, t3.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t4.geo,t4.geo}

@verbatiminclude ../../tutorial/t4.geo

@c -------------------------------------------------------------------------
@c t5.geo
@c -------------------------------------------------------------------------

@node t5.geo, t6.geo, t4.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t5.geo,t5.geo}

@verbatiminclude ../../tutorial/t5.geo

@c -------------------------------------------------------------------------
@c t6.geo
@c -------------------------------------------------------------------------

@node t6.geo, t7.geo, t5.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t6.geo,t6.geo}

@verbatiminclude ../../tutorial/t6.geo

@c -------------------------------------------------------------------------
@c t7.geo
@c -------------------------------------------------------------------------

@node t7.geo, t8.geo, t6.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t7.geo,t7.geo}

@verbatiminclude ../../tutorial/t7.geo

@c -------------------------------------------------------------------------
@c t8.geo
@c -------------------------------------------------------------------------

@node t8.geo, t9.geo, t7.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t8.geo,t8.geo}

@verbatiminclude ../../tutorial/t8.geo

@c -------------------------------------------------------------------------
@c t9.geo
@c -------------------------------------------------------------------------

@node t9.geo, t10.geo, t8.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t9.geo,t9.geo}

@verbatiminclude ../../tutorial/t9.geo

@c -------------------------------------------------------------------------
@c t10.geo
@c -------------------------------------------------------------------------

@node t10.geo, t11.geo, t9.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t10.geo,t10.geo}

@verbatiminclude ../../tutorial/t10.geo

@c -------------------------------------------------------------------------
@c t11.geo
@c -------------------------------------------------------------------------

@node t11.geo, t12.geo, t10.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t11.geo,t11.geo}

@verbatiminclude ../../tutorial/t11.geo

@c -------------------------------------------------------------------------
@c t12.geo
@c -------------------------------------------------------------------------

@node t12.geo, t13.geo, t11.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t12.geo,t12.geo}

@verbatiminclude ../../tutorial/t12.geo

@c -------------------------------------------------------------------------
@c t13.geo
@c -------------------------------------------------------------------------

@node t13.geo, t14.geo, t12.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t13.geo,t13.geo}

@verbatiminclude ../../tutorial/t13.geo

@c -------------------------------------------------------------------------
@c t14.geo
@c -------------------------------------------------------------------------

@node t14.geo, t15.geo, t13.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t14.geo,t14.geo}

@verbatiminclude ../../tutorial/t14.geo

@c -------------------------------------------------------------------------
@c t15.geo
@c -------------------------------------------------------------------------

@node t15.geo, t16.geo, t14.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t15.geo,t15.geo}

@verbatiminclude ../../tutorial/t15.geo

@c -------------------------------------------------------------------------
@c t16.geo
@c -------------------------------------------------------------------------

@node t16.geo,  , t15.geo, Tutorial
@section @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/tutorial/t16.geo,t16.geo}

@verbatiminclude ../../tutorial/t16.geo

@c =========================================================================
@c Options
@c =========================================================================

@node Options, Compiling the source code, Tutorial, Top
@appendix 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: @code{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: @code{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->Export', or when saving per-model options with
`File->Save Options->For Current File' (cf. ``Saved in: @code{-}'' 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
@code{General.SessionFileName} and @code{General.OptionsFileName} files
by hand.

@c All the included files are generated automatically with `gmsh -doc'

@menu
* General options list::
* Geometry options list::
* Mesh options list::
* Solver options list::
* Post-processing options list::
@end menu

@c -------------------------------------------------------------------------
@c General options list
@c -------------------------------------------------------------------------

@node General options list, Geometry options list, Options, Options
@section General options list

@include opt_general.texi

@include opt_print.texi

@c -------------------------------------------------------------------------
@c Geometry options list
@c -------------------------------------------------------------------------

@node Geometry options list, Mesh options list, General options list, Options
@section Geometry options list

@include opt_geometry.texi

@c -------------------------------------------------------------------------
@c Mesh options list
@c -------------------------------------------------------------------------

@node Mesh options list, Solver options list, Geometry options list, Options
@section Mesh options list

@include opt_mesh.texi

@c -------------------------------------------------------------------------
@c Solver options list
@c -------------------------------------------------------------------------

@node Solver options list, Post-processing options list, Mesh options list, Options
@section Solver options list

@include opt_solver.texi

@c -------------------------------------------------------------------------
@c Post-processing options list
@c -------------------------------------------------------------------------

@node Post-processing options list,  , Solver options list, Options
@section Post-processing options list

@include opt_post.texi

@include opt_view.texi

@c todo:
@c @sp 1
@c The @code{ColorTable} is defined as a list...

@c =========================================================================
@c Compiling the source code
@c =========================================================================

@node Compiling the source code, Gmsh API, Options, Top
@appendix Compiling the source code

Stable releases and source snapshots are available from
@url{http://gmsh.info/src/}. You can also access the Git repository
directly:

@enumerate
@item
The first time you want to download the latest full source, type:

@example
git clone @url{https://gitlab.onelab.info/gmsh/gmsh.git}
@end example

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

@example
git pull
@end example

@end enumerate

Once you have the source code, you need to run CMake to configure your
build (see the
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/README.txt,README.txt}
file in the top-level source directory for detailed information on how
to run CMake).

Each build can be configured using a series of options, to selectively
enable optional modules or features. Here is the list of CMake options:

@ftable @code

@include cmake_options.texi

@end ftable

@c =========================================================================
@c Gmsh API
@c =========================================================================

@node Gmsh API, Information for developers, Compiling the source code, Top
@appendix Gmsh API

@cindex API
@cindex Programming, API

The Gmsh Application Programming Interface (API) allows you to integrate
the Gmsh library in your own application. Examples on how to use the API
are available in the
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/demos/api/,demos/api}
directory. In particular, this directory contains C++, C, Python and
Julia versions of several of the @code{.geo} tutorials from
@ref{Tutorial}.

By design, the Gmsh API is purely functional, and only uses elementary
types from the target language. Currently supported languages are C++,
C, Python and Julia. The different versions of the API are generated
automatically from the master API definition file
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/api/gen.py,api/gen.py}:

@itemize @bullet
@item C++ API: @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/api/gmsh.h,gmsh.h}
@item C API: @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/api/gmshc.h,gmshc.h}
@item Python API: @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/api/gmsh.py,gmsh.py}
@item Julia API: @url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/api/gmsh.jl,gmsh.jl}
@end itemize

The additional
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/api/gmsh.h_cwrap,gmsh.h_cwrap}
header redefines the C++ API in terms of the C API. This is provided as
a convenience for users of the @url{http://gmsh.info/bin,binary Gmsh
Software Development Kit (SDK)} whose C++ compiler Application Binary
Interface (ABI) is not compatible with the ABI of the C++ compiler used
to create the SDK. To use these C++ bindings of the C API instead of the
native C++ API, simply rename @code{gmsh.h_cwrap} as @code{gmsh.h}. Note
that this will lead to (slightly) reduced performance compared to using
the native Gmsh C++ API, as it entails additional data copies between
the C++ wrapper, the C API and the native C++ code.

The functions available in the API are given below (see the relevant
header/module file for the exact definition in each supported
language@footnote{In C++ @code{/gmsh/model/geo/addPoint} will lead to a
namespaced function @code{gmsh::model::geo::addPoint}, while in Python
and Julia it will lead to @code{gmsh.model.geo.addPoint}, and in C to
@code{gmshModelGeoAddPoint}. Output values are passed by reference in
C++, as pointers in C and directly returned (after the return value, if
any) in Python and Julia.}):

@include api.texi

@c =========================================================================
@c Information for developers
@c =========================================================================

@node Information for developers, Frequently asked questions, Gmsh API, Top
@appendix Information for developers

@cindex Developer, information
@cindex Programming, notes

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 (@uref{http://www.fltk.org}) for the widget
set. Gmsh's build system is based on CMake
(@uref{http://www.cmake.org}). Practical notes on how to compile Gmsh's
source code is provided in @ref{Compiling the source code} (see also
@ref{Frequently asked questions}).

This section is for developers who would like to contribute directly to
the Gmsh source code. Gmsh's official GIT repository is located at
@uref{https://gitlab.onelab.info/gmsh/gmsh}. The wiki
(@uref{https://gitlab.onelab.info/gmsh/gmsh/wikis/Git-cheat-sheet})
contains instructions on how to create feature branches and submit merge
requests.

@menu
* Source code structure::
* Coding style::
* Adding a new option::
@end menu

@c -------------------------------------------------------------------------
@c Source code structure
@c -------------------------------------------------------------------------

@node Source code structure, Coding style, Information for developers, Information for developers
@section Source code structure

Gmsh's code is structured in several subdirectories, roughly separated
between the four core modules
(@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Geo,Geo},
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Mesh,Mesh},
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Solver,Solver},
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Post,Post}) and associated
utilities (@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Common,Common},
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Numeric,Numeric}) on one hand, and
the graphics (@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Graphics,Graphics})
and interface (@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Fltk,Fltk},
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Parser,Parser}) code on the other.

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

@c -------------------------------------------------------------------------
@c Coding style
@c -------------------------------------------------------------------------

@node Coding style, Adding a new option, Source code structure, Information for developers
@section 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:

@enumerate
@item
See @uref{https://gitlab.onelab.info/gmsh/gmsh/wikis/Git-cheat-sheet}
for instructions on how to contribute to Gmsh's GIT source code
repository. All branches are tested; make sure that all tests pass and
that your code does not produce any warning before submitting merge
requests.
@item
Follow the style used in the existing code when adding something new:
indent using 2 spaces (never use tabs!), put 1 space after commas, put
opening braces for functions on a separate line, opening braces for
loops and tests on the same line, etc. You can use the
@code{clang-format} tool to apply these rules automatically (the rules
are defined in the
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/.clang-format,.clang-format}
file.)
@item
Always use the @code{Msg::} class to print information or errors
@item
Use memory checking tools to detect memory leaks and other nasty memory
problems. For example, you can use
@itemize @bullet
@item
Valgrind on Linux:
@example
valgrind --leak-check=yes --show-reachable=yes gmsh file.geo -3
@end example
@item
GMALLOC on Mac OS X:
@example
(gdb) set env DYLD_INSERT_LIBRARIES /usr/lib/libgmalloc.dylib
@end example
@item
LIBNJAMD:
@example
export LD_PRELOAD=libnjamd.so
kill -USR1
@end example
@item
Purify
@item
Memprof
@item
@dots{}
@end itemize
@end enumerate

@c -------------------------------------------------------------------------
@c Adding a new option
@c -------------------------------------------------------------------------

@node Adding a new option,  , Coding style, Information for developers
@section Adding a new option

To add a new option in Gmsh:

@enumerate
@item
create the option in the @code{CTX} class
(@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Common/Context.h,Common/Context.h}
if it's a classical option, or in the @code{PViewOptions} class
(@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Post/PViewOptions.h,Post/PViewOptions.h})
if it's a post-processing view-dependent option;
@item
in
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Common/DefaultOptions.h,Common/DefaultOptions.h},
give a name (for the parser to be able to access it), a reference to a
handling routine (i.e. @code{opt_XXX}) and a default value for this
option;
@item
create the handling routine @code{opt_XXX} in
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Common/Options.cpp,Common/Options.cpp}
(and add the prototype in
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Common/Options.h,Common/Options.h});
@item
optional: create the associated widget in
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Fltk/optionWindow.cpp,Fltk/optionWindow.h};
@end enumerate

@c =========================================================================
@c Frequently asked questions
@c =========================================================================

@node Frequently asked questions, Version history, Information for developers, Top
@appendix Frequently asked questions

@cindex Frequently asked questions
@cindex Questions, frequently asked
@cindex FAQ

@menu
* The basics::
* Installation problems::
* General questions::
* Geometry module questions::
* Mesh module questions::
* Solver module questions::
* Post-processing module questions::
@end menu

@c -------------------------------------------------------------------------
@c The basics
@c -------------------------------------------------------------------------

@node The basics, Installation problems, Frequently asked questions, Frequently asked questions
@section The basics

@enumerate
@item 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.

@item 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 @ref{License} for more information.

@item 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 @file{.msh}
extension.

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

@item Can I embed 'Gmsh' in my own software?

Yes, using the Gmsh API (@pxref{Gmsh API}). See @ref{Copying conditions}
for the licensing constraints.

@item Where can I find more information?

@url{http://gmsh.info} is the primary location to obtain information
about Gmsh. There you will for example find the complete reference
manual, a @url{https://gitlab.onelab.info/gmsh/gmsh/issues,bug tracking
database} and a searchable archive of the Gmsh mailing list
(@email{gmsh@@onelab.info}).
@end enumerate

@c -------------------------------------------------------------------------
@c Installation problems
@c -------------------------------------------------------------------------

@node Installation problems, General questions, The basics, Frequently asked questions
@section Installation problems

@enumerate
@item Which OSes does Gmsh run on?

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

@item 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 @url{http://www.mesa3d.org}.

@item How do I compile Gmsh from the source code?

You need cmake (@url{http://www.cmake.org}) and a C++ compiler. See
@ref{Compiling the source code} and the
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/README.txt,README.txt}
file in the top-level source directory for more information.

@item Where does Gmsh save its configuration files?

Gmsh will attempt to save temporary files and persistent configuration
options first in the @code{$GMSH_HOME} directory, then in
@code{$APPDATA} (on Windows) or @code{$HOME} (on other OSes), then in
@code{$TMP}, and finally in @code{$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.
@end enumerate

@c -------------------------------------------------------------------------
@c General questions
@c -------------------------------------------------------------------------

@node General questions, Geometry module questions, Installation problems, Frequently asked questions
@section General questions

@enumerate
@item Gmsh (from a binary distribution) complains about missing libraries.

On Windows, if your system complains about missing @file{OPENGL32.DLL}
or @file{GLU32.DLL} libraries, then OpenGL is not properly installed on
your machine. You can download OpenGL from Microsoft's web site, or
directly from @url{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.

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

Disable opaque move in your window manager.

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

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

@item How can I save GIF, JPEG, ..., images?

Just choose the appropriate format in `File->Export'. By default Gmsh
guesses the format from the file extension, so you can just type
@file{myfile.jpg} in the dialog and Gmsh will automatically create a JPEG
image file.

@item How can I save MPEG, AVI, ..., animations?

You can create simple MPEG animations by choosing MPEG as the format in
`File->Export': this allows you to loop over time steps or
post-processing data sets, or to change parameters according to
@code{Print.Parameter}. To create fully customized animations or to use
different output formats (AVI, MP4, etc.) you should write a
script. Have a look at @ref{t8.geo} or
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/demos/post_processing/anim.script,demos/post_processing/anim.script}
for some examples.

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

@item 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.
@end enumerate

@c -------------------------------------------------------------------------
@c Geometry module
@c -------------------------------------------------------------------------

@node Geometry module questions, Mesh module questions, General questions, Frequently asked questions
@section Geometry module

@enumerate
@item Does Gmsh support NURBS curves/surfaces?

Yes, but only with the OpenCASCADE kernel.

@item 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, curves 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:
@itemize
@item
you may save the unrolled geometry in another file (e.g. with gmsh
file.geo -0), and use this new file for subsequent computations;
@item
or you may set the @code{Geometry.AutoCoherence} option to 0. This will
prevent any automatic duplicate check/replacement. If you still need to
remove the duplicates entities, simply add @code{Coherence;} at strategic
locations in your geo files (e.g. before the creation of curve loops,
etc.).
@end itemize

@item 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 tag, interactively, or per window).

@item Can I edit STEP/IGES/BRep models?

Yes. With the OpenCASCADE kernel (@code{SetFactory("OpenCASCADE");}),
load the file (@code{Merge "file.step";} or @code{ShapeFromFile("file.step");})
and add the relevant scripting commands after that to delete parts,
create new parts or apply boolean operators.

@item How can I build modular geometries?

Define common geometrical objects and options in separate files or using
@code{Macro}, reusable in all your problem definition structures.

@item Some files take much more time to load with Gmsh 4 compared to Gmsh 3: what's happening?

In Gmsh 4, some operations (@code{Color}, @code{Show}, @code{Hide},
@code{BoundingBox}, @code{Boundary}, @code{PointsOf}, @code{Periodic},
@code{In} embedding constraints, ..) are now applied directly on the
internal Gmsh model, instead of being handled at the level of the CAD
kernel. This implies a synchronization between the CAD kernel and the
Gmsh model. To minimize the number of synchronizations (which can become
costly for large models), you should always create your geometry first;
and use these commands once the geometry has been created.

@end enumerate

@c -------------------------------------------------------------------------
@c Mesh module
@c -------------------------------------------------------------------------

@node Mesh module questions, Solver module questions, Geometry module questions, Frequently asked questions
@section Mesh module

@enumerate
@item What should I do when the 2D unstructured algorithm fails?

Verify that the curves in the model do not self-intersect. If
`@code{Mesh.RandomFactor} * size of triangle / size of model' approaches
machine accuracy, increase @code{Mesh.RandomFactor}.

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

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

@item How can I only save tetrahedral elements (not triangles and lines)?

By default, if physical groups are defined, the output mesh only
contains those elements that belong to physical entities. So to save
only 3D elements, simply define one (or more) physical volume(s) and
don't define any physical surfaces, physical curves or physical points.

@item 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 @emph{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 tags in the GUI with
`Tools->Options->Geometry->Visibility->Curve labels'). If there are
duplicates, try to change the geometrical tolerance and sew the faces
(see options in `Tools->Options->Geometry->General').

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

Use `Optimize quality' in the mesh menu.

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

@item Does Gmsh automatically couple unstructured tetrahedral meshes and structured hexahedral meshed using pyramids?

Only in simple geometrical cases. We need your help to improve this.

@item Can I explicitly assign region tags to extruded layers?

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

@item 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 @code{Mesh.Smoothing = 10}).

@item Does Gmsh support curved elements?

Yes, just choose the appropriate order in the mesh menu after the mesh is
completed. High order optimization tools are in development and also available
in the mesh menu. You can select the order on the command line with e.g.
@code{-order 2}.

@item 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
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/demos/simple_geo/sphere-discrete.geo,demos/simple_geo/sphere-discrete.geo}.

@item 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 groups (Physical Points, Physical Curves,
Physical Surfaces and Physical Volumes). See the reference manual as
well as the tutorials (in particular @ref{t1.geo}) for a detailed
description and some examples.

@item How can I display only the mesh associated with selected geometrical entities?

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

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

@item What is the signification of SICN, Gamma and SIGE in Tools->Statistics?

They measure the quality of the tetrahedra in a mesh:

@itemize
@item
SICN: signed inverse condition number
@item
Gamma: inscribed radius / circumscribed radius
@item
SIGE: signed inverse error on the gradient of FE solution
@end itemize

For the exact definitions, see
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/Geo/MElement.cpp,Geo/MElement.cpp}. The
graphs plot the the number of elements vs. the quality measure.

@item How can I save a mesh file with a given (e.g. older) MSH file format version?

@itemize
@item
In the GUI: open `File->Export', enter your @file{filename.msh} and then
pick the version in the dropdown menu.
@item
On the command line: use the @code{-format} option (e.g. @code{gmsh
file.geo -format msh2 -2}).
@item
In a @code{.geo} script: add the line @code{Mesh.MshFileVersion = x.y;}
for any version number @code{x.y}. You can also save this in your
default options.
@item
In the API: @code{gmsh::option::setNumber("Mesh.MshFileVersion", x.y)}.
@end itemize

As an alternative method, you can also not specify the format
explicitely, and just choose a filename with the @code{.msh2} or
@code{.msh4} extension.
@end enumerate

@c -------------------------------------------------------------------------
@c Solver module
@c -------------------------------------------------------------------------

@node Solver module questions, Post-processing module questions, Mesh module questions, Frequently asked questions
@section Solver module

@enumerate
@item How do I integrate my own solver with Gmsh?

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

@item 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
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/utils/misc/callgmsh.c,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 @code{-listen} command line option) and Gmsh
will always listen for your program on the Solver.SocketName socket.
@end enumerate

@c -------------------------------------------------------------------------
@c Post-processing module
@c -------------------------------------------------------------------------

@node Post-processing module questions,  , Solver module questions, Frequently asked questions
@section Post-processing module

@enumerate
@item How do I compute a section of a plot?

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

@item Can I save an isosurface to a file?

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

@item Can Gmsh generate isovolumes?

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

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

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

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

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

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

@item Is there a way to save animations?

You can save simple MPEG animations directly from the `File->Export'
menu. For other formats you should write a script. Have a look at
@ref{t8.geo} or
@url{https://gitlab.onelab.info/gmsh/gmsh/tree/master/demos/post_processing/anim.script,demos/post_processing/anim.script}
for some examples.

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

@item Can I do arithmetic operations on a view? Can I perform operations involving different views?

Yes, with the Evaluate plugin.

@item Some plugins seem to create empty views. What's wrong?

There can be several reasons:
@itemize
@item
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
@code{Plugin(DecomposeinSimplex)} to transform all quads, hexas, prisms
and pyramids into triangles and tetrahedra).
@item
the plugin might expect a mesh while all you provide is a point
cloud. In 2D, you can use @code{Plugin(Triangulate)} to transform a
point cloud into a triangulated surface. In 3D you can use
@code{Plugin(Tetrahedralize)}.
@item
the input parameters are out of range.
@end itemize

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

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

@item 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'.
@end enumerate


@c =========================================================================
@c Version history
@c =========================================================================

@node Version history, Copyright and credits, Frequently asked questions, Top
@appendix Version history

@cindex Versions
@cindex History, versions
@cindex Changelog

@verbatiminclude ../../CHANGELOG.txt

@c =========================================================================
@c Copyright and credits
@c =========================================================================

@node Copyright and credits, License, Version history, Top
@appendix Copyright and credits

@cindex Copyright
@cindex Acknowledgments
@cindex Contributors, list
@cindex Credits

@verbatiminclude ../../CREDITS.txt

@c =========================================================================
@c License
@c =========================================================================

@node License, Concept index, Copyright and credits, Top
@appendix License

@cindex License

@verbatiminclude ../../LICENSE.txt

@c =========================================================================
@c Concept Index (cindex)
@c =========================================================================

@node Concept index, Syntax index, License, Top
@unnumbered Concept index

@cindex Index, concepts
@cindex Concepts, index

@printindex cp

@c =========================================================================
@c Syntax Index (tindex+findex)
@c =========================================================================

@node Syntax index,  , Concept index, Top
@unnumbered Syntax index

@cindex Index, syntax
@cindex Syntax, index
@cindex Keywords, index

@printindex tp

@bye
