\input texinfo.tex @c -*-texinfo-*-
@c Gmsh - Copyright (C) 1997-2022 C. Geuzaine, J.-F. Remacle
@c
@c See the LICENSE.txt file in the Gmsh root directory for license information.
@c Please report all 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: cf. "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
@include version.texi
@set COPYRIGHT @copyright{} 1997-2022 Christophe Geuzaine, Jean-Fran@,{c}ois Remacle
@set SYN a synchronization of the CAD model with the internal Gmsh model.
@set SYNC This operation triggers @value{SYN}
@set SYNCS These operations all trigger @value{SYN}
@settitle Gmsh @value{GMSH-VERSION}
@footnotestyle separate
@setchapternewpage odd
@paragraphindent 0
@finalout
@afourpaper
@c %**end of header

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

@c remove \Underfull \hbox warnings
@tex
\global\hbadness=10000
@end tex

@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 @w{ }
@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
* Reporting a bug::             Where to report issues
* Overview of Gmsh::            High-level overview of Gmsh
* Gmsh tutorial::               A step-by-step tutorial for both @file{.geo} files and the API
* Gmsh graphical user interface::  Description of Gmsh's GUI
* Gmsh command-line interface::  Description of Gmsh's command-line interface
* Gmsh scripting language::     Description of Gmsh's built-in scripting language (@file{.geo} files)
* Gmsh application programming interface::  Description of Gmsh's multi-language API
* Gmsh options::                Description of all Gmsh options
* Gmsh mesh size fields::       Description of all Gmsh mesh size fields
* Gmsh plugins::                Description of all built-in Gmsh plugins
* Gmsh file formats::           Description of Gmsh's native file formats
* Compiling the source code::   Information on how to compile Gmsh from source
* 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 command-line, scripting and API syntax
@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 pre-compiled binary versions of Gmsh (for Windows,
macOS and Linux) can be downloaded from @uref{https://gmsh.info}.  Gmsh
packages are also directly available 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{https://gmsh.info}.

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

@node Copying conditions, Reporting a bug, Obtaining Gmsh, Top
@unnumbered Copying conditions

@cindex Copyright
@cindex License

Gmsh is @emph{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{https://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 Reporting a bug
@c =========================================================================

@node Reporting a bug, Overview of Gmsh, Copying conditions, Top
@unnumbered Reporting a bug

@cindex Issues, reporting
@cindex Bugs, reporting
@cindex Reporting bugs

If, after reading this reference manual, you think you have found a bug
in Gmsh, please file an issue on
@url{https://gitlab.onelab.info/gmsh/gmsh/issues}. Provide 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
your operation system.

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 Overview of Gmsh
@c =========================================================================

@node Overview of Gmsh, Gmsh tutorial, Reporting a bug, Top
@chapter Overview of Gmsh

@cindex Introduction
@cindex Overview

Gmsh is a three-dimensional finite element mesh 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
flexible visualization capabilities.

Gmsh is built around four modules (geometry, mesh, solver and
post-processing), which can be controlled with the graphical user
interface (GUI; see @ref{Gmsh graphical user interface}), from the
command line (@pxref{Gmsh command-line interface}), using text files
written in Gmsh's own scripting language (@file{.geo} files; see
@ref{Gmsh scripting language}), or through the C++, C, Python, Julia and
Fortran application programming interface (API; see @ref{Gmsh
application programming interface}).

A brief description of the four modules is given hereafter, before an
overview of what Gmsh does best (... and what it is not so good at), and
some practical information on how to install and run Gmsh on your
computer.

@menu
* Geometry module::
* Mesh module::
* Solver module::
* Post-processing module::
* What Gmsh is pretty good at::
* and what Gmsh is not so good at::
* Installing and running Gmsh on your computer::
@end menu

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

@node Geometry module, Mesh module, Overview of Gmsh, Overview of Gmsh
@section Geometry module

A model in Gmsh is defined using its Boundary Representation (BRep): a
volume is bounded by a set of surfaces, a surface is bounded by a series
of curves, and a curve is bounded by two end points. Model entities are
topological entities, i.e., they only deal with adjacencies in the
model, and are implemented as a set of abstract topological
classes. This BRep is extended by the definition of @emph{embedded}, or
internal, model entities: internal points, curves and surfaces can be
embedded in volumes; and internal points and curves can be embedded in
surfaces.

The geometry of model entities can be provided by different CAD
kernels. The two default kernels interfaced by Gmsh are the
@emph{built-in} kernel and the @emph{OpenCASCADE} kernel. Gmsh does not
translate the geometrical representation from one kernel to another, or
from these kernels to some neutral representation. Instead, Gmsh
directly queries the native data for each CAD kernel, which avoids data
loss and is crucial for complex models where translations invariably
introduce issues linked to slightly different representations. Selecting
the CAD kernel in @file{.geo} scripts is done with the @code{SetFactory}
command (@pxref{Geometry scripting commands}), while in the Gmsh API the
kernel appears explicitly in all the relevant functions from the
@code{gmsh/model} namespace, with @code{geo} or @code{occ} prefixes for
the built-in and OpenCASCADE kernel, respectively (@pxref{Namespace
gmsh/model}).

Entities can either be built in a @emph{bottom-up} manner (first points,
then curves, surfaces and volumes) with the built-in and OpenCASCADE
kernels, or in a @emph{top-down} constructive solid geometry fashion
(solids on which boolean operations are performed) with the OpenCASCADE
kernel. Both methodologies can also be combined. Finally, groups of
model entities (called ``physical groups'') can be defined, based on the
elementary geometric entities. (See @ref{Elementary entities vs physical
groups}, for more information about how physical groups affect the way
meshes are saved.)

Both model entities (also referred to as ``elementary entities'') and
physical groups are uniquely defined by a pair of integers: their
dimension (0 for points, 1 for curves, 2 for surfaces, 3 for volumes)
and their @emph{tag}, a strictly positive global identification
number. Entity and group tags are unique per dimension:
@enumerate
@item each point must possess a unique tag;
@item each curve must possess a unique tag;
@item each surface must possess a unique tag;
@item each volume must possess a unique tag.
@end enumerate
Zero or negative tags are reserved by Gmsh for internal use.

Model entities can be manipulated and transformed in a variety of ways
within the geometry module, but operations are always performed directly
within their respective CAD kernels. As explained above, there is no
common internal geometrical representation: rather, Gmsh directly
performs the operations (translation, rotation, intersection, union,
fragments, ...) on the native geometrical representation using each CAD
kernel's own API.  In the same philosophy, models can be imported in the
geometry module through each CAD kernel's own import mechanisms. For
example, by default Gmsh imports STEP and IGES files through
OpenCASCADE, which will lead to the creation of model entities with an
internal OpenCASCADE representation.

The @ref{Gmsh tutorial}, starting with @ref{t1}, is the best place to
learn how to use the geometry module: it contains examples of increasing
complexity based on both the built-in and the OpenCASCADE kernel.  Note
that many features of the geometry module can be used interactively in
the GUI (@pxref{Gmsh graphical user interface}), which is also a good
way to learn about both Gmsh's scripting language and the API, as
actions in the geometry module automatically append the related command
in the input script file, and can optionally also generate input for the
languages supported by the API (see the
@code{General.ScriptingLanguages} option; this is still work-in-progress
as of Gmsh 4.11.)

In addition to CAD-type geometrical entities, whose geometry is provided
by a CAD kernel, Gmsh also supports @emph{discrete} model entities,
which are defined by a mesh (e.g. STL). Gmsh does not perform
geometrical operations on such discrete entities, but they can be
equipped with a geometry through a so-called ``reparametrization''
procedure@footnote{P. A. Beaufort, C. Geuzaine, J.-F. Remacle
@emph{Automatic surface mesh generation for discrete models–A complete
and automatic pipeline based on reparametrization}. Journal of
Computational Physics, 417, 109575, 2020.}. The parametrization is then
used for meshing, in exactly the same way as for CAD entities. See
@ref{t13} for an example.

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

@node Mesh module, Solver module, Geometry module, Overview of Gmsh
@section Mesh module

A finite element mesh of a model is a tessellation of its geometry by
simple geometrical elements of various shapes (in Gmsh: 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. This defines a so-called
conformal mesh. The mesh module implements several algorithms to
generate such meshes automatically. By default, meshes produced by Gmsh
are considered as @emph{unstructured}, even if they were generated in a
@emph{structured} way (e.g., by extrusion). This implies that the mesh
elements are completely defined simply by an ordered list of their
nodes, and that no predefined ordering relation is assumed between any
two elements.

In order to guarantee the conformity of the mesh, mesh generation is
performed in a bottom-up flow: 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, unless entities
of lower dimensions are explicitly embedded in entities of higher
dimension. 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, or if that
surface has been explicitly embedded in the volume. This automatically
ensures the conformity of the mesh when, for example, two volumes share
a common surface. Every meshing step is constrained by a @emph{mesh size
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 mesh size fields (for
example related to the distance to some boundary, to a arbitrary scalar
field defined on another mesh, etc.): see @ref{Gmsh mesh size
fields}. For each meshing step, all structured mesh directives are
executed first, and serve as additional constraints for the unstructured
parts. (The generation and handling of conformal meshes has important
consequences on how meshes are stored internally in Gmsh, and how they
are accessed through the API: see @ref{Gmsh application programming
interface}.)

Gmsh's mesh module regroups several 1D, 2D and 3D meshing algorithms:

@itemize @bullet
@item
The 2D @emph{unstructured} algorithms generate triangles and/or
quadrangles (when recombination commands or options are used). The 3D
@emph{unstructured} algorithms generate tetrahedra, or tetrahedra and
pyramids (when the boundary mesh contains quadrangles).
@item
The 2D @emph{structured} algorithms (transfinite and extrusion) generate
triangles by default, but quadrangles can be obtained by using the
recombination commands or options. 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.SubdivisionAlgorithm} option
(@pxref{Mesh options}).

@menu
* Choosing the right unstructured algorithm::
* Specifying mesh element sizes::
* Elementary entities vs physical groups::
@end menu

@c .........................................................................
@c Choosing the right unstructured algorithm
@c .........................................................................

@node Choosing the right unstructured algorithm, Specifying mesh element sizes, Mesh module, Mesh module
@subsection Choosing the right unstructured algorithm

Gmsh provides a choice between several 2D and 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 several algorithms can be
applied to generate the final mesh:

@itemize
@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-Delaunay'' 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.}.
@item
Other experimental algorithms with specific features are also
available. In particular, ``Frontal-Delaunay for
Quads''@footnote{J.-F. Remacle, F. Henrotte, T. Carrier-Baudouin,
E. Béchet, E. Marchandise, C. Geuzaine and T. Mouton, @emph{A frontal
Delaunay quad mesh generator using the Linf norm}, International Journal
for Numerical Methods in Engineering, 94(5), pp. 494-512, 2013.} is a
variant of the ``Frontal-Delaunay'' algorithm aiming at generating
right-angle triangles suitable for recombination; and
``BAMG''@footnote{F. Hecht, @emph{BAMG: bidimensional anisotropic mesh
generator}, User Guide, INRIA, Rocquencourt, 1998.} allows to generate
anisotropic triangulations.
@end itemize

For very complex curved surfaces the ``MeshAdapt'' algorithm is the most
robust. When high element quality is important, the ``Frontal-Delaunay''
algorithm should be tried. For very large meshes of plane surfaces the
``Delaunay'' algorithm is the fastest; it usually also handles complex
mesh size fields better than the ``Frontal-Delaunay''.  When the
``Delaunay'' or ``Frontal-Delaunay'' algorithms fail, ``MeshAdapt'' is
automatically triggered. The ``Automatic'' algorithm uses ``Delaunay''
for plane surfaces and ``MeshAdapt'' for all other surfaces.

Several 3D unstructured algorithms are also available:

@itemize
@item
The ``Delaunay'' algorithm is split into three separate steps. First, an
initial mesh of the union of all the volumes in the model is performed,
without inserting points in the volume. The surface mesh is then
recovered using H. Si's boundary recovery algorithm Tetgen/BR. Then a
three-dimensional version of the 2D Delaunay algorithm described above
is applied to insert points in the volume to respect the mesh size
constraints.
@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.}.
@item
The ``HXT'' algorithm@footnote{C. Marot, J. Pellerin and J.‐F. Remacle,
@emph{One machine, one minute, three billion tetrahedra}, International
Journal for Numerical Methods in Engineering 117.9, pp 967-990, 2019.}
is a new efficient and parallel reimplementaton of the Delaunay
algorithm.
@item
Other experimental algorithms with specific features are also available.
In particular, ``MMG3D''@footnote{C. Dobrzynski, @emph{MMG3D: user
guide}, INRIA, 2012.}  allows to generate anisotropic
tetrahedralizations.
@end itemize

The ``Delaunay'' algorithm is currently the most robust and is the only
one that supports the automatic generation of hybrid meshes with
pyramids. Embedded model entities and general mesh size fields
(@pxref{Specifying mesh element sizes}) are currently only supported by
the ``Delaunay'' and ``HXT'' algorithms.

When Gmsh is configured with OpenMP support (@pxref{Compiling the source
code}), most of the meshing steps can be performed in parallel:
@itemize
@item
1D and 2D meshing is parallelized using a coarse-grained approach,
i.e. curves (resp. surfaces) are each meshed sequentially, but several
curves (resp. surfaces) can be meshed at the same time.
@item
3D meshing using HXT is parallelized using a fine-grained approach,
i.e. the actual meshing procedure for a single volume is done is
parallel.
@end itemize
The number of threads can be controlled with the @code{-nt} flag on the
command line (@pxref{Gmsh command-line interface}), or with the
@code{General.NumThreads}, @code{Mesh.MaxNumThreads1D},
@code{Mesh.MaxNumThreads2D} and @code{Mesh.MaxNumThreads3D} options (see
@ref{General options} and @ref{Mesh options}).

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

@node Specifying mesh element sizes, Elementary entities vs physical groups, Choosing the right unstructured algorithm, Mesh module
@subsection Specifying mesh element sizes

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

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

@enumerate
@item
First, if the options @code{Mesh.MeshSizeFromPoints} and
@code{Mesh.MeshSizeExtendFromBoundary} are set (they are by default; see
@ref{Mesh options}), you can simply specify desired mesh element sizes
at the geometrical points of the model. The size of the mesh elements
will then be computed by interpolating these values inside the domain
during mesh generation. 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 or use more
advanced methods explained below.
@item
Second, if @code{Mesh.MeshSizeFromCurvature} is set to a positive value
(it is set to 0 by default), the mesh will be adapted with respect to
the curvature of the model entities, the value giving the target number
of elements per 2 Pi radians.
@item
Next, you can specify a general target mesh size, expressed as a
combination of mesh size fields (@pxref{Gmsh mesh size fields}):
@itemize @bullet
@item
The @code{Box} field specifies the size of the elements inside and
outside of a parallelepipedic region.
@item
The @code{Distance} field specifies the size of the mesh according to
the distance to some model entities.
@item
The @code{MathEval} field specifies the size of the mesh using an
explicit mathematical function.
@item
The @code{PostView} field specifies an explicit background mesh in the
form of a scalar post-processing view (see @ref{Post-processing module},
and @ref{Gmsh 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, e.g. in an iterative
process of mesh adaptation).
@item
The @code{Min} field specifies the size as the minimum of the sizes
computed using other fields.
@item
@dots{}
@end itemize
@item
Mesh sizes are also constrained by structured meshing constraints
(e.g. transfinite or extruded meshes) as well as by any discrete model
entity that is not equipped with a geometry, and which will thus
preserve it mesh during mesh generation.
@item
Boundary mesh sizes are interpolated inside surfaces and/or volumes
depending on the value of @code{Mesh.MeshSizeExtendFromBoundary}.
@end enumerate

To determine the actual mesh size at any given point in the model, Gmsh
evaluates all the above mesh size constraints and selects the smallest
value. Using the Gmsh API, this value can then be further modified using
a C++, C, Python, Julia or Fortran mesh size callback function provided
via @code{gmsh/model/mesh/setSizeCallback} (@pxref{Namespace
gmsh/model/mesh}).

The resulting value is further constrained in the interval [
@code{Mesh.MeshSizeMin}, @code{Mesh.MeshSizeMax} ] (which can also be
provided on the command line with @code{-clmin} and @code{-clmax}). The
resulting value is then finally multiplied by @code{Mesh.MeshSizeFactor}
(@code{-clscale} on the command line).

Note that when the element size is fully specified by a mesh size field,
it is thus often desirable to set
@example
Mesh.MeshSizeFromPoints = 0;
Mesh.MeshSizeFromCurvature = 0;
Mesh.MeshSizeExtendFromBoundary = 0;
@end example
to prevent over-refinement inside an entity due to small mesh sizes on
its boundary.

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

@node Elementary entities vs physical groups,  , Specifying mesh element sizes, Mesh module
@subsection Elementary entities vs. physical groups

It is usually convenient to combine elementary 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 the definition of ``physical groups''.

By default in the native Gmsh MSH mesh file format (@pxref{Gmsh file
formats}), as well as in most other mesh formats, if physical groups are
defined, the output mesh only contains those elements that belong to at
least one physical group. (Different mesh file formats treat physical
groups in slightly different ways, depending on their capability to
define groups.) To save all mesh elements whether or not physical groups
are defined, use the @code{Mesh.SaveAll} option (@pxref{Mesh options})
or specify @code{-save_all} on the command line. In some formats
(e.g. MSH2), setting @code{Mesh.SaveAll} will however discard all
physical group definitions.

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

@node Solver module, Post-processing module, Mesh module, Overview of Gmsh
@section Solver module

Gmsh implements a ONELAB (@uref{http://onelab.info}) server to exchange
data with external solvers or other codes (called ``clients''). The
ONELAB interface allows to call such clients and have them share
parameters and modeling information.

The implementation is based on a client-server model, with a server-side
database and local or remote clients communicating in-memory or through
TCP/IP sockets. Contrary to most solver interfaces, the ONELAB server
has no a priori knowledge about any specifics (input file format,
syntax, ...) of the clients. This is made possible by having any
simulation preceded by an analysis phase, during which the clients are
asked to upload their parameter set to the server. The issues of
completeness and consistency of the parameter sets are completely dealt
with on the client side: the role of ONELAB is limited to data
centralization, modification and re-dispatching.

Using the Gmsh API, you can directly embed Gmsh in your C++, C, Python,
Julia or Fortran solver, use ONELAB for interactive parameter definition
and modification, and to create post-processing data on the fly. See
@url{@value{GITLAB-PREFIX}/examples/api/prepro.py,prepro.py},
@url{@value{GITLAB-PREFIX}/examples/api/custom_gui.py,custom_gui.py} and
@url{@value{GITLAB-PREFIX}/examples/api/custom_gui.cpp,custom_gui.cpp}
for examples.

If you prefer to keep codes separate, you can also communicate with Gmsh
through a socket by providing the solver name (@code{Solver.Name0},
@code{Solver.Name1}, etc.) and the path to the executable
(@code{Solver.Executable0}, @code{Solver.Executable1}, etc.). Parameters
can then be exchanged using the ONELAB protocol: see the
@url{@value{GITLAB-PREFIX}/utils/solvers,utils/solvers} directory for
examples. A full-featured solver interfaced in this manner is GetDP
(@uref{https://getdp.info}), a general finite element solver using mixed
finite elements.

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

@node Post-processing module, What Gmsh is pretty good at, Solver module, Overview of Gmsh
@section Post-processing module

The 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 -- see @ref{Post-processing scripting
commands}), in native MSH files (ASCII or binary files with @file{.msh}
extensions: see @ref{Gmsh file formats}), or in standard third-party
formats such as CGNS or MED. Datasets can also be directly imported
using the Gmsh API (@pxref{Namespace gmsh/view}).

Once loaded into Gmsh, scalar fields can be displayed as iso-curves,
iso-surfaces or color maps, whereas vector fields can be represented
either by three-dimensional arrows or by displacement maps. Tensor
fields can be displayed as Von-Mises effective stresses, min/max
eigenvalues, eigenvectors, ellipses or ellipsoids. (To display other
combinations of components, you can use the
@code{View.ForceNumComponents} option -- see @ref{Post-processing
options}.)

Each dataset, along with the visualization options, is called a
``post-processing view'', or simply 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 or its unique tag
in a script or in the API) or globally (see the
@code{PostProcessing.Link} option in @ref{Post-processing options}).
Possible operations on post-processing views include section
computation, offset, elevation, boundary and component extraction, color
map and range modification, animation, vector graphic output, etc.
These operations are either carried out nondestructively through the
modification of post-processing options, or can lead to the actual
modification of the view data or the creation of new views when done
using post-processing plugins (@pxref{Gmsh plugins}). Both can be fully
automated in scripts or through the API (see e.g., @ref{t8}, and
@ref{t9}).

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

@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 module, Overview of Gmsh
@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 with the
built-in scripting language, thanks to user-defined macros, loops,
conditionals and includes (see @ref{User-defined macros}, @ref{Loops and
conditionals}, and @ref{Other general commands}). For more advanced
geometries, using the Gmsh API (@pxref{Gmsh application programming
interface}) in the language of your choice (C++, C, Python, Julia or
Fortran) brings even greater flexibility, the only downside being that
you need to either compile your code (for C++, C and Fortran) or to
configure and install an interpreter (Python or Julia) in addition to
Gmsh. A binary Software Development Kit (SDK) is distributed on the Gmsh
web site to make the process easier (@pxref{Installing and running Gmsh
on your computer});
@item
parametrize these geometries. Gmsh's scripting language or the Gmsh API
enable all commands and command arguments to depend on previous
calculations. Using the OpenCASCADE geometry kernel, Gmsh gives access
to all the usual constructive solid geometry operations (see
e.g. @ref{t16});
@item
import geometries from other CAD software in standard exchange
formats. Gmsh uses OpenCASCADE to import such files, including label and
color information from STEP and IGES files (see e.g. @ref{t20});
@item
generate unstructured 1D, 2D and 3D simplicial (i.e., using line
segments, triangles and tetrahedra) finite element meshes (see @ref{Mesh
module}), with fine control over the element size (@pxref{Specifying
mesh element sizes});
@item
create simple extruded geometries and meshes, and allow to automatically
couple such structured meshes with unstructured ones (using a layer of
pyramids in 3D);
@item
generate high-order (curved) meshes that conform to the CAD model
geometry. High-order mesh optimization tools allow to guarantee the
validity of such curved meshes;
@item
interact with external solvers by defining ONELAB parameters, shared
between Gmsh and the solvers and easily modifiable in the GUI
(@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, and can generate complex animations (see e.g. @ref{t8});
@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;
@item
configure your preferred options. Gmsh has a large number of
configuration options that can be set interactively using the GUI,
scattered inside script files, changed through the API, set in per-user
configuration files and specified on the command line (@pxref{Gmsh
options});
@item
and do all the above on various platforms (Windows, macOS and Linux),
for free (@pxref{Copying conditions})!
@end itemize

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

@node and what Gmsh is not so good at, Installing and running Gmsh on your computer, What Gmsh is pretty good at, Overview of Gmsh
@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 graphical user interface is only exposing a limited number of the
available features, and many aspects of the interface could be enhanced
(especially manipulators).
@item
Your complaints about Gmsh here :-)
@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 Installing and running Gmsh on your computer
@c -------------------------------------------------------------------------

@node Installing and running Gmsh on your computer,  , and what Gmsh is not so good at, Overview of Gmsh
@section Installing and running Gmsh on your computer

@cindex Running Gmsh
@cindex Installation

Gmsh can be used either as a standalone application, or as a library.

As a standalone application, Gmsh can be controlled with the GUI
(@pxref{Gmsh graphical user interface}), through the command line
(@pxref{Gmsh command-line interface}) and through @file{.geo} script
files (@pxref{Gmsh scripting language}). In addition, the ONELAB
interface (@pxref{Solver module}) allows to interact with the Gmsh
application through Unix or TCP/IP sockets.  Binary versions of the Gmsh
app for Windows, Linux and macOS can be downloaded from
@url{https://gmsh.info/#Download}. Several Linux distributions also ship
the Gmsh app. See @ref{Compiling the source code} for instructions on
how to compile the Gmsh app from source.

As a library, Gmsh can still be used in the same way as the standalone
Gmsh app, but in addition it can also be embedded in external codes
using the Gmsh API (@pxref{Gmsh application programming interface}).
The API is available in C++, C, Python, Julia and Fortran.  A binary
Software Development Kit (SDK) for Windows, Linux and macOS, that
contains the dynamic Gmsh library and the associated header and module
files, can be downloaded from @url{https://gmsh.info/#Download}. Python
users can use
@example
pip install --upgrade gmsh
@end example
which will download the binary SDK and install the files in the
appropriate system directories. Several Linux distributions also ship
the Gmsh SDK. See @ref{Compiling the source code} for instructions on
how to compile the dynamic Gmsh library from source.

@c =========================================================================
@c Gmsh tutorial
@c =========================================================================

@node Gmsh tutorial, Gmsh graphical user interface, Overview of Gmsh, Top
@chapter Gmsh tutorial

@cindex Examples
@cindex Tutorial

The following tutorials introduce new features gradually, starting with
the first tutorial @code{t1} (@pxref{t1}). The corresponding files are
available in the @url{@value{GITLAB-PREFIX}/tutorials,tutorials}
directory of the Gmsh distribution.

The @file{.geo} files (e.g. @file{t1.geo}) are written in Gmsh's
built-in scripting language (@pxref{Gmsh scripting language}). You can
open them directly with the Gmsh app: in the GUI (@pxref{Gmsh graphical
user interface}), use the `File->Open' menu and select
e.g. @file{t1.geo}. Or on the command line, run
@example
> gmsh t1.geo
@end example
which will launch the GUI, or run
@example
> gmsh t1.geo -2
@end example
to perform 2D meshing in batch mode (@pxref{Gmsh command-line
interface}).

The @file{c++}, @file{c}, @file{python}, @file{julia} and @file{fortran}
subdirectories of the @url{@value{GITLAB-PREFIX}/tutorials,tutorials}
directory contain the C++, C, Python, Julia and Fortran versions of the
tutorials, written using the Gmsh API (@pxref{Gmsh application
programming interface}). You will need the Gmsh dynamic library and the
associated header files (for C++ and C) or modules (for Python, Julia
and Fortran) to run them (@pxref{Installing and running Gmsh on your
computer}). Each subdirectory contains additional information on how to
run the tutorials for each supported language.

All the tutorials starting with the letter @file{t} are available both
using the scripting language and the API. Extended tutorials, starting
with the letter @file{x}, introduce features that are only available
through the API.

Note that besides these tutorials, the Gmsh distribution contains many
other examples written using both the built-in scripting language and
the API: see @url{@value{GITLAB-PREFIX}/examples,examples} and
@url{@value{GITLAB-PREFIX}/benchmarks,benchmarks}.

@menu
* t1::                          Geometry basics, elementary entities, physical groups
* t2::                          Transformations, extruded geometries, volumes
* t3::                          Extruded meshes, ONELAB parameters, options
* t4::                          Built-in functions, holes in surfaces, annotations, entity colors
* t5::                          Mesh sizes, macros, loops, holes in volumes
* t6::                          Transfinite meshes, deleting entities
* t7::                          Background meshes
* t8::                          Post-processing, image export and animations
* t9::                          Plugins
* t10::                         Mesh size fields
* t11::                         Unstructured quadrangular meshes
* t12::                         Cross-patch meshing with compounds
* t13::                         Remeshing an STL file without an underlying CAD model
* t14::                         Homology and cohomology computation
* t15::                         Embedded points, lines and surfaces
* t16::                         Constructive Solid Geometry, OpenCASCADE geometry kernel
* t17::                         Anisotropic background mesh
* t18::                         Periodic meshes
* t19::                         Thrusections, fillets, pipes, mesh size from curvature
* t20::                         STEP import and manipulation, geometry partitioning
* t21::                         Mesh partitioning
* x1::                          Geometry and mesh data
* x2::                          Mesh import, discrete entities, hybrid models, terrain meshing
* x3::                          Post-processing data import: list-based
* x4::                          Post-processing data import: model-based
* x5::                          Additional geometrical data: parametrizations, normals, curvatures
* x6::                          Additional mesh data: integration points, Jacobians and basis functions
* x7::                          Additional mesh data: internal edges and faces
@end menu

@c -------------------------------------------------------------------------
@c t1
@c -------------------------------------------------------------------------

@node t1, t2, Gmsh tutorial, Gmsh tutorial
@section @code{t1}: Geometry basics, elementary entities, physical groups

See
@url{@value{GITLAB-PREFIX}/tutorials/t1.geo,t1.geo}. Also
available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t1.cpp,t1.cpp}),
C
(@url{@value{GITLAB-PREFIX}/tutorials/c/t1.c,t1.c}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t1.py,t1.py}),
Julia
(@url{@value{GITLAB-PREFIX}/tutorials/julia/t1.jl,t1.jl})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t1.f90,t1.f90}).

@center@image{images/t1,9cm,}

@format
@verbatiminclude ../../tutorials/t1.geo
@end format

@c -------------------------------------------------------------------------
@c t2
@c -------------------------------------------------------------------------

@node t2, t3, t1, Gmsh tutorial
@section @code{t2}: Transformations, extruded geometries, volumes

See
@url{@value{GITLAB-PREFIX}/tutorials/t2.geo,t2.geo}. Also
available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t2.cpp,t2.cpp}),
C
(@url{@value{GITLAB-PREFIX}/tutorials/c/t2.c,t2.c}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t2.py,t2.py}),
Julia
(@url{@value{GITLAB-PREFIX}/tutorials/julia/t2.jl,t2.jl})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t2.f90,t2.f90}).

@center@image{images/t2,9cm,}

@format
@verbatiminclude ../../tutorials/t2.geo
@end format

@c -------------------------------------------------------------------------
@c t3
@c -------------------------------------------------------------------------

@node t3, t4, t2, Gmsh tutorial
@section @code{t3}: Extruded meshes, ONELAB parameters, options

See
@url{@value{GITLAB-PREFIX}/tutorials/t3.geo,t3.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t3.cpp,t3.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t3.py,t3.py}),
Julia
(@url{@value{GITLAB-PREFIX}/tutorials/julia/t3.jl,t3.jl})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t3.f90,t3.f90}).

@center@image{images/t3,9cm,}

@format
@verbatiminclude ../../tutorials/t3.geo
@end format

@c -------------------------------------------------------------------------
@c t4
@c -------------------------------------------------------------------------

@node t4, t5, t3, Gmsh tutorial
@section @code{t4}: Built-in functions, holes in surfaces, annotations, entity colors

See
@url{@value{GITLAB-PREFIX}/tutorials/t4.geo,t4.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t4.cpp,t4.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t4.py,t4.py}),
Julia
(@url{@value{GITLAB-PREFIX}/tutorials/julia/t4.jl,t4.jl})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t4.f90,t4.f90}).

@center@image{images/t4,9cm,}

@format
@verbatiminclude ../../tutorials/t4.geo
@end format

@c -------------------------------------------------------------------------
@c t5
@c -------------------------------------------------------------------------

@node t5, t6, t4, Gmsh tutorial
@section @code{t5}: Mesh sizes, macros, loops, holes in volumes

See
@url{@value{GITLAB-PREFIX}/tutorials/t5.geo,t5.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t5.cpp,t5.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t5.py,t5.py}),
Julia
(@url{@value{GITLAB-PREFIX}/tutorials/julia/t5.jl,t5.jl})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t5.f90,t5.f90}).

@center@image{images/t5,9cm,}

@format
@verbatiminclude ../../tutorials/t5.geo
@end format

@c -------------------------------------------------------------------------
@c t6
@c -------------------------------------------------------------------------

@node t6, t7, t5, Gmsh tutorial
@section @code{t6}: Transfinite meshes, deleting entities

See
@url{@value{GITLAB-PREFIX}/tutorials/t6.geo,t6.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t6.cpp,t6.cpp}),
C
(@url{@value{GITLAB-PREFIX}/tutorials/c/t6.c,t6.c}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t6.py,t6.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t6.f90,t6.f90}).

@center@image{images/t6,9cm,}

@format
@verbatiminclude ../../tutorials/t6.geo
@end format

@c -------------------------------------------------------------------------
@c t7
@c -------------------------------------------------------------------------

@node t7, t8, t6, Gmsh tutorial
@section @code{t7}: Background meshes

See
@url{@value{GITLAB-PREFIX}/tutorials/t7.geo,t7.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t7.cpp,t7.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t7.py,t7.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t7.f90,t7.f90}).

@center@image{images/t7,9cm,}

@format
@verbatiminclude ../../tutorials/t7.geo
@end format

@c -------------------------------------------------------------------------
@c t8
@c -------------------------------------------------------------------------

@node t8, t9, t7, Gmsh tutorial
@section @code{t8}: Post-processing, image export and animations

See
@url{@value{GITLAB-PREFIX}/tutorials/t8.geo,t8.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t8.cpp,t8.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t8.py,t8.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t8.f90,t8.f90}).

@center@image{images/t8,9cm,}

@format
@verbatiminclude ../../tutorials/t8.geo
@end format

@c -------------------------------------------------------------------------
@c t9
@c -------------------------------------------------------------------------

@node t9, t10, t8, Gmsh tutorial
@section @code{t9}: Plugins

See
@url{@value{GITLAB-PREFIX}/tutorials/t9.geo,t9.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t9.cpp,t9.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t9.py,t9.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t9.f90,t9.f90}).

@center@image{images/t9,9cm,}

@format
@verbatiminclude ../../tutorials/t9.geo
@end format

@c -------------------------------------------------------------------------
@c t10
@c -------------------------------------------------------------------------

@node t10, t11, t9, Gmsh tutorial
@section @code{t10}: Mesh size fields

See
@url{@value{GITLAB-PREFIX}/tutorials/t10.geo,t10.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t10.cpp,t10.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t10.py,t10.py}),
Julia
(@url{@value{GITLAB-PREFIX}/tutorials/julia/t10.jl,t10.jl})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t10.f90,t10.f90}).

@center@image{images/t10,9cm,}

@format
@verbatiminclude ../../tutorials/t10.geo
@end format

@c -------------------------------------------------------------------------
@c t11
@c -------------------------------------------------------------------------

@node t11, t12, t10, Gmsh tutorial
@section @code{t11}: Unstructured quadrangular meshes

See
@url{@value{GITLAB-PREFIX}/tutorials/t11.geo,t11.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t11.cpp,t11.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t11.py,t11.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t11.f90,t11.f90}).

@center@image{images/t11,9cm,}

@format
@verbatiminclude ../../tutorials/t11.geo
@end format

@c -------------------------------------------------------------------------
@c t12
@c -------------------------------------------------------------------------

@node t12, t13, t11, Gmsh tutorial
@section @code{t12}: Cross-patch meshing with compounds

See
@url{@value{GITLAB-PREFIX}/tutorials/t12.geo,t12.geo}/
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t12.cpp,t12.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t12.py,t12.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t12.f90,t12.f90}).

@center@image{images/t12,9cm,}

@format
@verbatiminclude ../../tutorials/t12.geo
@end format

@c -------------------------------------------------------------------------
@c t13
@c -------------------------------------------------------------------------

@node t13, t14, t12, Gmsh tutorial
@section @code{t13}: Remeshing an STL file without an underlying CAD model

See
@url{@value{GITLAB-PREFIX}/tutorials/t13.geo,t13.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t13.cpp,t13.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t13.py,t13.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t13.f90,t13.f90}).

@center@image{images/t13,9cm,}

@format
@verbatiminclude ../../tutorials/t13.geo
@end format

@c -------------------------------------------------------------------------
@c t14
@c -------------------------------------------------------------------------

@node t14, t15, t13, Gmsh tutorial
@section @code{t14}: Homology and cohomology computation

See
@url{@value{GITLAB-PREFIX}/tutorials/t14.geo,t14.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t14.cpp,t14.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t14.py,t14.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t14.f90,t14.f90}).

@center@image{images/t14,9cm,}

@format
@verbatiminclude ../../tutorials/t14.geo
@end format

@c -------------------------------------------------------------------------
@c t15
@c -------------------------------------------------------------------------

@node t15, t16, t14, Gmsh tutorial
@section @code{t15}: Embedded points, lines and surfaces

See
@url{@value{GITLAB-PREFIX}/tutorials/t15.geo,t15.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t15.cpp,t15.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t15.py,t15.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t15.f90,t15.f90}).

@center@image{images/t15,9cm,}

@format
@verbatiminclude ../../tutorials/t15.geo
@end format

@c -------------------------------------------------------------------------
@c t16
@c -------------------------------------------------------------------------

@node t16, t17, t15, Gmsh tutorial
@section @code{t16}: Constructive Solid Geometry, OpenCASCADE geometry kernel

See
@url{@value{GITLAB-PREFIX}/tutorials/t16.geo,t16.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t16.cpp,t16.cpp}),
C
(@url{@value{GITLAB-PREFIX}/tutorials/c/t16.c,t16.c}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t16.py,t16.py}),
Julia
(@url{@value{GITLAB-PREFIX}/tutorials/julia/t16.jl,t16.jl})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t16.f90,t16.f90}).

@center@image{images/t16,9cm,}

@format
@verbatiminclude ../../tutorials/t16.geo
@end format

@c -------------------------------------------------------------------------
@c t17
@c -------------------------------------------------------------------------

@node t17, t18, t16, Gmsh tutorial
@section @code{t17}: Anisotropic background mesh

See
@url{@value{GITLAB-PREFIX}/tutorials/t17.geo,t17.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t17.cpp,t17.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t17.py,t17.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t17.f90,t17.f90}).

@center@image{images/t17,9cm,}

@format
@verbatiminclude ../../tutorials/t17.geo
@end format

@c -------------------------------------------------------------------------
@c t18
@c -------------------------------------------------------------------------

@node t18, t19, t17, Gmsh tutorial
@section @code{t18}: Periodic meshes

See
@url{@value{GITLAB-PREFIX}/tutorials/t18.geo,t18.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t18.cpp,t18.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t18.py,t18.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t18.f90,t18.f90}).

@center@image{images/t18,9cm,}

@format
@verbatiminclude ../../tutorials/t18.geo
@end format

@c -------------------------------------------------------------------------
@c t19
@c -------------------------------------------------------------------------

@node t19, t20, t18, Gmsh tutorial
@section @code{t19}: Thrusections, fillets, pipes, mesh size from curvature

See
@url{@value{GITLAB-PREFIX}/tutorials/t19.geo,t19.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t19.cpp,t19.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t19.py,t19.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t19.f90,t19.f90}).

@center@image{images/t19,9cm,}

@format
@verbatiminclude ../../tutorials/t19.geo
@end format

@c -------------------------------------------------------------------------
@c t20
@c -------------------------------------------------------------------------

@node t20, t21, t19, Gmsh tutorial
@section @code{t20}: STEP import and manipulation, geometry partitioning

See
@url{@value{GITLAB-PREFIX}/tutorials/t20.geo,t20.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t20.cpp,t20.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t20.py,t20.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t20.f90,t20.f90}).

@center@image{images/t20,9cm,}

@format
@verbatiminclude ../../tutorials/t20.geo
@end format

@c -------------------------------------------------------------------------
@c t21
@c -------------------------------------------------------------------------

@node t21, x1, t20, Gmsh tutorial
@section @code{t21}: Mesh partitioning

See
@url{@value{GITLAB-PREFIX}/tutorials/t21.geo,t21.geo}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/t21.cpp,t21.cpp}),
Python
(@url{@value{GITLAB-PREFIX}/tutorials/python/t21.py,t21.py})
and Fortran
(@url{@value{GITLAB-PREFIX}/tutorials/fortran/t21.f90,t21.f90}).

@center@image{images/t21,9cm,}

@format
@verbatiminclude ../../tutorials/t21.geo
@end format

@c -------------------------------------------------------------------------
@c x1
@c -------------------------------------------------------------------------

@node x1, x2, t21, Gmsh tutorial
@section @code{x1}: Geometry and mesh data

See
@url{@value{GITLAB-PREFIX}/tutorials/python/x1.py,x1.py}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/x1.cpp,x1.cpp}).

@format
@verbatiminclude ../../tutorials/python/x1.py
@end format

@c -------------------------------------------------------------------------
@c x2
@c -------------------------------------------------------------------------

@node x2, x3, x1, Gmsh tutorial
@section @code{x2}: Mesh import, discrete entities, hybrid models, terrain meshing

See
@url{@value{GITLAB-PREFIX}/tutorials/python/x2.py,x2.py}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/x2.cpp,x2.cpp}).

@center@image{images/x2,9cm,}

@format
@verbatiminclude ../../tutorials/python/x2.py
@end format

@c -------------------------------------------------------------------------
@c x3
@c -------------------------------------------------------------------------

@node x3, x4, x2, Gmsh tutorial
@section @code{x3}: Post-processing data import: list-based

See
@url{@value{GITLAB-PREFIX}/tutorials/python/x3.py,x3.py}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/x3.cpp,x3.cpp}).

@center@image{images/x3,9cm,}

@format
@verbatiminclude ../../tutorials/python/x3.py
@end format

@c -------------------------------------------------------------------------
@c x4
@c -------------------------------------------------------------------------

@node x4, x5, x3, Gmsh tutorial
@section @code{x4}: Post-processing data import: model-based

See
@url{@value{GITLAB-PREFIX}/tutorials/python/x4.py,x4.py}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/x4.cpp,x4.cpp}).

@center@image{images/x4,9cm,}

@format
@verbatiminclude ../../tutorials/python/x4.py
@end format

@c -------------------------------------------------------------------------
@c x5
@c -------------------------------------------------------------------------

@node x5, x6, x4, Gmsh tutorial
@section @code{x5}: Additional geometrical data: parametrizations, normals, curvatures

See
@url{@value{GITLAB-PREFIX}/tutorials/python/x5.py,x5.py}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/x5.cpp,x5.cpp}).

@center@image{images/x5,9cm,}

@format
@verbatiminclude ../../tutorials/python/x5.py
@end format

@c -------------------------------------------------------------------------
@c x6
@c -------------------------------------------------------------------------

@node x6, x7, x5, Gmsh tutorial
@section @code{x6}: Additional mesh data: integration points, Jacobians and basis functions

See
@url{@value{GITLAB-PREFIX}/tutorials/python/x6.py,x6.py}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/x6.cpp,x6.cpp}).

@format
@verbatiminclude ../../tutorials/python/x6.py
@end format

@c -------------------------------------------------------------------------
@c x7
@c -------------------------------------------------------------------------

@node x7,  , x6, Gmsh tutorial
@section @code{x7}: Additional mesh data: internal edges and faces

See
@url{@value{GITLAB-PREFIX}/tutorials/python/x7.py,x7.py}.
Also available in C++
(@url{@value{GITLAB-PREFIX}/tutorials/c++/x7.cpp,x7.cpp}).

@center@image{images/x7,9cm,}

@format
@verbatiminclude ../../tutorials/python/x7.py
@end format

@c =========================================================================
@c Gmsh graphical user interface
@c =========================================================================

@node Gmsh graphical user interface, Gmsh command-line interface, Gmsh tutorial, Top
@chapter Gmsh graphical user interface

@cindex GUI
@cindex Graphical user interface

Once you have the Gmsh application installed (@pxref{Installing and
running Gmsh on your computer}), to launch the graphical interface just
double-click on the Gmsh icon, or type
@example
> gmsh
@end example
at the shell prompt in a terminal. This will open the main window of the
Gmsh GUI, with a menu bar on top (except on macOS, where by default the
menu bar is on the top of the screen -- this can be changed with the
@code{General.SystemMenuBar} option, see @ref{General options}), a tree
menu on the left (which by default contains a `Modules' entry with three
children: `Geometry', `Mesh' and `Solver'), a graphic area on the right,
and a status bar with some shortcut buttons at the bottom. (You can
detach the tree menu using `Window->Attach/Detach Menu'.)

@iftex
@sp 1
@end iftex
@center@image{images/gui,10.5cm,}

To create a new geometrical model, use the `File->New' menu to create a
new model file, and choose for example @file{mymodel.geo} as file
name. Then in the tree menu, successively open the `Geometry',
`Elementary entities' and `Add' submenus, and click for example on
`Rectangle'. A context window with parameters will pop up: you can enter
some parameters in this window (e.g. the width and height of the
rectangle) and move the mouse to place it on the canvas. If you don't
want to place the rectangle with the mouse, select `X', `Y' and `Z
freeze' in the window and enter the coordinates manually in the context
window. Once you are done, either press @kbd{e} (see the status message
on the top of the graphic window) or click on the `Add' button in the
context window.

@iftex
@sp 1
@end iftex
@center@image{images/gui_add_rectangle,10.5cm,}

There is no need to save your geometrical model: when the rectangle was
added, scripting commands were automatically appended to your model
file @file{mymodel.geo}:
@example
//+
SetFactory("OpenCASCADE");
Rectangle(1) = @{0, 0, 0, 1, 0.5, 0@};
@end example
You can edit this script with any text editor; clicking on `Edit script'
in the tree menu will launch the default text editor specified by the
@code{General.Editor} option (@pxref{General options}). If you edit the
script, you should click on `Reload script' in the tree menu to reload
the modifications in the GUI. The @code{//+} line in the script is a
comment that is used as a placemark between commands added by the GUI;
see @ref{Gmsh scripting language} for the scripting language reference.

Combining GUI actions and script file editing is a classical way of
working with the Gmsh app. 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.

To load an existing model instead of creating a model from scratch, use
the `File->Open' menu. For example, to open the first tutorial
(@pxref{Gmsh tutorial}), choose
@url{@value{GITLAB-PREFIX}/tutorials/t1.geo,t1.geo}. On the terminal,
you can also specify the file name directly on the command line, i.e.:
@example
> gmsh t1.geo
@end example

To generate a mesh, open `Mesh' in the tree menu and choose the desired
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' in the tree menu, 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.  Note that most interactive commands have keyboard
shortcuts: see @ref{Keyboard shortcuts}, or select `Help->Keyboard and
Mouse Usage' in the menu. For example, to quickly generate the 2D mesh
and save a mesh, you can first press @kbd{2}, then @kbd{Ctrl+Shift+s}.

A double-click in the graphic window will pop up a quick shortcut menu,
which can be used e.g. to quickly toggle the visibility of mesh entities
(like surface faces), reset the viewport, select the rotation center,
display axes, or access the full module options (from the
`Tools->Options' menu). The shortcut buttons on the bottom left of the
status bar can be used to quickly adjust the viewport: `X', `Y', `Z' set
viewports with the corresponding axis perpendicular to graphic plane;
the rotation button rotates the view by 90 degrees; and `1:1' resets the
scale.

@iftex
@sp 1
@end iftex
@center@image{images/gui_mesh,10.5cm,}

Several files can be loaded simultaneously. When specified on the
command line, the first one defines the active model (in the same way as
using the `File->Open' menu) and the others are `merged' into this model
(in the same way as using the the `File->Merge' menu). For example, to
merge the post-processing views contained in the files
@url{@value{GITLAB-PREFIX}/tutorials/view1.pos,view1.pos} and
@url{@value{GITLAB-PREFIX}/tutorials/view5.msh,view5.msh} together with
the geometry of the first tutorial @ref{t1}, you can type the following
command:
@example
> gmsh t1.geo view1.pos view5.msh
@end example

When one or more more post-processing views are loaded, a
`Post-Processing' entry in the tree menu appears. With the previous
command, three views will appear in the tree menu under
`Post-processing', 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 shortcuts icons on the
left of 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. 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{Gmsh
options}. A full list of options with their current values is also
available using the `Help->Current Options' menu.

Finally, note that the GUI can also be run (and modified) using the API:
see @ref{Namespace gmsh/fltk} for details.

The two next sections describe the mouse actions in the GUI, as well as
all the predefined keyboard shortcuts. Screencasts explaining how to use
the Gmsh GUI are available online at the following address:
@uref{https://gmsh.info/screencasts/}.

@c TODO: add section describing the main windows in the GUI, with a
@c screenshot for each one: Tools->Options, Tools->Plugins,
@c Tools->Visibility, Tools->Clipping, Tools->Manipulator,
@c Tools->Statistics and Tools->Message console

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

@menu
* Mouse actions::
* Keyboard shortcuts::
@end menu

@node Mouse actions, Keyboard shortcuts, Gmsh graphical user interface, Gmsh graphical user interface
@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, Gmsh graphical user interface
@section Keyboard shortcuts

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

(On macOS, @kbd{Ctrl} is replaced by @kbd{Cmd} in the shortcuts below.)

@include shortcuts.texi

@c =========================================================================
@c Gmsh command-line interface
@c =========================================================================

@node Gmsh command-line interface, Gmsh scripting language, Gmsh graphical user interface, Top
@chapter Gmsh command-line interface

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

Gmsh defines a number of commands-line switches that can be used to
control Gmsh in ``batch'' mode from the command line, and pass options
without resorting to a script (@pxref{Gmsh scripting language}) or the
API (@pxref{Gmsh application programming interface}).

For example, meshing the first tutorial in batch mode can be done in a
terminal by passing the @code{-2} command-line switch:
@example
> gmsh t1.geo -2
@end example

The same effect could be achieved by adding the @code{Mesh 2;} command
at the end of @file{t1.geo} and running
@example
> gmsh t1.geo -parse_and_exit
@end example
or further adding the @code{Exit;} command at the end of the script and
simply opening this new file:
@example
> gmsh t1.geo
@end example

Note that all numeric and string options (@pxref{Gmsh options}) can be
set from the command line with the @code{-setnumber} and
@code{-setstring} switches
@example
> gmsh t1.geo -setnumber Mesh.Nodes 1 -setnumber Geometry.SurfaceLabels 1
@end example

The list of all command-line switches is given hereafter.

@include commandline.texi

@c =========================================================================
@c Gmsh scripting language
@c =========================================================================

@node Gmsh scripting language, Gmsh application programming interface, Gmsh command-line interface, Top
@chapter Gmsh scripting language

The Gmsh scripting language is interpreted at runtime by Gmsh's
parser. Scripts are written in ASCII files and are usually given the
@file{.geo} extension, but any extension (or no extension at all) can
also be used. For example Gmsh often uses the @file{.pos} extension for
scripts that contain post-processing commands, in particular parsed
post-processing views (@pxref{Post-processing scripting commands}).

Historically, @file{.geo} scripts have been the primary way to perform
complex tasks with Gmsh, and they are indeed quite powerful: they can
handle (lists of) floating point (@pxref{Floating point expressions})
and string (@pxref{String expressions}) variables, loops and tests
(@pxref{Loops and conditionals}), macros (@pxref{User-defined macros}),
etc. However Gmsh's scripting language is still quite limited compared
to actual programming languages: for example there are no private
variables, macros don't take arguments, and the runtime interpretation
by the parser can penalize performance on large models. Depending on the
workflow and the application, using the Gmsh API (@pxref{Gmsh
application programming interface}) can thus sometimes be
preferable. The downside of the API is that, while the scripting
language is baked into Gmsh and is thus available directly in the
standalone Gmsh app, the API requires external dependencies (a C++, C or
Fortran compiler; or a Python or Julia interpreter).

This chapter describes the scripting language by detailing general
commands first (@pxref{General scripting commands}), before detailing
the scripting commands specific to the geometry (@pxref{Geometry
scripting commands}), mesh (@pxref{Mesh scripting commands}) and
post-processing (@pxref{Post-processing scripting commands}) modules.

The following rules are used when describing the scripting language in
the rest of this chapter (note that metasyntactic variable definitions
stay valid throughout the chapter, not only in the section 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

@menu
* General scripting commands::
* Geometry scripting commands::
* Mesh scripting commands::
* Post-processing scripting commands::
@end menu

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

@node General scripting commands, Geometry scripting commands, Gmsh scripting language, Gmsh scripting language
@section General scripting commands

@menu
* Comments::
* Floating point expressions::
* String expressions::
* Color expressions::
* Operators::
* Built-in functions::
* User-defined macros::
* Loops and conditionals::
* Other general commands::
@end menu

@c .........................................................................
@c Comments
@c .........................................................................

@node Comments, Floating point expressions, General scripting commands, General scripting commands
@subsection 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 Floating point expressions
@c .........................................................................

@node Floating point expressions, String expressions, Comments, General scripting commands
@subsection Floating point 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.

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

Floating point expressions (or, more simply, ``expressions'') are
denoted by the metasyntactic variable @var{expression}, 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{number-option} |
  Find(@var{expression-list-item}, @var{expression-list-item}) |
  StrFind(@var{string-expression}, @var{string-expression}) |
  StrCmp(@var{string-expression}, @var{string-expression}) |
  StrLen(@var{string-expression}) |
  TextAttributes(@var{string-expression}<,@var{string-expression}@dots{}>) |
  Exists(@var{string}) | Exists(@var{string}~@{ @var{expression} @}) |
  FileExists(@var{string-expression}) |
  StringToName(@var{string-expression}) | S2N(@var{string-expression}) |
  GetNumber(@var{string-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{number-option}s} are
listed in @ref{Gmsh 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{string-expression} for any
occurrence of the second @var{string-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{StrLen} 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}), 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 the
@uref{https://gitlab.onelab.info/doc/tutorials/wikis/ONELAB-syntax-for-Gmsh-and-GetDP,
ONELAB tutorial wiki} 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
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} @} |
  Mass Curve|Surface|Volume @{ @var{expression} @} |
  CenterOfMass Curve|Surface|Volume @{ @var{expression} @} |
  MatrixOfInertia Curve|Surface|Volume @{ @var{expression} @} |
  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, with the bounding box
specified as (X min, Y min, Z min, X max, Y max, Z max). Beware that the
order of coordinates is different than in the @code{BoundingBox} command
for the scene: see @ref{Other general commands}. The last cases permit to
retrieve the mass, the center of mass or the matrix of inertia of an
entity, the coordinates of a given geometry point (@pxref{Points}), the
elementary entities making up physical groups, and the tags of all
(physical or elementary) points, curves, surfaces or volumes in the
model. @value{SYNCS}

To see the practical use of such expressions, have a look at the first
couple of examples in @ref{Gmsh 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 String expressions
@c .........................................................................

@node String expressions, Color expressions, Floating point expressions, General scripting commands
@subsection String expressions

@cindex Expressions, string
@cindex Strings

String expressions are defined as:
@example
@var{string-expression}:
  "@var{string}" |
  @var{string} | @var{string}[ @var{expression} ] |
  Today | OnelabAction | GmshExecutableName |
  CurrentDirectory | CurrentDir | CurrentFileName
  StrPrefix ( @var{string-expression} ) |
  StrRelative ( @var{string-expression} ) |
  StrCat ( @var{string-expression} <,@dots{}> ) |
  Str ( @var{string-expression} <,@dots{}> ) |
  StrChoice ( @var{expression}, @var{string-expression}, @var{string-expression} ) |
  StrSub( @var{string-expression}, @var{expression}, @var{expression} ) |
  StrSub( @var{string-expression}, @var{expression} ) |
  UpperCase ( @var{string-expression} ) |
  AbsolutePath ( @var{string-expression} ) |
  DirName ( @var{string-expression} ) |
  Sprintf ( @var{string-expression} , @var{expression-list} ) |
  Sprintf ( @var{string-expression} ) |
  Sprintf ( @var{string-option} ) |
  GetEnv ( @var{string-expression} ) |
  GetString ( @var{string-expression} <,@var{string-expression}>) |
  GetStringValue ( @var{string-expression} , @var{string-expression} ) |
  StrReplace ( @var{string-expression} , @var{string-expression} , @var{string-expression} )
  NameToString ( @var{string} ) | N2S ( @var{string} ) |
  <Physical> Point|Curve|Surface|Volume @{ @var{expression} @} |
  DefineString(@var{string-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} (or @code{CurrentDir}) and
@code{CurrentFileName} return the directory and file name of the script
being parsed. @code{StrPrefix} and @code{StrRelative} take the prefix
(e.g. to remove the extension) or the relative path of a given file
name. @code{StrCat} and @code{Str} concatenate string expressions
(@code{Str} adds a newline character after each string except the last).
@code{StrChoice} returns the first or second @var{string-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{string-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{string-expression} is a format string that can contain floating
point formatting characters: @code{%e}, @code{%g}, etc.) The various
@w{@var{string-option}s} are listed in @ref{Gmsh
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{Physical Point},
etc., or @code{Point}, etc., retrieve the name of the physical or
elementary entity, if any.  @code{NameToString} converts a variable name
into a string.

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

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

List of string expressions are defined as:
@example
@var{string-expression-list}:
  @var{string-expression} <,@dots{}>
@end example

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

@node Color expressions, Operators, String expressions, General scripting commands
@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{string-expression} |
  @{ @var{expression}, @var{expression}, @var{expression} @} |
  @{ @var{expression}, @var{expression}, @var{expression}, @var{expression} @} |
  @var{color-option}
@end example
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{@value{GITLAB-PREFIX}/src/common/Colors.h,src/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{Gmsh options}.

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

@c .........................................................................
@c Operators
@c .........................................................................

@menu
* Operators::
* Built-in functions::
* User-defined macros::
* Loops and conditionals::
* Other general commands::
@end menu

@node Operators, Built-in functions, Color expressions, General scripting commands
@subsection 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 available unary, binary and ternary operators.

@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{Other 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 scripting commands
@subsection 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 Max ( @var{expression}, @var{expression} )
Maximum of the two arguments.

@item Min ( @var{expression}, @var{expression} )
Minimum of the two arguments.

@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 scripting commands
@subsection 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{string-expression}
Begin 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
End the body of the current user-defined macro. Macro declarations
cannot be imbricated.

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

See @ref{t5}, 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, Other general commands, User-defined macros, General scripting commands
@subsection 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} )
Iterate 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} )
Iterate 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} @}
Iterate 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} @}
Iterate 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
End 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
End a matching @code{If} command.
@end ftable

@c .........................................................................
@c Other general commands
@c .........................................................................

@node Other general commands,  , Loops and conditionals, General scripting commands
@subsection Other 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};
Create a new expression identifier @var{string}, or affects
@var{expression} to an existing expression identifier. The following
expression identifiers are predefined (hardcoded in Gmsh's parser):

@ftable @code
@item Pi
Return 3.1415926535897932.

@item GMSH_MAJOR_VERSION
Return Gmsh's major version number.

@item GMSH_MINOR_VERSION
Return Gmsh's minor version number.

@item GMSH_PATCH_VERSION
Return Gmsh's patch version number.

@item MPI_Size
Return 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
Return the rank of the current processor.

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

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

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

@item newp
Return 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 newc
Return the next available curve tag.

@item news
Return the next available surface tag.

@item newv
Return the next available volume tag.

@item newcl
Return the next available curve loop tag.

@item newsl
Return the next available surface loop tag.

@item newreg
Return 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}).}.
@end ftable

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

@item @var{string}[] = @{ @var{expression-list} @};
Create 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} @};
Affect 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};
Add and affect @var{expression} to an existing expression identifier.

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

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

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

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

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

@item @var{string} [ @{ @var{expression-list} @} ] += @{ @var{expression-list} @};
Add and affect, 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} @};
Subtract and affect, 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} @};
Multiply and affect, 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} @};
Divide and affect, 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{string-expression};
Create a new string expression identifier @code{@var{string}} with a
given @var{string-expression}.

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

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

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

@item DefineConstant[ @var{string} = @{ @var{expression}|@var{string-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 the
@uref{https://gitlab.onelab.info/doc/tutorials/wikis/ONELAB-syntax-for-Gmsh-and-GetDP,
ONELAB tutorial wiki} for more information.

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

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

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

@item @var{string-option} = @var{string-expression};
Affect @var{string-expression} to a string option.

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

@item @var{number-option} += @var{expression};
Add and affect @var{expression} to a real option.

@item @var{number-option} -= @var{expression};
Subtract and affect @var{expression} to a real option.

@item @var{number-option} *= @var{expression};
Multiply and affect @var{expression} to a real option.

@item @var{number-option} /= @var{expression};
Divide and affect @var{expression} to a real option.

@item Abort;
Abort the current script.

@item Exit;
Exit Gmsh.

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

@item Printf ( @var{string-expression} <, @var{expression-list}> );
Print a string expression in the information window and/or on the
terminal. @code{Printf} is equivalent to the @code{printf} C function:
@var{string-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{Floating point expressions}), so that only valid floating point
formatting characters make sense in @var{string-expression}. See @ref{t5},
for an example of the use of @code{Printf}.

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

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

@item Warning|Error ( @var{string-expression} <, @var{expression-list}> );
Same as @code{Printf}, but raises a warning or an error.

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

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

@item Draw;
Redraw the scene.

@item SplitCurrentWindowHorizontal @var{expression};
Split the current window horizontally, with the ratio given by @var{expression}.

@item SplitCurrentWindowVertical @var{expression};
Split the current window vertically, with the ratio given by @var{expression}.

@item SetCurrentWindow @var{expression};
Set the current window by speficying its index (starting at 0) in the
list of all windows. When new windows are created by splits, new windows
are appended at the end of the list.

@item UnsplitWindow;
Restore a single window.

@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;
Recompute the bounding box of the scene (which is normally computed only
after new model 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
@value{SYNC}

@item BoundingBox @{ @var{expression}, @var{expression}, @var{expression}, @var{expression}, @var{expression}, @var{expression} @};
Force 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). Beware that order of the
coordinates is different than in the @code{BoundingBox} commands for
model entities: see @ref{Floating point expressions}.

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

@item Delete Physicals;
Delete all physical groups.

@item Delete Variables;
Delete all the expressions.

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

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

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

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

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

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

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

@item SetName @var{string-expression};
Change the name of the current model.

@item SetFactory(@var{string-expression});
Change 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;
Force an immediate transfer from the old geometrical database into the
new one (this transfer normally occurs right after a file is read).

@item NewModel;
Create a new current model.

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

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

@node Geometry scripting commands, Mesh scripting commands, General scripting commands, Gmsh scripting language
@section Geometry scripting commands

@cindex Geometry, scripting commands
@cindex Scripting commands, geometry

Both the built-in and the OpenCASCADE CAD kernels can be used in the
scripting language, by specifying @code{SetFactory("Built-in")} or
@code{SetFactory("OpenCASCADE")}, respectively, before geometrical
scripting commands. If @code{SetFactory} is not specified, the built-in
kernel is used.

A bottom-up boundary representation approach can be used by first
defining points (using the @code{Point} command), 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). 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.  With
the OpenCASCADE kernel, additional boolean operations are available:
@code{BooleanIntersection}, @code{BooleanUnion},
@code{BooleanDifference} and @code{BooleanFragments}.

The next subsections describe all the available geometry commands in the
scripting language. Note that the following general rule is followed for
the definition of model 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::
* Other geometry commands::
@end menu

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

@node Points, Curves, Geometry scripting commands, Geometry scripting 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} > @};
Create a 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{string-expression} <, @var{expression}> ) <+|->= @{ @var{expression-list} @};
Create 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{string-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 scripting 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} @};
Create 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} @};
Create a Bezier curve. The @var{expression-list} contains the
tags of the control points.

@item BSpline ( @var{expression} ) = @{ @var{expression-list} @};
Create 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} @};
Create 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} <, ...> @};
Create a circle arc. If three @var{expression}s are provided on the
right-hand-side they 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, if between 4 and
6 expressions are provided, the first three define the coordinates of
the center, the next one defines the radius, and the optional next two
the start and end angle.
@c TODO: document < Plane @{ @var{expression}, @var{expression}, @var{expression} @}; >

@item Ellipse ( @var{expression} ) = @{ @var{expression}, @var{expression}, @var{expression} <, ...> @};
Create an ellipse arc. If four @var{expression}s are provided on the
right-hand-side they define the start point, the center point, a point
anywhere on the major axis and the end point. If the first point is a
major axis point, the third expression can be ommitted. With the
OpenCASCADE kernel, if between 5 and 7 expressions are provided, the
first three define the coordinates of the center, the next two define
the major (along the x-axis) and minor radii (along the y-axis), and the
next two the start and end angle. Note that OpenCASCADE does not allow
creating ellipse arcs with the major radius smaller than the minor
radius.

@item Compound Spline | BSpline ( @var{expression} ) = @{ @var{expression-list} @} Using @var{expression};
Create a spline or a BSpline from control points sampled on the curves
in @var{expression-list}. @code{Using} @var{expression} specifies the
number of intervals on each curve to compute the sampling
points. Compound splines and BSplines are only available with the
built-in geometry kernel.

@item Curve Loop ( @var{expression} ) = @{ @var{expression-list} @};
Create 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 curves that constitute the curve loop. A curve loop must be a
closed loop. With the built-in geometry kernel, the 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; the built-in kernel also supports multiple curve loops (or
subloops) in a single @code{Curve Loop} command, but this is not
recommended). With the OpenCASCADE kernel the curve loop is always
oriented according to the orientation of its first curve; negative tags
can be specified for compatibility with the built-in kernel, but are
simply ignored. Curve loops are used to create surfaces: see
@ref{Surfaces}.

@item Wire ( @var{expression} ) = @{ @var{expression-list} @};
Create 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{string-expression} <, @var{expression}> ) <+|->= @{ @var{expression-list} @};
Create 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{string-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). In some mesh file formats (e.g. MSH2),
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 scripting 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} @};
Create 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} @}, Using Point @{ @var{expression-list} @} >;
Create a surface filling. With the built-in kernel, the first curve
loop should be composed of either three or four curves, the surface is
constructed using transfinite interpolation, and 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). With the
OpenCASCADE kernel, a BSpline surface is constructucted by optimization
to match the bounding curves, as well as the (optional) points provided
after @code{Using Point}.

@item BSpline Surface ( @var{expression} ) = @{ @var{expression-list} @};
Create a BSpline surface filling. Only a single curve loop made of 2, 3
or 4 BSpline curves can be provided. @code{BSpline Surface} is only
available with the OpenCASCADE kernel.

@item Bezier Surface ( @var{expression} ) = @{ @var{expression-list} @};
Create a Bezier surface filling. Only a single curve loop made of 2, 3
or 4 Bezier curves can be provided. @code{Bezier Surface} is only
available with the OpenCASCADE kernel.

@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} @};
Create 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} @} < Using Sewing >;
Create 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 surfaces that
constitute the surface loop. A surface loop must always represent a
closed shell, and the surfaces should be oriented consistently (using
negative tags to specify reverse orientation). (Surface loops are used
to create volumes: see @ref{Volumes}.) With the OpenCASCADE kernel, the
optional @code{Using Sewing} argument allows to build a shell made of
surfaces that share geometrically identical (but topologically
different) curves.

@item Physical Surface ( @var{expression} | @var{string-expression} <, @var{expression}> ) <+|->= @{ @var{expression-list} @};
Create 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{string-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).  In some mesh
file formats (e.g. MSH2), 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 scripting commands
@subsection Volumes

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

@ftable @code
@item Volume ( @var{expression} ) = @{ @var{expression-list} @};
Create 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} @};
Create a sphere, defined by the 3 coordinates of its center and a
radius. Additional expressions define 3 angle limits. The first two
optional arguments define the polar angle opening (from -Pi/2 to
Pi/2). The optional `angle3' argument defines the azimuthal opening
(from 0 to 2*Pi). @code{Sphere} is only available with the OpenCASCADE
kernel.

@item Box ( @var{expression} ) = @{ @var{expression-list} @};
Create 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} @};
Create 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} @};
Create 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} @};
Create 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} @};
Create 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} @};
Create 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{string-expression} <, @var{expression}> ) <+|->= @{ @var{expression-list} @};
Create 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{string-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 scripting 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} @}
Extrude 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} @}
Extrude 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). With the built-in geometry kernel the angle
should be strictly smaller than Pi.

@item Extrude @{ @{ @var{expression-list} @}, @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} @{ @var{extrude-list} @}
Extrude 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). With
the built-in geometry kernel the angle should be strictly smaller than
Pi.

@item Extrude @{ @var{extrude-list} @}
Extrude 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} @}
Extrude entities in @var{extrude-list} along the give wire. Only
available with the OpenCASCADE geometry kernel.

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

@item Ruled ThruSections @{ @var{expression-list} @}
Create 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} @}
Fillet 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}).

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

@node Boolean operations, Transformations, Extrusions, Geometry scripting 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} @}
Compute the intersection of the object and the tool.
@item BooleanUnion @{ @var{boolean-list} @} @{ @var{boolean-list} @}
Compute 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} @}
Compute all the fragments resulting from the intersection of the
entities in the object and in the tool, making all interfaces conformal.
When applied to entities of different dimensions, the lower dimensional
entities will be automatically embedded in the higher dimensional
entities if they are not on their boundary.
@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{@value{GITLAB-PREFIX}/examples/boolean/,examples/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} @};
Compute the intersection of the object and the tool and assign the
result the tag @var{expression}.
@item BooleanUnion  ( @var{expression} ) = @{ @var{boolean-list} @} @{ @var{boolean-list} @};
Compute the union of the object and the tool and assign the result
the tag @var{expression}.
@item BooleanDifference  ( @var{expression} ) = @{ @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{@value{GITLAB-PREFIX}/examples/boolean/,examples/boolean}
for examples.

Boolean operations are only available with the OpenCASCADE geometry kernel.

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

@node Transformations, Other geometry commands, Boolean operations, Geometry scripting 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} @}
Scale 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} @}
Scale 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} @}
Rotate 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} @}
Transform 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 Affine @{ @var{expression-list} @} @{ @var{transform-list} @}
Apply a 4 x 4 affine transformation matrix (16 entries given by row;
only 12 can be provided for convenience) to all elementary
entities. Currently only available with the OpenCASCADE kernel.

@item Translate @{ @var{expression-list} @} @{ @var{transform-list} @}
Translate 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.) Return 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. @value{SYNC}

@item CombinedBoundary @{ @var{transform-list} @}
(Not a transformation per-se.) Return 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.
@value{SYNC}

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

@item Intersect Curve @{ @var{expression-list} @} Surface @{ @var{expression} @}
(Not a transformation per-se.) Return the intersections of the curves
given in @var{expression-list} with the specified surface. Currently
only available with the built-in kernel.

@item Split Curve @{ @var{expression} @} Point @{ @var{expression-list} @}
(Not a transformation per-se.) Split the curve @var{expression} on the
specified control points. Only available with the built-in kernel, for
lines, splines and BSplines.
@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 Other geometry commands
@c .........................................................................

@node Other geometry commands,  , Transformations, Geometry scripting commands
@subsection Other geometry commands

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

@ftable @code
@item Coherence;
Remove all duplicate elementary 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}). With the OpenCASCADE geometry kernel,
@code{Coherence} is simply a shortcut for a @code{BooleanFragments}
operation on all entities, with the @code{Delete} operator applied to
all operands.

@item HealShapes;
Apply the shape healing procedure(s), according to
@code{Geometry.OCCFixDegenerated}, @code{Geometry.OCCFixSmallEdges},
@code{Geometry.OCCFixSmallFaces}, @code{Geometry.OCCSewFaces},
@code{Geometry.OCCMakeSolids}. Only available with the OpenCASCADE
geometry kernel.

@item < Recursive > Delete @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Delete 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. @value{SYNC}

@item Delete Embedded @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Delete all the embedded entities in the elementary entities whose tags
are given in @var{expression-list-or-all}. @value{SYNC}

@item SetMaxTag Point | Curve | Surface | Volume ( @var{expression} )
Force the maximum tag for a category of entities to a given value, so
that subsequently created entities in the same category will not have
tags smaller than the given value.

@item < Recursive > Hide @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Hide the entities listed in @var{expression-list-or-all}.

@item Hide @{ : @}
Hide all entities.

@item < Recursive > Show @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @}
Show the entities listed in @var{expression-list-or-all}.

@item Show @{ : @}
Show all entities.

@item Sphere | PolarSphere ( @var{expression} ) = @{@var{expression}, @var{expression}@};
Change the current (surface) geometry used by the built-in geometry kernel to a (polar) sphere, defined by the two point tags specified on the right hand side. The @var{expression} between parentheses on the left hand side specifies a new unique tag for this geometry.

@item Parametric Surface ( @var{expression} ) = "@var{string}" "@var{string}" "@var{string}";
Change the current (surface) geometry used by the built-in geometry kernel to a parametric surface defined by the three strings expression evaluating to the x, y and z coordinates. The @var{expression} between parentheses on the left hand side specifies a new unique tag for this geometry.

@item Coordinates Surface @var{expression};
Change the current (surface) geometry used by the built-in geometry kernel to the geometry identified by the given @var{expression}.

@item Euclidian Coordinates ;
Restore the default planar geometry for the built-in geometry kernel.

@end ftable

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

@node Mesh scripting commands, Post-processing scripting commands, Geometry scripting commands, Gmsh scripting language
@section Mesh scripting commands

@cindex Mesh, scripting commands
@cindex Scripting commands, Mesh

The mesh module scripting commands allow to modify the mesh element
sizes and specify structured grid parameters. Certain meshing actions
(e.g. ``mesh all the surfaces'') can also be specified in the script
files, but are usually performed either in the GUI or on the command
line (see @ref{Gmsh graphical user interface}, and @ref{Gmsh
command-line interface}).

@menu
* Mesh element sizes::
* Structured grids::
* Other mesh commands::
@end menu

@c .........................................................................
@c Mesh element sizes
@c .........................................................................

@node Mesh element sizes, Structured grids, Mesh scripting commands, Mesh scripting commands
@subsection Mesh element sizes

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

@ftable @code
@item MeshSize @{ @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{string-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

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

@node Structured grids, Other mesh commands, Mesh element sizes, Mesh scripting 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} @}
Extrude 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}, 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 similar 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} @}
Extrude both the geometry and the mesh using a rotation
(@pxref{Extrusions}). The @var{layers} option is defined as above.  With
the built-in geometry kernel the angle should be strictly smaller than
Pi. With the OpenCASCADE kernel the angle should be strictly smaller
than 2 Pi.

@item Extrude @{ @{ @var{expression-list} @}, @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} @{ @var{extrude-list} @var{layers} @}
Extrude both the geometry and the mesh using a combined translation and
rotation (@pxref{Extrusions}). The @var{layers} option is defined as
above. With the built-in geometry kernel the angle should be strictly
smaller than Pi. With the OpenCASCADE kernel the angle should be
strictly smaller than 2 Pi.

@item Extrude @{ Surface @{ @var{expression-list} @}; @var{layers} < Using Index[@var{expr}]; > < Using View[@var{expr}]; > < ScaleLastLayer; > @}
Extrude a ``topological'' boundary layer from the specified surfaces. If
no view is specified, the mesh of the boundary layer entities is created
using a gouraud-shaded (smoothed) normal field. If a scalar view is
specified, it locally prescribes the thickness of the layer. If a
vector-valued view is specified it locally prescribes both the extrusion
direction and the thickness. 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. Topological boundary layers are only available with the built-in
kernel. See
@url{@value{GITLAB-PREFIX}/benchmarks/extrude/sphere_boundary_layer.geo,sphere_boundary_layer.geo}
or
@url{@value{GITLAB-PREFIX}/benchmarks/extrude/sphere_boundary_layer_from_view.geo,sphere_boundary_layer_from_view.geo}
for @file{.geo} file examples, and
@url{@value{GITLAB-PREFIX}/examples/api/aneurysm.py,aneurysm.py} for an API
example.

The advantage of this approach is that it provides a topological
description of the boundary layer, which means that it can be connected
to other geometrical entities. The disadvantage is that the mesh is just
a ``simple'' extrusion: no fans, no special treatments of reentrant
corners, etc. Another boundary layer algorithm is currently available
through the @code{BoundaryLayer} field (@pxref{Specifying mesh element
sizes}). It only works in 2D however, and is a meshing constraint: it
works directly at the mesh level, without creating geometrical
entities. See
e.g. @url{@value{GITLAB-PREFIX}/benchmarks/2d/BL0.geo,BL0.geo} or
@url{@value{GITLAB-PREFIX}/benchmarks/2d/naca12_2d.geo,naca12_2d.geo}.

@item Transfinite Curve @{ @var{expression-list-or-all} @} = @var{expression} < Using Progression | Bump @var{expression} >;
Select 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. @value{SYNC}

@item Transfinite Surface @{ @var{expression-list-or-all}  @}  < = @{ @var{expression-list} @} > < Left | Right | Alternate | AlternateRight | AlternateLeft > ;
Select 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}. For 3-sided surfaces a specific algorithm can be
used to generate structured triangular by setting
@code{Mesh.TransfiniteTri} to 1. Examples can be found in
@url{@value{GITLAB-PREFIX}/benchmarks/transfinite,benchmarks/transfinite}.
@value{SYNC}

@item Transfinite Volume @{ @var{expression-list} @} < = @{ @var{expression-list} @} > ;
Select 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. @value{SYNC}

@item TransfQuadTri @{ @var{expression-list} @} ;
Apply 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. @value{SYNC}

@end ftable

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

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

@c .........................................................................
@c Other mesh commands
@c .........................................................................

@node Other mesh commands,  , Structured grids, Mesh scripting commands
@subsection Other mesh commands

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

@ftable @code
@item Mesh @var{expression};
Generate @var{expression}-D mesh. @value{SYNC}

@item TransformMesh @{ @var{expression-list} @};
Transform all the node coordinates in the current mesh using the 4x4
affine transformation matrix given by row (only 12 entries can be
provided for convenience).

@item TransformMesh @{ @var{expression-list} @} @{ @var{transform-list} @};
Transform the node coordinates in the current mesh of all the elementary
entities in @var{transform-list} using the 4x4 affine transformation
matrix given by row (only 12 entries can be provided for convenience).

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

@item OptimizeMesh @var{string-expression};
Optimize the current mesh with the given algorithm (currently
@code{"Gmsh"} for default tetrahedral mesh optimizer, @code{"Netgen"}
for Netgen optimizer, @code{"HighOrder"} for direct high-order mesh
optimizer, @code{"HighOrderElastic"} for high-order elastic smoother,
@code{"HighOrderFastCurving"} for fast curving algorithm,
@code{"Laplace2D"} for Laplace smoothing, @code{"Relocate2D"} and
@code{"Relocate3D"} for node relocation).

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

@item RelocateMesh Point | Curve | Surface @{ @var{expression-list-or-all} @};
Relocate 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. @value{SYNC}

@item RecombineMesh;
Recombine the current mesh into quadrangles. @value{SYNC}

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

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

@item Point | Curve @{ @var{expression-list} @} In Surface @{ @var{expression} @};
Add a meshing constraint to 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). @value{SYNC}

@item Point | Curve | Surface @{ @var{expression-list} @} In Volume @{ @var{expression} @};
Add a meshing constraint to 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 algorithms. @value{SYNC}

@item Periodic Curve @{ @var{expression-list} @} = @{ @var{expression-list} @} ;
Add a meshing constraint to force the mesh of the curves on the
left-hand side to match the mesh of the curves on the right-hand side
(masters). If used after meshing, generate the periodic node
correspondence information assuming the mesh of the curves on the
left-hand side effectively matches the mesh of the curves on the
right-hand side. @value{SYNC}

@item Periodic Surface @var{expression} @{ @var{expression-list} @} = @var{expression} @{ @var{expression-list} @} ;
Add a meshing constraint to force the mesh of the surface on the
left-hand side (with boundary edges specified between braces) to match
the mesh of the master surface on the right-hand side (with boundary
edges specified between braces). If used after meshing, generate the
periodic node correspondence information assuming the mesh of the
surface on the left-hand side effectively matches the mesh of the master
surface on the right-hand side (useful for structured and extruded
meshes). @value{SYNC}

@item Periodic Curve | Surface @{ @var{expression-list} @} = @{ @var{expression-list} @} Affine | Translate @{ @var{expression-list} @} ;
Add a meshing constraint to force mesh of curves or surfaces on the
left-hand side to match the mesh of the curves or surfaces on the
right-hand side (masters), using prescribed geometrical
transformations. If used after meshing, generate the periodic node
correspondence information assuming the mesh of the curves or surfaces
on the left-hand side effectively matches the mesh of the curves or
surfaces on the right-hand side (useful for structured and extruded
meshes). @code{Affine} takes a 4 x 4 affine transformation matrix given
by row (only 12 entries can be provided for convenience);
@code{Translate} takes the 3 components of the translation as in
@ref{Transformations}. @value{SYNC}

@item Periodic Curve | Surface @{ @var{expression-list} @} = @{ @var{expression-list} @} Rotate @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} ;
Add a meshing constraint to force the mesh of curves or surfaces on the
left-hand side to match the mesh of the curves on the right-hand side
(masters), using a rotation specified as in @ref{Transformations}. If
used after meshing, generate the periodic node correspondence
information assuming the mesh of the curves or surfaces on the left-hand
side effectively matches the mesh of the curves or surfaces on the
right-hand side (useful for structured and extruded
meshes). @value{SYNC}

@item Coherence Mesh;
Remove all duplicate mesh nodes in the current mesh.

@item CreateTopology < @{ @var{expression} , @var{expression} @} > ;
Create a boundary representation from the mesh of the current model if
the model does not have one (e.g. when imported from mesh file formats
with no BRep representation of the underlying model). If the first
optional argument is set (or not given), make all volumes and surfaces
simply connected first; if the second optional argument is set (or not
given), clear any built-in CAD kernel entities and export the discrete
entities in the built-in CAD kernel.

@item CreateGeometry < @{ <Physical> Point | Curve | Surface | Volume @{ @var{expression-list-or-all} @}; @dots{} @} > ;
Create a geometry for discrete entities (represented solely by a mesh,
without an underlying CAD description) in the current model, i.e. create
a parametrization for discrete curves and surfaces, assuming that each
can be parametrized with a single map. If no entities are given, create
a geometry for all discrete entities.

@item ClassifySurfaces @{ @var{expression} , @var{expression} , @var{expression} < , @var{expression} > @};
Classify (``color'') the current surface mesh based on an angle
threshold (the first argument, in radians), and create new discrete
surfaces, curves and points accordingly.  If the second argument is set,
also create discrete curves on the boundary if the surface is open. If
the third argument is set, create edges and surfaces than can be
reparametrized with @code{CreateGeometry}. The last optional argument
sets an angle threshold to force splitting of the generated curves.

@item RenumberMeshNodes;
Renumber the node tags in the current mesh in a continuous sequence.

@item RenumberMeshElements;
Renumber the elements tags in the current mesh in a continuous sequence.

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

@item Recombine Surface @{ @var{expression-list-or-all} @}  < = @var{expression} >;
Recombine 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). @value{SYNC}

@item MeshAlgorithm Surface @{ @var{expression-list} @} = @var{expression};
Specify the meshing algorithm for the surfaces @var{expression-list}.

@item MeshSizeFromBoundary Surface @{ @var{expression-list} @} = @var{expression};
Force the mesh size to be extended from the boundary (or not, depending
on the value of @var{expression}) for the surfaces
@var{expression-list}.

@item Compound Curve | Surface @{ @var{expression-list-or-all} @} ;
Treat 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} @} ;
Add a constraint to reverse the orientation of the mesh of the given
curve(s) or surface(s) during meshing. @value{SYNC}

@item ReorientMesh Volume @{ @var{expression-list} @} ;
Add a constraint to reorient the meshes (during mesh generation) of the
bounding surfaces of the given volumes so that the normals point outward
to the volumes; and if a mesh already exists, reorient it. Currently
only available with the OpenCASCADE kernel, as it relies on the STL
triangulation. @value{SYNC}

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

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

@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 Post-processing scripting commands
@c -------------------------------------------------------------------------

@node Post-processing scripting commands,  , Mesh scripting commands, Gmsh scripting language
@section Post-processing scripting commands

@cindex Post-processing, scripting commands
@cindex Scripting commands, Post-processing
@cindex 2D plots
@cindex 3D plots
@cindex Plots
@cindex Graphs
@cindex Views

Here is the list of available post-processing scripting commands.

@ftable @code
@item Alias View[@var{expression}];
Create 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}];
Create 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;
Combine 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;
Combine 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;
Combine 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;
Combine 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;
Combine 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;
Combine 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}];
Delete (remove) the @var{expression}-th post-processing view. Note that
post-processing view indices start at 0.

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

@item Background Mesh View[@var{expression}];
Apply 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;
Execute the plugin @var{string}. The list of default plugins is given in
@ref{Gmsh plugins}.

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

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

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

@item View "@var{string}" @{ @var{string} < ( @var{expression-list} ) > @{ @var{expression-list} @}; @dots{} @};
Create 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}), 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{Gmsh 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{coordinates} ) @{ @var{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:

@example
                      @var{type}  #@var{coordinates}  #@var{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 example

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{coordinates} 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{coordinates} 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{values} can contain an
arbitrary number of @w{@var{string-expression}s}. If the
@var{string-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{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{coordinates}). 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:
@example
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 example

@end ftable

@c =========================================================================
@c Gmsh application programming interface
@c =========================================================================

@node Gmsh application programming interface, Gmsh options, Gmsh scripting language, Top
@chapter Gmsh application programming interface

@cindex API
@cindex Programming, API

The Gmsh application programming interface (API) allows to integrate the
Gmsh library in external applications written in C++, C, Python, Julia
or Fortran. By design, the Gmsh API is purely functional, and only uses
elementary types from the target languages. See the
@url{@value{GITLAB-PREFIX}/tutorials/c++,tutorials/c++},
@url{@value{GITLAB-PREFIX}/tutorials/c,tutorials/c},
@url{@value{GITLAB-PREFIX}/tutorials/python,tutorials/python},
@url{@value{GITLAB-PREFIX}/tutorials/julia,tutorials/julia} and
@url{@value{GITLAB-PREFIX}/tutorials/fortran,tutorials/fortran}
directories from the @ref{Gmsh tutorial} for examples. For other API
examples, see the @url{@value{GITLAB-PREFIX}/examples/api/,examples/api}
directory.

The different versions of the API are generated automatically from the
master API definition file
@url{@value{GITLAB-PREFIX}/api/gen.py,api/gen.py}:

@itemize @bullet
@item C++ API: @url{@value{GITLAB-PREFIX}/api/gmsh.h,gmsh.h}
@item C API: @url{@value{GITLAB-PREFIX}/api/gmshc.h,gmshc.h}
@item Python API: @url{@value{GITLAB-PREFIX}/api/gmsh.py,gmsh.py}
@item Julia API: @url{@value{GITLAB-PREFIX}/api/gmsh.jl,gmsh.jl}
@item Fortran API: @url{@value{GITLAB-PREFIX}/api/gmsh.f90,gmsh.f90}
@end itemize

The additional
@url{@value{GITLAB-PREFIX}/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{https://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 structure of the API reflects the underlying Gmsh data model (see
also @ref{Source code structure}):
@itemize
@item
There are two main data containers: @emph{models} (which hold the
geometrical and the mesh data) and @emph{views} (which hold
post-processing data). These are manipulated by the API functions in the
top-level namespaces @code{gmsh/model} and @code{gmsh/view},
respectively. The other top-level namespaces are @code{gmsh/option}
(which handles all options), @code{gmsh/plugin} (which handles
extensions to core Gmsh functionality), @code{gmsh/graphics} (which
handles drawing), @code{gmsh/fltk} (which handles the graphical user
interface), @code{gmsh/parser} (which handles the Gmsh parser),
@code{gmsh/onelab} (which handles ONELAB parameters and communications
with external codes) and @code{gmsh/logger} (which handles information
logging).
@item
Geometrical data is made of model @emph{entities}, called @emph{points}
(entities of dimension 0), @emph{curves} (entities of dimension 1),
@emph{surfaces} (entities of dimension 2) or @emph{volumes} (entities of
dimension 3). Model entities are stored using a boundary representation:
a volume is bounded by a set of surfaces, a surface is bounded by a
series of curves, and a curve is bounded by two end points. Volumes and
surfaces can also store @emph{embedded} entities of lower dimension, to
force a subsequent mesh to be conformal to internal features like a
point in the middle of a surface. Model entities are identified by a
pair of integers: their dimension @emph{dim} (0, 1, 2 or 3) and their
@emph{tag}, a strictly positive identification number. When dealing with
multiple geometrical entities of possibly different dimensions, the API
packs them as a vector of (dim, tag) integer pairs.  @emph{Physical
groups} are collections of model entities and are also identified by
their dimension and by a @emph{tag}. Operations which do not directly
reference a model are performed on the @emph{current} model.
@item
Model entities can be either CAD entities (from the built-in @emph{geo}
kernel or from the OpenCASCADE @emph{occ} kernel) or @emph{discrete}
entities (defined by a mesh). Operations on CAD entities are performed
directly within their respective CAD kernels (i.e. using functions from
the @code{gmsh/model/geo} or @code{gmsh/model/occ} namespaces,
respectively), as Gmsh does not translate across CAD formats but rather
directly accesses the native representation. CAD entities must be
@emph{synchronized} with the model in order to be meshed, or, more
generally, for functions outside of @code{gmsh/model/geo} or
@code{gmsh/model/occ} to manipulate them. 1D and 2D meshing algorithms
use the @emph{parametrization} of the underlying geometrical curve or
surface to generate the mesh. Discrete entities can be remeshed provided
that a parametrization is explicitly recomputed for them.
@item
Mesh data is made of @emph{elements} (points, lines, triangles,
quadrangles, tetrahedra, hexahedra, prisms, pyramids, ...), defined by
an ordered list of their @emph{nodes}. Elements and nodes are identified
by @emph{tags} (strictly positive identification numbers), and are
stored (@emph{classified}) in the model entity they discretize. Once
meshed, a model entity of dimension 0 (a geometrical point) will thus
contain a mesh element of type point (MSH type 15: cf. @ref{MSH file
format}), as well as a mesh node. A model curve will contain line
elements (e.g. of MSH type 1 or 8 for first order or second order
meshes, respectively) as well as its interior nodes, while its boundary
nodes will be stored in the bounding model points. A model surface will
contain triangular and/or quadrangular elements and all the nodes not
classified on its boundary or on its embedded entities (curves and
points). A model volume will contain tetrahedra, hexahedra, etc. and all
the nodes not classified on its boundary or on its embedded entities
(surfaces, curves and points). This data model allows to easily and
efficiently handle the creation, modification and destruction of
conformal meshes. All the mesh-related functions are provided in the
@code{gmsh/model/mesh} namespace.
@item
Post-processing data is made of @emph{views}. Each view is identified by
a @emph{tag}, and can also be accessed by its @emph{index} (which can
change when views are sorted, added or deleted). A view stores both
display @emph{options} and @emph{data}, unless the view is an
@emph{alias} of another view (in which case it only stores display
options, and the data points to a reference view).  View data can
contain several @emph{steps} (e.g. to store time series) and can be
either linked to one or more models@footnote{Each step can be linked to
a different model, which allows to have a single time series based on
multiple (e.g. deforming or moving) meshes.} (@emph{mesh-based} data, as
stored in MSH files: cf. @ref{MSH file format}) or independent from any
model (@emph{list-based} data, as stored in parsed POS files:
cf. @ref{Post-processing scripting commands}). Various @emph{plugins} exist to
modify and create views.
@end itemize

All the functions available in the API are given below. See the relevant
header/module file for the exact definition in each supported language:
in @url{@value{GITLAB-PREFIX}/api/gmsh.h,C++}
@code{gmsh/model/geo/addPoint} will lead to a namespaced function
@code{gmsh::model::geo::addPoint}, while in
@url{@value{GITLAB-PREFIX}/api/gmsh.py,Python} and
@url{@value{GITLAB-PREFIX}/api/gmsh.jl,Julia} it will lead to
@code{gmsh.model.geo.addPoint}, in
@url{@value{GITLAB-PREFIX}/api/gmshc.h,C} to @code{gmshModelGeoAddPoint}
and in @url{@value{GITLAB-PREFIX}/api/gmsh.f90,Fortran} to
@code{gmsh%model%geo%addPoint}.  In addition to the default
``camelCase'' function names, the Python and Julia APIs also define
``snake case'' aliases, i.e. @code{gmsh.model.geo.add_point}, as this is
the recommended style in these languages.  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 Gmsh options
@c =========================================================================

@node Gmsh options, Gmsh mesh size fields, Gmsh application programming interface, Top
@chapter Gmsh options

This chapter lists all the Gmsh options. Options can be specified in
script files (@pxref{General scripting commands}) or using the API
(@pxref{Namespace gmsh/option}): see @ref{t3} for an example. They can
also be specified on the command line using the @code{-setnumber} and
@code{-setstring} switches: see @ref{Gmsh command-line interface}.  Many
options can also be changed interactively in the GUI (@pxref{Gmsh
graphical user interface}): to see which option corresponds to which
widget in the GUI, leave your mouse on the widget and a tooltip with the
option name will appear.  Note that some options can affect the GUI in
real time: loading a script file that sets @code{General.GraphicsWidth}
for example (@pxref{General options}) will change the width of the
graphic window at runtime.

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 option descriptions 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 descriptions
below), automatically loaded by Gmsh every time it starts up. Finally,
other options are only saved to disk manually, either by explicitly
saving an option file with `File->Export', or when saving per-model
options with `File->Save Model Options' (cf. ``Saved in: @code{-}'' in
the lists below). Per-model options are saved in a file name matching
the model file, but with an extra @file{.opt} extension appended: the
option file will be automatically opened after Gmsh opens the model
file.

Gmsh will attempt to save and load the session and option files 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 and load the files from the current working
directory.

To reset all options to their default values, either delete the
@code{General.SessionFileName} and @code{General.OptionsFileName} files
by hand, use `Help->Restore All Options to Default Settings', or click
on `Restore all options to default settings' button in the
`Tools->Options->General->Advanced' window.

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

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

@node General options, Print options, Gmsh options, Gmsh options
@section General options

@include opt_general.texi

@c -------------------------------------------------------------------------
@c Print options
@c -------------------------------------------------------------------------

@node Print options, Geometry options, General options, Gmsh options
@section Print options

@include opt_print.texi

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

@node Geometry options, Mesh options, Print options, Gmsh options
@section Geometry options

@include opt_geometry.texi

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

@node Mesh options, Solver options, Geometry options, Gmsh options
@section Mesh options

@include opt_mesh.texi

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

@node Solver options, Post-processing options, Mesh options, Gmsh options
@section Solver options

@include opt_solver.texi

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

@node Post-processing options, Post-processing view options, Solver options, Gmsh options
@section Post-processing options

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

@include opt_post.texi

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

@node Post-processing view options,  , Post-processing options, Gmsh options
@section Post-processing view options

Options related 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

@include opt_view.texi

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

@c =========================================================================
@c Gmsh mesh size fields
@c =========================================================================

@node Gmsh mesh size fields, Gmsh plugins, Gmsh options, Top
@chapter Gmsh mesh size fields

This chapter lists all the Gmsh mesh size fields (@pxref{Specifying mesh
element sizes}). Fields can be specified in script files (@pxref{Mesh
element sizes}) or using the API (@pxref{Namespace
gmsh/model/mesh/field}). See @ref{t10} for an example on how to use
fields.

@include fields.texi

@c =========================================================================
@c Gmsh plugins
@c =========================================================================

@node Gmsh plugins, Gmsh file formats, Gmsh mesh size fields, Top
@chapter Gmsh plugins

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

This chapter lists all the plugins that are bundled in the official Gmsh
distribution. 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), in the scripting language
(@pxref{Post-processing scripting commands}) and in the API
(@pxref{Namespace gmsh/plugin}).  See @ref{t9} for an example on how to
use plugins.

@include plugins.texi

@c =========================================================================
@c Gmsh file formats
@c =========================================================================

@node Gmsh file formats, Compiling the source code, Gmsh plugins, Top
@chapter Gmsh 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 scripting commands}. Such ``parsed'' views do not
require an underlying mesh, and can therefore be easier to use in some
cases.)

@menu
* MSH file format::
* Node ordering::
* Legacy formats::
@end menu

@c -------------------------------------------------------------------------
@c MSH file format
@c -------------------------------------------------------------------------

@node MSH file format, Node ordering, Gmsh file formats, Gmsh file formats
@section MSH file format

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

The MSH file format version 4 (current revision: version 4.1) contains
one mandatory section giving information about the file
(@code{$MeshFormat}), followed by several optional sections defining the
physical group names (@code{$PhysicalName}), the elementary model
entities (@code{$Entities}), the partitioned entities
(@code{$PartitionedEntities}), the nodes (@code{$Nodes}), the elements
(@code{$Elements}), the periodicity relations (@code{$Periodic}), the
ghost elements (@code{$GhostElements}), the parametrizations
(@code{$Parametrizations}) and the post-processing datasets
(@code{$NodeData}, @code{$ElementData}, @code{$ElementNodeData}). The
sections reflect the underlying Gmsh data model: @code{$Entities} store
the boundary representation of the model geometrical entities,
@code{$Nodes} and @code{$Elements} store mesh data classified on these
entities, and @code{$NodeData}, @code{$ElementData},
@code{$ElementNodeData} store post-processing data (views). (See
@ref{Gmsh application programming interface} and @ref{Source code structure} for a more detailed
description of the internal Gmsh data model.)

To represent a simple mesh, the minimal sections that should be present
in the file are @code{$MeshFormat}, @code{$Nodes} and
@code{$Elements}. Nodes are assumed to be defined before elements. To
represent a mesh with the full topology (BRep) of the model and
associated physical groups, an @code{$Entities} section should be
present before the @code{$Nodes} 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). 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.

All the node, element and entity tags (their global identification
numbers) should be strictly positive. (Tag @code{0} is reserved for
internal use.)  Important note about efficiency: tags can be "sparse",
i.e., do not have to constitute a continuous list of numbers (the format
even allows them to not be ordered). However, using sparse tags can lead
to performance degradation. For meshes, sparse indexing can@footnote{If
the numbering is not too sparse, Gmsh will still use a vector.} force
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. By default, for
non-partitioned, single file meshes, Gmsh will create files with a
continuous ordering of node and element tags, starting at 1. Detecting
if the numbering is continuous can be done easily when reading a file by
inspecting @code{numNodes}, @code{minNodeTag} and @code{maxNodeTag} in
the @code{$Nodes} section; and @code{numElements}, @code{minElementTag}
and @code{maxElementTag} in the @code{$Elements} section.

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 the format description below are written in binary form,
using the type given between parentheses. The block structure of the
@code{$Nodes} and @code{$Elements} sections allows to read integer and
floating point data in each block in a single step (e.g. using
@code{fread} in C).

The format is defined as follows:

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

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

$Entities
  numPoints(size_t) numCurves(size_t)
    numSurfaces(size_t) numVolumes(size_t)
  pointTag(int) X(double) Y(double) Z(double)
    numPhysicalTags(size_t) physicalTag(int) ...
  ...
  curveTag(int) minX(double) minY(double) minZ(double)
    maxX(double) maxY(double) maxZ(double)
    numPhysicalTags(size_t) physicalTag(int) ...
    numBoundingPoints(size_t) pointTag(int; sign encodes orientation) ...
  ...
  surfaceTag(int) minX(double) minY(double) minZ(double)
    maxX(double) maxY(double) maxZ(double)
    numPhysicalTags(size_t) physicalTag(int) ...
    numBoundingCurves(size_t) curveTag(int; sign encodes orientation) ...
  ...
  volumeTag(int) minX(double) minY(double) minZ(double)
    maxX(double) maxY(double) maxZ(double)
    numPhysicalTags(size_t) physicalTag(int) ...
    numBoundngSurfaces(size_t) surfaceTag(int; sign encodes orientation) ...
  ...
$EndEntities

$PartitionedEntities
  numPartitions(size_t)
  numGhostEntities(size_t)
    ghostEntityTag(int) partition(int)
    ...
  numPoints(size_t) numCurves(size_t)
    numSurfaces(size_t) numVolumes(size_t)
  pointTag(int) parentDim(int) parentTag(int)
    numPartitions(size_t) partitionTag(int) ...
    X(double) Y(double) Z(double)
    numPhysicalTags(size_t) physicalTag(int) ...
  ...
  curveTag(int) parentDim(int) parentTag(int)
    numPartitions(size_t) partitionTag(int) ...
    minX(double) minY(double) minZ(double)
    maxX(double) maxY(double) maxZ(double)
    numPhysicalTags(size_t) physicalTag(int) ...
    numBoundingPoints(size_t) pointTag(int) ...
  ...
  surfaceTag(int) parentDim(int) parentTag(int)
    numPartitions(size_t) partitionTag(int) ...
    minX(double) minY(double) minZ(double)
    maxX(double) maxY(double) maxZ(double)
    numPhysicalTags(size_t) physicalTag(int) ...
    numBoundingCurves(size_t) curveTag(int) ...
  ...
  volumeTag(int) parentDim(int) parentTag(int)
    numPartitions(size_t) partitionTag(int) ...
    minX(double) minY(double) minZ(double)
    maxX(double) maxY(double) maxZ(double)
    numPhysicalTags(size_t) physicalTag(int) ...
    numBoundingSurfaces(size_t) surfaceTag(int) ...
  ...
$EndPartitionedEntities

$Nodes
  numEntityBlocks(size_t) numNodes(size_t)
    minNodeTag(size_t) maxNodeTag(size_t)
  entityDim(int) entityTag(int) parametric(int; 0 or 1)
    numNodesInBlock(size_t)
    nodeTag(size_t)
    ...
    x(double) y(double) z(double)
       < u(double; if parametric and entityDim >= 1) >
       < v(double; if parametric and entityDim >= 2) >
       < w(double; if parametric and entityDim == 3) >
    ...
  ...
$EndNodes

$Elements
  numEntityBlocks(size_t) numElements(size_t)
    minElementTag(size_t) maxElementTag(size_t)
  entityDim(int) entityTag(int) elementType(int; see below)
    numElementsInBlock(size_t)
    elementTag(size_t) nodeTag(size_t) ...
    ...
  ...
$EndElements

$Periodic
  numPeriodicLinks(size_t)
  entityDim(int) entityTag(int) entityTagMaster(int)
  numAffine(size_t) value(double) ...
  numCorrespondingNodes(size_t)
    nodeTag(size_t) nodeTagMaster(size_t)
    ...
  ...
$EndPeriodic

$GhostElements
  numGhostElements(size_t)
  elementTag(size_t) partitionTag(int)
    numGhostPartitions(size_t) ghostPartitionTag(int) ...
  ...
$EndGhostElements

$Parametrizations
  numCurveParam(size_t) numSurfaceParam(size_t)
  curveTag(int) numNodes(size_t)
    nodeX(double) nodeY(double) nodeZ(double) nodeU(double)
    ...
  ...
  surfaceTag(int) numNodes(size_t) numTriangles(size_t)
    nodeX(double) nodeY(double) nodeZ(double)
      nodeU(double) nodeV(double)
      curvMaxX(double) curvMaxY(double) curvMaxZ(double)
      curvMinX(double) curvMinY(double) curvMinZ(double)
    ...
    nodeIndex1(int) nodeIndex2(int) nodeIndex3(int)
    ...
  ...
$EndParametrizations

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

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

$ElementNodeData
  numStringTags(ASCII int)
  stringTag(string) ...
  numRealTags(ASCII int)
  realTag(ASCII double) ...
  numIntegerTags(ASCII int)
  integerTag(ASCII int) ...
  elementTag(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

In the format description above, @code{elementType} 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)
@item ...
@end table
All the currently supported elements in the format are defined in
@url{https://gitlab.onelab.info/gmsh/gmsh/blob/master/src/common/GmshDefines.h,GmshDefines.h}. See
@ref{Node ordering} for the ordering of the nodes.

The post-processing sections (@code{$NodeData}, @code{$ElementData},
@code{$ElementNodeData}) can contain @code{numStringTags} string tags,
@code{numRealTags} real value tags and @code{numIntegerTags} integer
tags. The default set of tags understood by Gmsh is as follows:
@table @code
@item stringTag
The first is interpreted as the name of the post-processing view and the
second as the name of the interpolation scheme, as provided in the
@code{$InterpolationScheme} section.
@item realTag
The first is interpreted as a time value associated with the dataset.
@item integerTag
The first 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).
@end table

In the @code{$InterpolationScheme} section:
@table @code
@item numElementTopologies
is the number of element topologies for which interpolation matrices are
provided.
@item elementTopology
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 numInterpolationMatrices
is the number of interpolation matrices provided for the given element
topology. Currently you should provide 2 matrices, i.e., the matrices
that specify how to interpolate the data (they have the same meaning as
in @ref{Post-processing scripting commands}). The matrices are specified by 2
integers (@code{numRows} and @code{numColumns}) followed by the values,
by row.
@end table

Here is a small example of a minimal ASCII MSH4.1 file, with a mesh
consisting of two quadrangles and an associated nodal scalar dataset
(the comments are not part of the actual file):

@example
$MeshFormat
4.1 0 8     @emph{MSH4.1, ASCII}
$EndMeshFormat
$Nodes
1 6 1 6     @emph{1 entity bloc, 6 nodes total, min/max node tags: 1 and 6}
2 1 0 6     @emph{2D entity (surface) 1, no parametric coordinates, 6 nodes}
1           @emph{  node tag #1}
2           @emph{  node tag #2}
3           @emph{  etc.}
4
5
6
0. 0. 0.    @emph{  node #1 coordinates (0., 0., 0.)}
1. 0. 0.    @emph{  node #2 coordinates (1., 0., 0.)}
1. 1. 0.    @emph{  etc.}
0. 1. 0.
2. 0. 0.
2. 1. 0.
$EndNodes
$Elements
1 2 1 2     @emph{1 entity bloc, 2 elements total, min/max element tags: 1 and 2}
2 1 3 2     @emph{2D entity (surface) 1, element type 3 (4-node quad), 2 elements}
1 1 2 3 4   @emph{  quad tag #1, nodes 1 2 3 4}
2 2 5 6 3   @emph{  quad tag #2, nodes 2 5 6 3}
$EndElements
$NodeData
1           @emph{1 string tag:}
"My view"   @emph{  the name of the view ("My view")}
1           @emph{1 real tag:}
0.0         @emph{  the time value (0.0)}
3           @emph{3 integer tags:}
0           @emph{  the time step (0; time steps always start at 0)}
1           @emph{  1-component (scalar) field}
6           @emph{  6 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 example

The 4.1 revision of the format includes the following modifications with
respect to the initial 4.0 version:
@itemize @bullet
@item
All the @code{unsigned long} entries have been changed to
@code{size_t}. All the entries designating counts which were previously
encoded as @code{int} have also been changed to @code{size_t}. (This
only impacts binary files.)
@item
The @code{$Entities} section is now optional.
@item
Integer and floating point data in the @code{$Nodes} section is not
mixed anymore: all the tags are given first, followed by all the
coordinates.
@item
The bounding box for point entities has been replaced simply by the 3
coordinates of the point (instead of the six bounding box values).
@item
The @code{entityDim} and @code{entityTag} values have been switched in
the @code{$Nodes} and @code{$Elements} sections (for consistency with
the ordering used elsewhere in the file and in the @ref{Gmsh application programming interface}).
@item
The minimum and the maximum tag of nodes (resp. elements) have been
added in the header of the @code{$Nodes} (resp. @code{$Elements})
section, to facilitate the detection of sparse or dense numberings when
reading the file.
@item
The @code{$Periodic} section has been changed to always provide the
number of values in the affine transform (which can be zero, if the
transform is not provided).
@end itemize

The following changes are foreseen in a future revision of the MSH format:
@itemize @bullet
@item
The @code{$GhostElements}, @code{$NodeData}, @code{$ElementData} and
@code{$ElementNodeData} will be reworked for greater IO efficiency, with
separation of entries by type and a block structure with predictable
sizes.
@item
Node and element tags in @code{$NodeData}, @code{$ElementData} and
@code{$ElementNodeData} will be switched to @code{size_t}.
@end itemize

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

@node Node ordering, Legacy formats, MSH file format, Gmsh file formats
@section Node ordering

@cindex Nodes, ordering

Historically, Gmsh first supported linear elements (lines, triangles,
quadrangles, tetrahedra, prisms and hexahedra). Then, support for second
and some third order elements has been added. Below we distinguish such
``low order elements'', which are hardcoded (i.e. they are explicitly
defined in the code), and general ``high-order elements'', that have
been coded in a more 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.

@example
@group
Line:                  Line3:           Line4:

      v
      ^
      |
      |
0-----+-----1 --> u    0----2----1      0---2---3---1

@end group
@end example

@example
@group
Triangle:               Triangle6:          Triangle9/10:

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

@end group
@end example

@example
@group
Triangle12/15:

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

@end group
@end example

@example
@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 example

@example
@group
Tetrahedron:                          Tetrahedron10:

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

@example
@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 example

@example
@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 example

@example
@group
Pyramid:                     Pyramid13:

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

@example
@group
Pyramid14:

               4
             ,/|\
           ,/ .'|\
         ,/   | | \
       ,/    .' | `.
     ,7      |  12  \
   ,/       .'   |   \
 ,/         9    |    11
0--------6-.'----3    `.
  `\        |      `\    \
    `5     .' 13     10   \
      `\   |           `\  \
        `\.'             `\`
           1--------8-------2
                    `\
                       u
@end group
@end example

@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, Gmsh 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 (Legacy)::
* MSH file format version 1 (Legacy)::
* POS ASCII file format (Legacy)::
* POS binary file format (Legacy)::
@end menu

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

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

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}. It 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}
<Affine @var{value} ...>
@var{dimension} @var{entity-tag} @var{master-entity-tag}
@var{number-of-nodes}
@var{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 positive (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 positive (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}.

@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 model 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 scripting 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!):

@example
$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, phys 99, ent 2, nodes 1 2 3 4}
2 3 2 99 2 2 5 6 3 @emph{  quad #2: type 3, phys 99, ent 2, nodes 2 5 6 3}
$EndElements
$NodeData
1                  @emph{one string tag:}
"My view"          @emph{  the name of the view ("My 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 example

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 group and elementary entity):
@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 (Legacy), POS ASCII file format (Legacy), MSH file format version 2 (Legacy), Legacy formats
@subsection MSH file format version 1 (Legacy)

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}. 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 positive (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 positive (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 positive 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 positive (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 (Legacy), POS binary file format (Legacy), MSH file format version 1 (Legacy), 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}. 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 (Legacy),  , POS ASCII file format (Legacy), 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 (Legacy)}, 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 Compiling the source code
@c =========================================================================

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

Stable releases and source snapshots are available from
@url{https://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{@value{GITLAB-PREFIX}/README.txt,README.txt} file in
the top-level source directory for additional information on how to run
CMake, as well as the
@url{https://gitlab.onelab.info/gmsh/gmsh/wikis/Gmsh-compilation,
Gmsh-compilation wiki page} for more detailed instructions on how to
compile Gmsh, including the compilation of common dependencies).

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

@table @code

@include cmake_options.texi

@end table

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

@node Information for developers, Frequently asked questions, Compiling the source code, 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 widgets (menus,
buttons, etc.). Gmsh's build system is based on CMake
(@uref{http://www.cmake.org}). Practical notes on how to compile Gmsh's
source code are 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{@value{GITLAB-PREFIX}/src/geo,src/geo},
@url{@value{GITLAB-PREFIX}/src/mesh,src/mesh},
@url{@value{GITLAB-PREFIX}/src/solver,src/solver},
@url{@value{GITLAB-PREFIX}/src/post,src/post}) and
associated utilities
(@url{@value{GITLAB-PREFIX}/src/common,src/common},
@url{@value{GITLAB-PREFIX}/src/numeric,src/numeric})
on one hand, and the graphics
(@url{@value{GITLAB-PREFIX}/src/graphics,src/graphics})
and interface
(@url{@value{GITLAB-PREFIX}/src/fltk,src/fltk},
@url{@value{GITLAB-PREFIX}/src/parser,src/parser},
@url{@value{GITLAB-PREFIX}/api,api}) code on
the other.

The geometry module is based on a model class
(@url{@value{GITLAB-PREFIX}/src/geo/GModel.h,src/geo/GModel.h}),
and abstract entity classes for geometrical points
(@url{@value{GITLAB-PREFIX}/src/geo/GVertex.h,src/geo/GVertex.h}),
curves
(@url{@value{GITLAB-PREFIX}/src/geo/GEdge.h,src/geo/GEdge.h}),
surfaces
(@url{@value{GITLAB-PREFIX}/src/geo/GFace.h,src/geo/GFace.h})
and volumes
(@url{@value{GITLAB-PREFIX}/src/geo/GRegion.h,src/geo/GRegion.h}).
Concrete implementations of these classes are provided for each
supported CAD kernel
(e.g. @url{@value{GITLAB-PREFIX}/src/geo/gmshVertex.h,src/geo/gmshVertex.h}
for points in Gmsh's built-in CAD kernel, or
@url{@value{GITLAB-PREFIX}/src/geo/OCCVertex.h,src/geo/OCCVertex.h}
for points from OpenCASCADE). All these elementary model entities derive
from
@url{@value{GITLAB-PREFIX}/src/geo/GEntity.h,src/geo/GEntity.h}.
Physical groups are simply stored as integer tags in the entities.

A mesh is composed of elements: mesh points
(@url{@value{GITLAB-PREFIX}/src/geo/MPoint.h,src/geo/MPoint.h}),
lines
(@url{@value{GITLAB-PREFIX}/src/geo/MLine.h,src/geo/MLine.h}),
triangles
(@url{@value{GITLAB-PREFIX}/src/geo/MTriangle.h,src/geo/MTriangle.h}),
quadrangles
(@url{@value{GITLAB-PREFIX}/src/geo/MQuadrangle.h,src/geo/MQuadrangle.h}),
tetrahedra
(@url{@value{GITLAB-PREFIX}/src/geo/MTetrahedron.h,src/geo/MTetrahedron.h}),
etc. All the mesh elements are derived from
@url{@value{GITLAB-PREFIX}/geo/MElement.h,src/geo/MElement.h},
and are stored in the corresponding model entities: one mesh point per
geometrical point, mesh lines in geometrical curves, triangles and
quadrangles in surfaces, etc. The elements are defined in terms of their
nodes
(@url{@value{GITLAB-PREFIX}/src/geo/MVertex.h,src/geo/MVertex.h}).
Each model entity stores only its internal nodes: nodes on boundaries or
on embedded entities are stored in the associated bounding/embedded
entity.

The post-processing module is based on the concept of views
(@url{@value{GITLAB-PREFIX}/src/post/PView.h,src/post/PView.h}) and
abstract data containers (derived from
@url{@value{GITLAB-PREFIX}/src/post/PViewData.h,src/post/PViewData.h}).
Data can be either mesh-based
(@url{@value{GITLAB-PREFIX}/src/post/PViewDataGModel.h,src/post/PViewDataGModel.h}),
in which case the view is linked to one or more models, or list-based
(@url{@value{GITLAB-PREFIX}/src/post/PViewDataList.h,src/post/PViewDataList.h}),
in which case all the relevant geometrical information is self-contained
in the view.

@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:

@itemize
@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 warnings 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{@value{GITLAB-PREFIX}/.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, on Linux you can use
@code{valgrind --leak-check=full gmsh file.geo -3}.
@c macOS: (gdb) set env DYLD_INSERT_LIBRARIES /usr/lib/libgmalloc.dylib
@c export LD_PRELOAD=libnjamd.so kill -USR1
@c macOS: (lldb) env DYLD_INSERT_LIBRARIES=/usr/lib/libgmalloc.dylib
@end itemize

@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{@value{GITLAB-PREFIX}/src/common/Context.h,src/common/Context.h}
if it's a classical option, or in the @code{PViewOptions} class
(@url{@value{GITLAB-PREFIX}/src/post/PViewOptions.h,src/post/PViewOptions.h})
if it's a post-processing view-dependent option;
@item
in
@url{@value{GITLAB-PREFIX}/src/common/DefaultOptions.h,src/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{@value{GITLAB-PREFIX}/src/common/Options.cpp,src/common/Options.cpp}
(and add the prototype in
@url{@value{GITLAB-PREFIX}/src/common/Options.h,src/common/Options.h});
@item
optional: create the associated widget in
@url{@value{GITLAB-PREFIX}/src/fltk/optionWindow.cpp,src/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 library
to integrate in C++, C, Python, Julia or Fortran codes.

@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 application programming
interface}). See @ref{Copying conditions} for the licensing constraints.

@item Where can I find more information?

@url{https://gmsh.info} is the primary location to obtain information
about Gmsh. There you will for example find the complete reference
manual and the @url{https://gitlab.onelab.info/gmsh/gmsh/issues,bug
tracking database}.
@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, macOS, Linux and most Unix variants. Gmsh is also
available as part of the ONELAB package on Android and iOS tablets and
phones.

@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} 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 macOS) 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 switch).

@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 save high-resolution images?

You can specify the dimension in the dialog (e.g. set the width of the
image to 5000 pixels; leaving one dimension negative will rescale using
the natural aspect ratio), or through the @code{Print.Width} and
@code{Print.Height} options. The maximum image size is graphics hardware
dependent.

@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} or
@url{@value{GITLAB-PREFIX}/examples/post_processing/anim.script,examples/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 trimmed NURBS surfaces?

Yes, but only with the OpenCASCADE kernel.

@item Gmsh is very slow when I use many transformations (Translate, Rotate, Symmetry, Extrude, etc.) with the built-in CAD kernel. 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 with the built-in CAD kernel. 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 serialized (``unrolled'') geometry in another file
(using @code{gmsh file.geo -0} or exporting to ``.geo_unrolled''), 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 @file{.geo} files (e.g. before the creation
of curve loops, etc.).
@end itemize

@item Why is my ``.geo_unrolled'' file incomplete?

``Unrolled GEO'' files can only fully represent geometries created with
the built-in geometry kernel. If you want to serialize a geometry
created with the OpenCASCADE geometry kernel, you should use the native
OpenCASCADE ``.brep'' format.

@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. See
e.g. @url{@value{GITLAB-PREFIX}/examples/boolean/import.geo,examples/boolean/import.geo}.

@item Why are there surfaces missing when I export a STEP as an unrolled @file{.geo} file?

You should @emph{not} export STEP models as @file{.geo} files. By
design, Gmsh never translates from one CAD format to another. The
``unrolled GEO'' feature is there for unrolling complex GEO scripts
writted with the built-in geometry kernel. While it can indeed export a
limited subset of geometrical entities created by other CAD kernels
(e.g. OpenCASCADE), this feature is available for debugging purposes.

@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. Or use
the features of your language of choice and the Gmsh API.

@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 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 How can I remove mesh nodes for geometrical construction points (centers of spheres, etc.) from output mesh file?

By default Gmsh saves all the geometrical entities and their associated
mesh. In particular, since each geometry point is meshed with a point
element, defined by a mesh node, the output file will contain one 0-D
mesh element and one mesh node for each geometry point. To remove such
elements/nodes from the mesh, simply define physical groups for the
entities you want to save (see previous question).

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

Yes, but only if pyramids need to be created on a single side of the
quadrangular surface mesh.

@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 also available in the
mesh menu. You can select the order on the command line with e.g.
@code{-order 2}, and activcate high-order optimization with
@code{-optimize_ho}.

@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{@value{GITLAB-PREFIX}/examples/simple_geo/sphere-discrete.geo,examples/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}) for a detailed
description and some examples.

The Gmsh API can be used to build sophisticated interactive workflows
where the definition of boundary conditions and material properties can
be fully tailored to your preferred solver. For an example see
@url{@value{GITLAB-PREFIX}/examples/api/prepro.py,examples/api/prepro.py}.

@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' 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{@value{GITLAB-PREFIX}/src/geo/MElement.cpp,src/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 @file{.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
explicitly, and just choose a filename with the @code{.msh2} or
@code{.msh4} extension.

@item Why isn't neighboring element information stored in the MSH file?

Each numerical method has its own requirements: it might need
neighboring elements connected by a node, an edge or a face; it might
require a single layer or multiple layers; it should include elements of
lower dimension (boundaries) or not, go across geometrical entities or
mesh partitions or not, etc. Given the number of possibilities,
generating the appropriate information is thus best performed in the
numerical solver itself. The Gmsh API makes these computations easy: see
tutorial @ref{x7} and
@url{@value{GITLAB-PREFIX}/examples/api/neighbors.py,examples/api/neighbors.py}.

@item Could mesh edges/faces be stored in the MSH file?

Edge/faces can be easily generated from the information already
available in the file (i.e. nodes and elements), or through the Gmsh
API: see tutorial @ref{x7},
@url{@value{GITLAB-PREFIX}/examples/api/edges.cpp,examples/api/edges.cpp} and
@url{@value{GITLAB-PREFIX}/examples/api/faces.cpp,examples/api/faces.cpp}.

@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. See @ref{Solver module}.

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

Using the Gmsh API, you can directly embed Gmsh in your own solver, use
ONELAB for interactive parameter definition and modification, and create
visualization data on the fly. See e.g.
@url{@value{GITLAB-PREFIX}/examples/api/prepro.py,prepro.py},
@url{@value{GITLAB-PREFIX}/examples/api/custom_gui.py,custom_gui.py},
@url{@value{GITLAB-PREFIX}/examples/api/custom_gui.cpp,custom_gui.cpp}.

Another (rather crude) approach if to launch the Gmsh app everytime you
want to visualize something (a simple C program showing how to do this
is given in
@url{@value{GITLAB-PREFIX}/utils/misc/callgmsh.c,utils/misc/callgmsh.c}).

Yet another approach is to modify your program so that it can
communicate with Gmsh through ONELAB over a socket. Select `Always
listen to incoming connection requests' in the Gmsh solver option panel
(or run gmsh with the @code{-listen} command line switch), and Gmsh will
always listen for your program on the given socket (or on the
@code{Solver.SocketName} if no socket is specified).

@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->Isosurface' 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} or
@url{@value{GITLAB-PREFIX}/examples/post_processing/anim.script,examples/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'.

When viewing 3D scalar fields, you can also modify the colormap
(`Tools->Options->View->Map') to make the iso-surfaces ``transparent'':
either by holding @kbd{Ctrl} while dragging the mouse to draw the alpha
channel by hand, or by using the @kbd{a}, @kbd{Ctrl+a}, @kbd{p} and
@kbd{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

@format
@verbatiminclude ../../CHANGELOG.txt
@end format

@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

@format
@verbatiminclude ../../CREDITS.txt
@end format

@c =========================================================================
@c License
@c =========================================================================

@node License, Concept index, Copyright and credits, Top
@appendix License

@cindex License

@format
@verbatiminclude ../../LICENSE.txt
@end format

@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
