\input texinfo.tex @c -*-texinfo-*-
@c $Id: gmsh.texi,v 1.196 2006/01/14 22:32:58 geuzaine Exp $
@c
@c Copyright (C) 1997-2006 C. Geuzaine, J.-F. Remacle
@c
@c This program is free software; you can redistribute it and/or modify
@c it under the terms of the GNU General Public License as published by
@c the Free Software Foundation; either version 2 of the License, or
@c (at your option) any later version.
@c
@c This program is distributed in the hope that it will be useful,
@c but WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with this program; if not, write to the Free Software
@c Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
@c USA.
@c 
@c Please report all bugs and problems to <gmsh@geuz.org>.
@c
@c =========================================================================
@c
@c This is the Gmsh documentation texinfo source file
@c
@c Things to do -> "Ctrl+s todo:" 
@c
@c Indexing:
@c
@c * @cindex = concept index, e.g. "File formats"
@c * @tindex + @findex = type + function index, e.g. "Sqrt(expression)"
@c
@c Before release, run C-u C-c C-u C-a in GNU Emacs. This updates all node
@c pointers and menus.
@c 
@c =========================================================================
@c %**start of header
@setfilename        gmsh.info
@set EDITION        1.33
@set GMSH-VERSION   1.62
@set COPYRIGHT      @copyright{} 1997-2006 Christophe Geuzaine, Jean-Fran@,{c}ois Remacle
@c
@settitle Gmsh @value{GMSH-VERSION}
@footnotestyle separate
@setchapternewpage odd
@paragraphindent 0
@finalout
@c %**end of header

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

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

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

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

@shorttitlepage Gmsh

@titlepage

@title Gmsh Reference Manual

@subtitle The documentation for Gmsh @value{GMSH-VERSION}
@subtitle A finite element mesh generator with built-in pre- and post-processing facilities
@subtitle 
@subtitle Edition @value{EDITION} (@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 =========================================================================

@summarycontents
@contents

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

@ifnottex
@node Top, Copying conditions, (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 edition @value{EDITION} (@today{}) of
the @cite{Gmsh Reference Manual}, for Gmsh @value{GMSH-VERSION}.
@end ifnottex

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

@menu
* Copying conditions::          Terms and conditions of use.
* Overview::                    What is Gmsh?
* General tools::               Description of general commands and options.
* Geometry module::             Description of all Geometry commands.
* Mesh module::                 Description of all Mesh commands.
* Solver module::               Description of all Solver commands.
* Post-processing module::      Description of all Post-Processing commands.
* Tutorial::                    A step-by-step tutorial.
* Running Gmsh::                How to run Gmsh on your operating system.
* File formats::                Input and output file formats.
* Programming notes::           Random notes for developers.
* Bugs and versions::           Contact information and ChangeLog
* Tips and tricks::             Some tips to make your life easier with Gmsh.
* Frequently asked questions::  The Gmsh FAQ
* License::                     Complete copy of the license.
* Concept index::               Index of concepts.
* Syntax index::                Index of reserved keywords in the Gmsh language.

@detailmenu
 --- The Detailed Node Listing ---

Overview

* Geometry::                    
* Mesh::                        
* Solver::                      
* Post-processing::             
* What Gmsh is pretty good at::  
* and what Gmsh is not so good at::  
* Syntactic rules::             
* Comments::                    

General tools

* Expressions::                 
* Operators::                   
* Built-in functions::          
* User-defined functions::      
* Loops and conditionals::      
* General commands::            
* General options::             

Expressions 

* Floating point expressions::  
* Character expressions::       
* Color expressions::           

Geometry module

* Geometry commands::           
* Geometry options::            

Geometry commands

* Points::                      
* Lines::                       
* Surfaces::                    
* Volumes::                     
* Extrusions::                  
* Transformations::             
* Miscellaneous geometry commands::  

Mesh module

* Elementary vs physical entities::  
* Mesh commands::               
* Mesh options::                

Mesh commands

* Characteristic lengths::      
* Structured grids::            
* Miscellaneous mesh commands::  

Solver module

* Solver options::              
* Solver example::              

Post-processing module

* Post-processing commands::    
* Post-processing plugins::     
* Post-processing options::     

Tutorial

* t1.geo::                      
* t2.geo::                      
* t3.geo::                      
* t4.geo::                      
* t5.geo::                      
* t6.geo::                      
* t7.geo::                      
* t8.geo::                      
* t9.geo::                      

Running Gmsh

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

File formats

* Gmsh mesh file formats::      
* Gmsh post-processing file formats::  
* Gmsh node ordering::          

Gmsh mesh file formats

* Version 1.0::                 
* Version 2.0::                 

Gmsh post-processing file formats

* Parsed post-processing file format::  
* ASCII post-processing file format::  
* Binary post-processing file format::  

Programming notes

* Coding style::                
* Option handling::             

Bugs, versions and credits

* Bugs::                        
* Versions::                    
* Credits::                     

@end detailmenu
@end menu

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

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

@cindex Copyright
@cindex License

@include copying.texi

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

@node Overview, General tools, Copying conditions, Top
@chapter Overview

@cindex Introduction
@cindex Overview

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

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

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

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

@node Geometry, Mesh, Overview, Overview
@section Geometry: geometrical entity definition

Geometries are created in a bottom-up flow by successively defining points,
oriented lines (line segments, circles, ellipses, splines, @dots{}),
oriented surfaces (plane surfaces, ruled surfaces, triangulated surfaces,
@dots{}) and volumes. Compound groups of geometrical entities can be
defined, based on these elementary geometric entities. Gmsh's scripting
language allows all geometrical entities to be fully parameterized.

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

@node Mesh, Solver, Geometry, Overview
@section Mesh: finite element mesh generation

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

The mesh generation is performed in the same bottom-up flow as the geometry
creation: lines are discretized first; the mesh of the lines is then used to
mesh the surfaces; then the mesh of the surfaces is used to mesh the
volumes. In this process, the mesh of an entity is only constrained by the
mesh of its boundary@footnote{For example, in three dimensions:

@itemize @bullet
@item
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;
@item
the line elements discretizing a curve will be forced to be edges of
tetrahedra in the final 3D mesh only if the curve is part of the boundary of
a surface, itself part of the boundary of a volume;
@item
a single node discretizing a point in the middle of a volume will be forced
to be a vertex of one of the tetrahedra in the final 3D mesh only if this
point is connected to a curve, itself part of the boundary of a surface,
itself part of the boundary of a volume...
@end itemize
}. This automatically assures the conformity of the mesh when, for example,
two surfaces share a common line. But this also implies that the
discretization of an ``isolated'' (@var{n}-1)-th dimensional entity inside
an @var{n}-th dimensional entity does @emph{not} constrain the @var{n}-th
dimensional mesh.  Every meshing step is constrained by the characteristic
length field, which can be uniform, specified by characteristic lengths
associated with elementary geometrical entities, or associated with another
mesh (the background mesh).

For each meshing step, all structured mesh directives are executed first,
and serve as additional constraints for the unstructured parts. The
implemented Delaunay algorithm is subdivided in the following five steps for
surface/volume discretization:

@enumerate
@item
trivial meshing of a box including the convex polygon/polyhedron defined by
the boundary nodes resulting from the discretization of the lines/surfaces;
@item
creation of the initial mesh by insertion of all the nodes on the
lines/surfaces thanks to the Bowyer algorithm;
@item
boundary restoration to force all the edges/faces of the lines/surfaces to
be present in the initial mesh;
@item
suppression of all the unwanted triangles/tetrahedra (in particular those
containing the nodes of the initial box);
@item
insertion of new nodes by the Bowyer algorithm until the characteristic size
of each simplex is lower or equal to the characteristic length field
evaluated at the center of its circumscribed circle/sphere.
@end enumerate

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

@node Solver, Post-processing, Mesh, Overview
@section Solver: external solver interface

External solvers can be interfaced with Gmsh through Unix or TCP/IP sockets,
which permits to easily launch external computations and to collect and
exploit the simulation results within Gmsh's post-processing module. The
default solver interfaced with Gmsh is GetDP
(@uref{http://www.geuz.org/getdp/}). Small examples of solvers written in C,
C++, Perl and Python are available in the source distribution (in the
@file{utils/solvers/} directory).

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

@node Post-processing, What Gmsh is pretty good at, Solver, Overview
@section Post-processing: scalar, vector and tensor field visualization

Multiple post-processing scalar, vector or tensor maps can be loaded and
manipulated (globally or individually) along with the geometry and the
mesh. Scalar fields are represented by iso-value lines/surfaces or color
maps, while vector fields are represented by three-dimensional arrows or
displacement maps. Post-processing functions include section computation,
offset, elevation, boundary and component extraction, color map and range
modification, animation, vector graphic output, etc. All post-processing
options can be accessed either interactively or through the input ASCII text
files. Scripting permits to automate all post-processing operations, e.g.,
for the creation of animations. User-defined operations can also be
performed on post-processing views through dynamically loadable plugins.

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

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

Gmsh is a (relatively) small program, and was principally developed ``in
academia, to solve academic problems''@dots{} Nevertheless, over the
years, many people outside universities have found Gmsh useful in their
day-to-day jobs. Here is a tentative list of what Gmsh does best:

@itemize @bullet
@item
quickly describe simple and/or ``repetitive'' geometries, thanks to
user-defined functions, loops, conditionals and includes (see
@ref{User-defined functions}, @ref{Loops and conditionals}, and @ref{General
commands});
@item
parameterize these geometries. Gmsh's scripting language enables all
commands and command arguments to depend on previous calculations (see
@ref{Expressions}, and @ref{Geometry commands});
@item
generate 1D, 2D and 3D simplicial (i.e., using line segments, triangles and
tetrahedra) finite element meshes. The performance of the 1D and 2D
algorithms is pretty good; the 3D algorithm is still experimental and slow
(see @ref{Mesh module}, and @ref{Tutorial});
@item
specify target element sizes accurately. Gmsh provides several mechanisms to
control the size of the elements in the final mesh: through interpolation
from geometrical point characteristic lengths or geometrical attractors, or
from user-defined background meshes (@pxref{Mesh commands});
@item
create simple extruded geometries and meshes (see @ref{Geometry commands},
and @ref{Mesh commands});
@item
interact with external solvers. Gmsh provides C, C++, Perl and Python
interfaces, and others can be easily added (@pxref{Solver module});
@item
visualize computational results in a great variety of ways. Gmsh can display
scalar, vector and tensor data sets, and can perform various operations on
the resulting post-processing views (@pxref{Post-processing module});
@item
export plots in many different formats: vector PostScript or encapsulated
PostScript, LaTeX, PNG, JPEG, @dots{} (@pxref{General options});
@item
generate complex animations (see @ref{General tools}, and @ref{t8.geo});
@item
run on low end machines and/or machines with no graphic system. Gmsh can be
compiled with or without the graphical user interface, and all versions can
be used either interactively or not, directly from the command line
(@pxref{Running Gmsh});
@item
configure your preferred options. Gmsh has a large number of configuration
options that can be set interactively using the GUI, scattered inside
command files, changed on the fly in scripts, set in per-user configuration
files, or specified on the command-line (see @ref{General options},
@ref{Geometry options}, @ref{Mesh options}, @ref{Post-processing options},
and @ref{Running Gmsh});
@item
and do all the above on various platforms (Windows, Mac and Unix), for free
(@pxref{Copying conditions}), using clear-text ASCII files and/or a small
but powerful graphical user interface.
@end itemize

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

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

Due to its historical background and limited developer manpower, Gmsh has
also some (a lot of?) weaknesses:

@itemize @bullet
@item
the bottom-up approach for describing geometries can become inconvenient for
complex models;
@item
there is no support for NURBS and only very limited support for trimmed
surfaces;
@item
Gmsh is not primarily a structured mesh generator: no automatic
quadrilateral or hexahedral meshing algorithm is provided. If you want
quadrangles, you have to use transfinite, elliptic or extruded meshes or
recombine unstructured triangular meshes. For hexahedra, your only choice is
transfinite or extruded meshes;
@item
Gmsh is not a multi-bloc generator: all meshes produced by Gmsh are
conforming in the sense of finite element meshes;
@item
the 2D anisotropic and the 3D unstructured algorithms are still experimental
and not very robust.  If these algorithms fail, try to change some
characteristic lengths to generate meshes that better suit the geometrical
details of the structures;
@item
Gmsh was designed to solve academic ``test cases'', not industrial-size
problems. You may find that Gmsh is too slow for large problems (with
thousands of geometric primitives, or millions of mesh/post-processing
elements).
@end itemize

If you have the skills and some free time, feel free to join the project! We
gladly accept any code contributions (@pxref{Programming notes}) to remedy
the aforementioned (and all other) shortcomings...

@c -------------------------------------------------------------------------
@c Syntactic Rules Used in this Document
@c -------------------------------------------------------------------------

@node Syntactic rules, Comments, and what Gmsh is not so good at, Overview
@section Syntactic rules used in this document

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

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

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

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

@node Comments,  , Syntactic rules, Overview
@section Comments

@cindex Comments
@cindex File, comments

@findex /*, */
@findex //

All Gmsh ASCII text input 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 General tools
@c =========================================================================

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

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

Note that, if you are just beginning to use Gmsh, or just want to see what
Gmsh is all about, you really don't need to read this chapter and the four
next ones. Just have a quick look at @ref{Running Gmsh}, and go play with
the graphical user interface, running the tutorials and demonstration files
bundled in the distribution! Most of the commands and options described in
the following chapters are available interactively in the GUI, so you don't
need to worry about Gmsh's internals for creating your first geometries,
meshes and post-processing plots. Once you master the tutorial (read the
source files: they are heavily commented---see @ref{Tutorial}), you might
want to come back here to learn more about the specific syntax of Gmsh's
commands and esoteric options.

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

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

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

@cindex Expressions, definition
@cindex Constants

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

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

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

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

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

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

@example
@var{expression}:
  @var{real} |
  @var{string} |
  @var{string} [ @var{expression} ] |
  # @var{string} [ ] |
  ( @var{expression} ) |
  @var{operator-unary-left} @var{expression} |
  @var{expression} @var{operator-unary-right} |
  @var{expression} @var{operator-binary} @var{expression} |
  @var{expression} @var{operator-ternary-left} @var{expression} @var{operator-ternary-right} @var{expression} |
  @var{built-in-function} |
  @var{real-option} |
  GetValue("@var{string}", @var{expression})
@end example

Such @w{@var{expression}s} are used in most of Gmsh's commands.  The third
and fourth cases in this definition permit to extract one item from a list
(see below) and get the size of a list, respectively. The operators
@var{operator-unary-left}, @var{operator-unary-right},
@var{operator-binary}, @var{operator-ternary-left} and
@var{operator-ternary-right} are defined in @ref{Operators}. For the
definition of @w{@var{built-in-function}s}, see @ref{Built-in
functions}. The various @w{@var{real-option}s} are listed in @ref{General
options}, @ref{Geometry options}, @ref{Mesh options}, @ref{Solver options},
and @ref{Post-processing options}.

The last case in the definition allows to ask the user for a value
interactively. 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.

@cindex Expressions, lists

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

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

@noindent with

@example
@var{expression-list-item}:
  @var{expression} |
  @var{expression} : @var{expression} |
  @var{expression} : @var{expression} : @var{expression} |
  @var{string} [ ] |
  @var{string} [ @{ @var{expression-list} @} ] |
  Point @{ @var{expression} @} |
  @var{transform} |
  @var{extrude}
@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 case permits to reference an expression list.
The fifth case permits to reference an expression sublist (whose elements
are those corresponding to the indices provided by the
@var{expression-list}). The sixth case permits to retrieve the coordinates
of a given geometry point (@pxref{Points}). The last two cases permit to
retrieve the indices of entities created through geometrical transformations
and extrusions (see @ref{Transformations}, and @ref{Extrusions}).

@c todo: explain in detail what numbers are returned once we decide what to
@c do (chapeau et body pour extrude, etc.)...

To see the practical use of such expressions, have a look at the first
couple of examples in @ref{Tutorial}. Note that, in order to lighten the
syntax, you can always 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}.

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

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

@cindex Expressions, character
@cindex Strings

Character expressions are defined as:

@example
@var{char-expression}:
  "@var{string}" |
  Today |
  StrPrefix ( @var{char-expression} ) |
  StrRelative ( @var{char-expression} ) |
  StrCat ( @var{char-expression} , @var{char-expression} ) |
  Sprintf ( @var{char-expression} , @var{expression-list} ) |
  Sprintf ( @var{char-expression} )
  Sprintf ( @var{char-option} )
@end example

@noindent The third and fourth cases in this definition permit to take the
prefix (e.g. to remove the extension) or the relative path of a string. The
fifth case permits to concatenate two character expressions, and the sixth
and seventh are equivalent to the @code{sprintf} C function (where
@var{char-expression} is a format string that can contain floating point
formatting characters: @code{%e}, @code{%g}, etc.). The last case permits to
use the value of a @var{char-option} as a @var{char-expression}.  The
various @w{@var{char-option}s} are listed in @ref{General options},
@ref{Geometry options}, @ref{Mesh options}, @ref{Solver options}, and
@ref{Post-processing options}.

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

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

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

@cindex Expressions, color
@cindex Colors

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

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

@noindent The first case permits to use the X Windows names to refer to colors,
e.g., @code{Red}, @code{SpringGreen}, @code{LavenderBlush3}, @dots{}
(see @file{Common/Colors.h} in Gmsh's source tree 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{General options},
@ref{Geometry options}, @ref{Mesh options}, @ref{Solver options}, and
@ref{Post-processing options}.

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

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

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

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

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

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

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

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

@noindent
@var{operator-ternary-left}:
@ftable @code
@item ?
@end ftable
@var{operator-ternary-right}:
@ftable @code
@item :
The only ternary operator, formed by @var{operator-ternary-left} and
@var{operator-ternary-right}, returns the value of its second argument if
the first argument is non-zero; otherwise it returns the value of its third
argument.
@end ftable

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

@findex ()

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@item 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 functions
@c -------------------------------------------------------------------------

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

@cindex Functions, user-defined

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

@ftable @code
@item Function @var{string}
Begins the declaration of a user-defined function named @var{string}. The
body of the function starts on the line after `@code{Function
@var{string}}', and can contain any Gmsh command.

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

@item Call @var{string};
Executes the body of a (previously defined) function named @var{string}.
@end ftable

See @ref{t5.geo}, for an example of a user-defined function.

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

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

@cindex Loops
@cindex Conditionals

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

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

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

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

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

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

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

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

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

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

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

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

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

The following commands can be used anywhere in a Gmsh ASCII text input file:

@ftable @code

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

@ftable @code
@item Pi
Returns 3.1415926535897932.

@item GMSH_MAJOR_VERSION
Returns Gmsh's major version number.

@item GMSH_MINOR_VERSION
Returns Gmsh's minor version number.

@item GMSH_PATCH_VERSION
Returns Gmsh's patch version number.

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

@item MPI_Rank
Returns the rank of the current processor.

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

@item newl
Returns the next available line number.

@item news
Returns the next available surface number.

@item newv
Returns the next available volume number.

@item newreg
Returns the next available region number. That is, @code{newreg} returns the
maximum of @code{newp}, @code{newl}, @code{news}, @code{newv} and all
physical entity numbers@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} [ ] = @{ @var{expression-list} @};
Defines a new expression list identifier @code{@var{string}[]}, or affects
@var{expression-list} to an existing expression list identifier.

@item @var{string} [ @{ @var{expression-list} @} ] = @{ @var{expression-list} @};
Affects each item in the right hand side @var{expression-list} to the
elements (indexed by the left hand side @var{expression-list}) of an
existing expression list identifier. The two @w{@var{expression-list}s} must
contain the same number of items. Remember the remark made when defining
@w{@var{expression-list}s}: the braces enclosing an @var{expression-list}
are optional if the list only contains a single item.

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

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

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

@item @var{string} | @var{real-option} += @var{expression};
Adds and affects @var{expression} to an existing expression identifier or to
a real option.

@item @var{string} | @var{real-option} -= @var{expression};
Subtracts and affects @var{expression} to an existing expression identifier
or to a real option.

@item @var{string} | @var{real-option} *= @var{expression};
Multiplies and affects @var{expression} to an existing expression identifier
or to a real option.

@item @var{string} | @var{real-option} /= @var{expression};
Divides and affects @var{expression} to an existing expression identifier
or to a real option.

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

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

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

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

@item Exit;
Aborts the current script.

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

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

@item Draw;
Redraws the scene.

@item BoundingBox;
Recomputes the bounding box of the scene (which is normally computed only
after new geometrical entities are added or after files are included or
merged). The bounding box is computed as follows:
@enumerate
@item
If there is a mesh (i.e., at least one mesh vertex), the bounding
box is taken as the box enclosing all the mesh vertices;
@item
If there is no mesh but there is a geometry (i.e., at least one geometrical
point), the bounding box is taken as the box enclosing all the geometrical
points;
@item
If there is no mesh and no geometry, but there are some post-processing
views, the bounding box is taken as the box enclosing all the primitives in
the views.
@end enumerate

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

@item Delete All;
Deletes all geometrical entities and all currently loaded meshes.

@item Delete Physicals;
Deletes all physical groups.

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

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

@item System @var{char-expression};
Executes a system call.

@item Include @var{char-expression};
Includes the file named @var{char-expression} at the current position in the
input file. The include command should be given on a line of its own.  If
the path in @var{char-expression} is not absolute, @var{char-expression} is
appended to the path of the current file.
@end ftable

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

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

Here is the list of the general @w{@var{char-option}s},
@w{@var{real-option}s} and @w{@var{color-option}s} (in that order---check
the default values to see the actual types). Most of these options are
accessible in the graphical user interface, but not all of them. When
running Gmsh interactively, changing an option in the ASCII text input file
will modify the option in the GUI in real time. This permits for example to
resize the graphical window in a script, or to interact with animations in
the script and in the GUI at the same time.

Gmsh's default behavior is to save some of these options in a per-user
``session resource'' file (@code{General.SessionFileName}) 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. Other options can be
saved in a per-user ``option'' file (@code{General.OptionsFileName}),
automatically loaded by Gmsh every time it starts up, by using the
`Tools->Options->Save' menu.

@c All the opt_XXX.texi files are generated automatically with `gmsh -doc'

@include opt_general.texi

@include opt_print.texi

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

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

@cindex Geometry, module
@cindex Module, geometry

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

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

@enumerate
@item each elementary point must possess a unique identification number;
@item each elementary line must possess a unique identification number;
@item each elementary surface must possess a unique identification number;
@item each elementary volume must possess a unique identification number.
@end enumerate

@noindent Elementary geometrical entities can then be manipulated in various
ways, for example using the @code{Translate}, @code{Rotate}, @code{Scale} or
@code{Symmetry} commands.

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

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

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

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

@cindex Geometry commands
@cindex Commands, geometry

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

@menu
* Points::                      
* Lines::                       
* Surfaces::                    
* Volumes::                     
* Extrusions::                  
* Transformations::             
* Miscellaneous geometry commands::  
@end menu

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

@node Points, Lines, Geometry commands, Geometry commands
@subsection Points

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

@ftable @code
@item Point ( @var{expression} ) = @{ @var{expression}, @var{expression}, @var{expression}, @var{expression} @};
Creates an elementary point. The @var{expression} inside the parentheses is
the point's identification number; 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 last
@var{expression} sets the characteristic mesh length at that point. See
@ref{Characteristic lengths}, for more information about how this
characteristic length information is used in the meshing process.

@item Physical Point ( @var{expression} ) = @{ @var{expression-list} @};
Creates a physical point. The @var{expression} inside the parentheses is the
physical point's identification number; the @var{expression-list} on the
right hand side should contain the identification numbers of all the
elementary points that need to be grouped inside the physical point.
@end ftable

@c .........................................................................
@c Lines
@c .........................................................................

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

@cindex Elementary lines
@cindex Lines, elementary
@cindex Physical lines
@cindex Lines, physical

@ftable @code
@item Bezier ( @var{expression} ) = @{ @var{expression-list} @};
Creates a Bezier curve. The @var{expression} inside the parentheses is the
Bezier curve's identification number; the @var{expression-list} on the right
hand side should contain the identification numbers of all the curve's
control points.

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

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

@c todo:
@c @item Circle ( @var{expression} ) = @{ @var{expression}, @var{expression}, @var{expression} @} Plane @{ @var{expression}, @var{expression}, @var{expression} @};

@item CatmullRom ( @var{expression} ) = @{ @var{expression-list} @};
@code{CatmullRom} is a synonym for @code{Spline}.

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

(A deprecated synonym for @code{Ellipse} is @code{Ellipsis}.)

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

@c todo:
@c @item Nurbs ( @var{expression} ) = @{ @var{expression-list} @};

@c todo:
@c @item Parametric ( @var{expression} ) = @{ @var{expression}, @var{expression}, "@var{string}", "@var{string}", "@var{string}" @};

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

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

@item Physical Line ( @var{expression} ) = @{ @var{expression-list} @};
Creates a physical line. The @var{expression} inside the parentheses is the
physical line's identification number; the @var{expression-list} on the
right hand side should contain the identification numbers of all the
elementary lines that need to be grouped inside the physical
line. Specifying negative identification numbers in the
@var{expression-list} will reverse the orientation of the mesh elements
belonging to the corresponding elementary lines in the saved mesh.
@end ftable

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

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

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

@ftable @code
@c todo:
@c @item Nurbs Surface ( @var{expression} ) = @{ @var{expression-list-list} @} Knots @{ @{ @var{expression-list} @}, @{ @var{expression-list} @} @} Order @{ @var{expression}, @var{expression} @};

@c todo:
@c @item Nurbs Surface With Bounds ( @var{expression} ) = @{ @var{expression-list-list} @} Knots @{ @{ @var{expression-list} @}, @{ @var{expression-list} @} @} Order @{ @var{expression}, @var{expression} @};

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

@item Ruled Surface ( @var{expression} ) = @{ @var{expression-list} @};
Creates a ruled surface, i.e., a surface that can be interpolated using
transfinite interpolation. The @var{expression} inside the parentheses is
the ruled surface's identification number; the @var{expression-list} on the
right hand side should the identification number of a single line loop,
composed of either three or four elementary lines.

@c todo:
@c @item Trimmed Surface ( @var{expression} ) = @{ @var{expression}, @{ @var{expression-list} @} @};

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

@item Physical Surface ( @var{expression} ) = @{ @var{expression-list} @};
Creates a physical surface. The @var{expression} inside the parentheses is
the physical surface's identification number; the @var{expression-list} on
the right hand side should contain the identification numbers of all the
elementary surfaces that need to be grouped inside the physical
surface. Specifying negative identification numbers in the
@var{expression-list} will reverse the orientation of the mesh elements
belonging to the corresponding elementary surfaces in the saved mesh.
@end ftable

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

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

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

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

(A deprecated synonym for @code{Volume} is @code{Complex Volume}.)

@item Physical Volume ( @var{expression} ) = @{ @var{expression-list} @};
Creates a physical volume. The @var{expression} inside the parentheses is
the physical volume's identification number; the @var{expression-list} on
the right hand side should contain the identification numbers of all the
elementary volumes that need to be grouped inside the physical
volume.
@end ftable

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

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

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

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

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

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

@item Extrude @{ @{ @var{expression-list} @}, @{ @var{expression-list} @}, @{ @var{expression-list} @}, @var{expression} @} @{ @var{extrude-list} @}
Extrudes all elementary entities (points, lines or surfaces) in
@var{extrude-list} using a translation combined with a rotation. 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; 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).
@end ftable

@noindent with

@example
@var{extrude-list}: 
  Point | Line | Surface @{ @var{expression-list} @}; @dots{}
@end example

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

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

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

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

@var{transform}:
@ftable @code
@item Dilate @{ @{ @var{expression-list} @}, @var{expression} @} @{ @var{transform-list} @}
Scales all elementary entities (points, lines or surfaces) 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 direction
of the homothetic transformation.

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

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

@item Translate @{ @var{expression-list} @} @{ @var{transform-list} @}
Translates all elementary entities (points, lines or surfaces) 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.
@end ftable

@noindent with

@example
@var{transform-list}: 
  Point | Line | Surface @{ @var{expression-list} @}; @dots{} |
  Duplicata @{ Point | Line | Surface @{ @var{expression-list} @}; @dots{} @} |
  @var{transform}
@end example

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

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

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

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

@item Delete @{ Point | Line | Surface | Volume @{ @var{expression-list} @}; @dots{} @}
Deletes all elementary entities (points, lines, surfaces or volumes) whose
identification numbers are given in @var{expression-list}.

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

@item Hide @var{char-expression};
Hide the entity @var{char-expression}, if @code{General.VisibilityMode} is
set to @code{0} or @code{1} (@var{char-expression} can for example be
@code{"*"}).

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

@item Show @var{char-expression};
Show the entity @var{char-expression}, if @code{General.VisibilityMode} is
set to @code{0} or @code{1} (@var{char-expression} can for example be
@code{"*"}).

@c todo:
@c @item Intersect;
@c Intersects all lines.
@end ftable

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

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

@cindex Options, geometry
@cindex Geometry, options

Geometry options control the behavior of geometry commands, as well as the
way geometrical entities are handled in the graphical user interface. For
the signification of the `Saved in:' field in the following list, see
@ref{General options}.

@include opt_geometry.texi

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

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

@cindex Mesh, module
@cindex Module, Mesh

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

The 2D @emph{unstructured} algorithms generate triangles or both triangles
and quadrangles (when @code{Recombine Surface} is used: see
@ref{Miscellaneous mesh commands}). The 3D unstructured algorithms only
generate tetrahedra.

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

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

@menu
* Elementary vs physical entities::  
* Mesh commands::               
* Mesh options::                
@end menu

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

@node Elementary vs physical entities, Mesh commands, Mesh module, Mesh module
@section Elementary vs. physical entities

If only elementary geometrical entities are defined (or if the
@code{Mesh.SaveAll} option is set; see @ref{Mesh options}), the grid
produced by the mesh module will be saved ``as is''. That is, all the
elements in the grid will be saved to disk using the identification number
of the elementary entities they discretize as their region number
(@pxref{Gmsh mesh file formats}). This can sometimes be inconvenient:

@itemize @bullet
@item
mesh elements cannot be duplicated;
@item 
the orientation of the mesh elements (the ordering of their nodes) is
determined entirely by the orientation of their ``parent'' elementary
entities, and cannot be modified;
@item
elements belonging to different elementary entities cannot be linked as
being part of a larger group having a physical or mathematical meaning (like
`Left wing', `Metallic part', `Dirichlet boundary condition', @dots{}).
@end itemize

To remedy these problems, the geometry module introduces the notion of
``physical'' entities (@pxref{Geometry module}). The purpose of physical
entities is to assemble elementary entities into larger, possibly
overlapping groups, and to control the orientation of the elements in these
groups. If physical entities are defined, the output mesh only contains
those elements that belong to physical entities. The introduction of such
physical entities in large models usually greatly facilitates the
manipulation of the model (e.g., using `Tools->Visibility' in the GUI) and
the interfacing with external solvers.

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

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

@cindex Mesh commands
@cindex Commands, mesh

The mesh module commands mostly permit to modify the characteristic lengths
and specify structured grid parameters. The actual mesh ``actions'' (i.e.,
``mesh the lines'', ``mesh the surfaces'' and ``mesh the volumes'') cannot
be specified in the input ASCII text input files. They have to be given
either in the GUI or on the command line (see @ref{Running Gmsh}, and
@ref{Command-line options}).

@menu
* Characteristic lengths::      
* Structured grids::            
* Miscellaneous mesh commands::  
@end menu

@c .........................................................................
@c Characteristic lengths
@c .........................................................................

@node Characteristic lengths, Structured grids, Mesh commands, Mesh commands
@subsection Characteristic lengths

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

The `size' of a mesh element is defined as the length of the segment for a
line segment, the radius of the circumscribed circle for a triangle and the
radius of the circumscribed sphere for a tetrahedron. There are three main
ways to specify the size of the mesh elements for a given geometry:

@enumerate
@item
You can specify characteristic lengths at the points of the geometrical
model (with the @code{Point} command: see @ref{Points}). The actual size of
the mesh elements will be computed by linearly interpolating these
characteristic lengths on the initial mesh (see @ref{Mesh}). This might
sometimes lead to over-refinement in some areas, so that you may have to add
``dummy'' geometrical entities in the model in order to get the desired
element sizes.

This method works with all the algorithms implemented in the mesh
module. The final element sizes are of course constrained by the structured
algorithms for which the element sizes are explicitly specified (e.g.,
transfinite and extruded grids: see @ref{Structured grids}).
@item
You can use geometrical ``attractors'', an elaborate version of the method
described in the preceding item: see the definition of the @code{Attractor}
command below.

Attractors only work with the 2D anisotropic algorithm (see the
@code{Mesh.Algorithm} option in @ref{Mesh options}).
@item
You can give Gmsh an explicit background mesh in the form of a scalar
post-processing view (see @ref{Post-processing commands}, and @ref{File
formats}) in which the nodal values are the target element sizes.  This
method is very general but it requires a first (usually rough) mesh and a
way to compute the target sizes on this mesh (usually through an error
estimation procedure, in an iterative process of mesh adaptation). Note that
the target element sizes can be constrained by the characteristic lengths
defined in the geometrical model if the
@code{Mesh.ConstrainedBackgroundMesh} option is set. To load a background
mesh, use the @code{-bgm} command-line option (@pxref{Command-line options})
or select `Apply as background mesh' in the post-processing view option
menu.

Background meshes are supported by all algorithms except the algorithms
based on Netgen.
@end enumerate

Here are the mesh commands that are related to the specification of
characteristic lengths:

@ftable @code
@item Attractor Point | Line @{ @var{expression-list} @} = @{ @var{expression}, @var{expression}, @var{expression} @};
Specifies a characteristic length attractor. The @var{expression-list}
should contain the identification numbers of the elementary points or lines
to serve as attractors; the two first @w{@var{expression}s} prescribe
refinement factors in a coordinate system local to the entities, and the
last @var{expression} a decay factor. This feature is still experimental,
and only works with the 2D anisotropic algorithm (see @code{Mesh.Algorithm}
in @ref{Mesh options}).  An example of the use of attractors is given in
@ref{t7.geo}.

Please note that attractors are an @emph{experimental} feature (to be
considered @emph{at most} alpha-quality...). Use at your own risk.

@item Characteristic Length @{ @var{expression-list} @} = @var{expression};
Modifies the characteristic length of the points whose identification
numbers are listed in @var{expression-list}. The new value is given by
@var{expression}.
@end ftable

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

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

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

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

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

The first @var{expression-list} defines how many elements should be created
in each extruded layer. The (optional) second @var{expression-list} assigns
a region number to each layer, which, if non-zero, overrides the elementary
entity number of the extruded entity.  This is useful when there is more
than one layer, as the elements in each layer can then be identified in a
unique way.  If the region number is set to zero, or if the
@var{expression-list} is omitted, the elements are associated with the
automatically created elementary geometrical entity (line, surface or
volume) created during the extrusion. The last @var{expression-list} gives
the normalized height of each layer (the list should contain a sequence of
@var{n} numbers 0 < @var{h1} < @var{h2} < @dots{} < @var{hn} <= 1). See
@ref{t3.geo}, for an example.

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

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

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

@item Transfinite Line @{ @var{expression-list} @} = @var{expression} < Using Progression | Bump @var{expression} >;
Selects the lines 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 line (this overrides any
characteristic length prescription---see @ref{Characteristic lengths}). 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
line.

(A deprecated synonym for @code{Progression} is @code{Power}.)

@item Transfinite Surface @{ @var{expression} @} = @{ @var{expression-list} @} < Left | Right | Alternate > ;
Selects the surface @var{expression} to be meshed with the 2D transfinite
algorithm (the surface can only have three or four sides). The
@var{expression-list} should contain the identification numbers of the
points on the boundary of the surface. The ordering of these point numbers
defines the ordering and orientation of the mesh elements, and should thus
follow the node ordering for triangles or quadrangles given in @ref{Gmsh
node ordering}. The optional argument specifies the way the triangles are
oriented when the mesh is not recombined.

@item Transfinite Volume @{ @var{expression} @} = @{ @var{expression-list} @};
Selects the volume @var{expression} to be meshed with the 3D transfinite
algorithm (the volume can only have six or eight faces).  The
@var{expression-list} should contain the identification numbers of the
points on the boundary of the volume. The ordering of these point numbers
defines the ordering and orientation of the mesh elements, and should thus
follow the node ordering for prisms or hexahedra given in @ref{Gmsh node
ordering}.

@item Elliptic Surface @{ @var{expression} @} = @{ @var{expression-list} @};
Selects the surface @var{expression} to be meshed with the 2D elliptic
algorithm (the surface can only have four sides). The @var{expression-list}
should contain the identification numbers of the points on the boundary of
the surface. The ordering of these point numbers defines the ordering and
orientation of the mesh elements, and should thus follow the node ordering
for triangles or quadrangles given in @ref{Gmsh node ordering}.

@end ftable

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

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

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

@ftable @code
@item Color @var{color-expression} @{ Point | Line | Surface | Volume @{ @var{expression-list} @}; @dots{} @}
Sets the mesh color of the entities in @var{expression-list} to @var{color-expression}.

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

@item Hide @var{char-expression};
Hides the mesh of the entity @var{char-expression}, if
@code{General.VisibilityMode} is set to @code{0} or @code{2}
(@var{char-expression} can for example be @code{"*"}).

@item Recombine Surface @{ @var{expression-list} @} < = @var{expression} >;
Recombines the triangular meshes of the surfaces listed in
@var{expression-list} into mixed triangular/quadrangular meshes. The
optional @var{expression} on the right hand side specifies the maximum
recombination angle allowed (a large @var{expression} leading to more
triangle recombinations).

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

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

@item Show @var{char-expression};
Shows the mesh of the entity @var{char-expression}, if
@code{General.VisibilityMode} is set to @code{0} or @code{2}
(@var{char-expression} can for example be @code{"*"}).
@end ftable

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

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

@cindex Options, mesh
@cindex Mesh, options

Mesh options control the behavior of mesh commands, as well as the way
meshes are displayed in the graphical user interface. For the signification
of the `Saved in:' field in the following list, see @ref{General options}.

@include opt_mesh.texi

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

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

@cindex Solver, module
@cindex Module, Solver

Five external solvers can be interfaced simultaneously with Gmsh.

If you just want to start a solver from the solver module, with no further
interactions between the solver and Gmsh, just edit the options relative to
one of the five available solvers (e.g., @code{Solver.Name0},
@code{Solver.Executable0}, @dots{}; see @ref{Solver options}), and set the
corresponding ``client-server'' option to zero
(e.g., @code{Solver.ClientServer0 = 0}). This doesn't require any
modification to be made to the solver.

If you want the solver to interact with Gmsh (for error messages, option
definitions, post-processing, etc.), you need to link your solver with the
@file{GmshClient.c} file and add the appropriate function calls inside your
program. You can then proceed as in the previous case, but this time you
should set the client-server option to 1 (e.g., @code{Solver.ClientServer0 =
1}), so that Gmsh and the solver can communicate through a Unix socket. See
@ref{Solver example}, for an example of how to interface a C++
solver. Bindings for solvers written in other languages (C, Perl and Python)
are available in the source distribution.

@menu
* Solver options::              
* Solver example::              
@end menu

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

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

@cindex Solver commands
@cindex Options, geometry

@include opt_solver.texi

@c -------------------------------------------------------------------------
@c Solver example
@c -------------------------------------------------------------------------

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

@cindex Solver example
@cindex Example, solver

Here is a small example of how to interface a C++ solver with Gmsh. The
following listing reproduces the @file{utils/solvers/c++/solver.cpp} file
from the Gmsh source distribution (C, Perl and Python examples are also
available).

@sp 1

@verbatiminclude ../../utils/solvers/c++/solver.cpp

@sp 1

To define the above solver as the second external solver in Gmsh, you then
need to define the following options (either merge them in your Gmsh option
file, or use the @code{-option} command-line option---see @ref{Command-line
options}):

@sp 1

@verbatiminclude ../../utils/solvers/c++/solver.opt

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

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

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

Gmsh's post-processing module can handle multiple scalar, vector or tensor
data sets along with the geometry and the mesh. The data sets should be
given in one of Gmsh's post-processing file formats described in @ref{File
formats}. Once loaded into Gmsh, scalar fields can be displayed as iso-value
lines and surfaces or color maps, whereas vector fields can be represented
either by three-dimensional arrows or by displacement maps. (Tensor fields
are currently displayed as Von-Mises effective stresses. To display other
(combinations of) components, use @code{Plugin(Extract)}: see
@ref{Post-processing plugins}.) 

In Gmsh's jargon, each data set is called a ``view'', and can arbitrarily
mix all types of elements and fields. Each view is given a name, and can be
manipulated either individually (each view has its own button in the GUI and
can be referred to by its index in a script) or globally (see the
@code{PostProcessing.Link} option in @ref{Post-processing options}).

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

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

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

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

Sample post-processing files in human-readable ``parsed'' format
(@pxref{Parsed post-processing file format}) are available in the
@file{tutorial} directory of Gmsh's distribution (@file{.pos} files).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@item View "@var{string}" @{ @var{string} ( @var{expression-list} ) @{ @var{expression-list} @}; @dots{} @};
Creates a new post-processing view, named @code{"@var{string}"}. This is the
easiest way to create a post-processing view, but also the least efficient
(the view is read through Gmsh's script parser, which can become a bit slow
if the view is very large---e.g., with one million elements). Nevertheless,
this ``parsed'' post-processing format (explained in detail in @ref{Parsed
post-processing file format}) is very powerful, since all the values are
@var{expressions}. Two other formats, better suited for very large data
sets, are described in @ref{ASCII post-processing file format}, and
@ref{Binary post-processing file format}.
@end ftable

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

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

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

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

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

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

@include opt_plugin.texi

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

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

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

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

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

See @ref{t8.geo}, and @ref{t9.geo}, for some examples.

@include opt_post.texi

@include opt_view.texi

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

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

@node Tutorial, Running Gmsh, Post-processing module, Top
@chapter Tutorial

@cindex Examples
@cindex Tutorial

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

This tutorial does not explain the mesh and post-processing file formats:
see @ref{File formats}, for this.

To learn how to run Gmsh on your computer, see @ref{Running Gmsh}. In
addition, interactive tutorials that explain how to use the graphical
user interface are available on Gmsh's webpage:

@itemize @bullet
@item 
@uref{http://geuz.org/gmsh/doc/gui_tutorial/,The first interactive
tutorial} shows how to create a simple 2D geometry and how to generate a
mesh;
@item
@uref{http://geuz.org/gmsh/doc/gui_tutorial_2/,The second} shows several
methods to visualize data sets on deformed grids;
@item
@uref{http://geuz.org/gmsh/doc/gui_tutorial_3/,The third} shows how to
use post-processing plugins.
@end itemize

@menu
* t1.geo::                      
* t2.geo::                      
* t3.geo::                      
* t4.geo::                      
* t5.geo::                      
* t6.geo::                      
* t7.geo::                      
* t8.geo::                      
* t9.geo::                      
@end menu

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

@node t1.geo, t2.geo, Tutorial, Tutorial
@section @file{t1.geo}

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

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

@node t2.geo, t3.geo, t1.geo, Tutorial
@section @file{t2.geo}

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

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

@node t3.geo, t4.geo, t2.geo, Tutorial
@section @file{t3.geo}

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

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

@node t4.geo, t5.geo, t3.geo, Tutorial
@section @file{t4.geo}

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

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

@node t5.geo, t6.geo, t4.geo, Tutorial
@section @file{t5.geo}

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

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

@node t6.geo, t7.geo, t5.geo, Tutorial
@section @file{t6.geo}

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

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

@node t7.geo, t8.geo, t6.geo, Tutorial
@section @file{t7.geo}

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

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

@node t8.geo, t9.geo, t7.geo, Tutorial
@section @file{t8.geo}

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

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

@node t9.geo,  , t8.geo, Tutorial
@section @file{t9.geo}

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

@c =========================================================================
@c Running Gmsh
@c =========================================================================

@node Running Gmsh, File formats, Tutorial, Top
@chapter Running Gmsh

@cindex Operating system
@cindex Running Gmsh

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

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

@node Interactive mode, Non-interactive mode, Running Gmsh, Running Gmsh
@section Interactive mode

@cindex Interactive mode

Gmsh's first operating mode is the `interactive graphical mode'. To launch
Gmsh in interactive mode, just click or double-click on the Gmsh icon
(Windows and Mac), or type

@example
> gmsh
@end example

@noindent at your shell prompt in a terminal (Unix). This will open
two windows: the graphic window (with a status bar at the bottom) and the
menu window (with a menu bar and some context-dependent buttons). 

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

@example
> gmsh t1.geo
@end example

To perform the mesh generation, go to the mesh module (by selecting `Mesh'
in the module menu) and choose the required dimension in the
context-dependent buttons (`1D' will mesh all the lines; `2D' will mesh all
the surfaces---as well as all the lines if `1D' was not called before; `3D'
will mesh all the volumes---and all the surfaces if `2D' was not called
before). To save the resulting mesh in the current mesh format, choose
`Save' in the context-dependent buttons, or select the appropriate format
with the `File->Save As' menu. The default mesh file name is based on the
name of the first input file on the command line (or @file{untitled} if
there wasn't any input file given), with an appended extension depending on
the mesh format@footnote{Nearly all the interactive commands have shortcuts:
see @ref{Keyboard shortcuts}, or select `Help->Keyboard Shortcuts' in the
menu.}.

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

Several files can be loaded simultaneously in Gmsh. The first one defines
the project, while the others are appended (`merged') to this project. You
can merge such files with the `File->Merge' menu, or by directly specifying
the names of the files on the command line. For example, to merge the
post-processing views contained in the files @file{view1.pos} and
@file{view2.pos} together with the geometry of the first tutorial
@file{t1.geo}, you can type the following command:

@example
> gmsh t1.geo view1.pos view2.pos
@end example

In the Post-Processing module (select `Post-Processing' in the module
menu), two view buttons will appear, respectively labeled `a scalar
map' and `a vector map'. A mouse click on the 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. If you want the
modifications made to one view to affect also all the other views,
select the `Apply next changes to all views' or `Force same options
for all views' option in the `Tools->Options->Post-processing' menu.

Note that all the options specified interactively can also be directly
specified in the ASCII input files. All available options, with their
current values, can be saved into a file by selecting `File->Save As->Gmsh
options', or simply viewed by pressing the `?' button in the status bar. To
save the current options as your default preferences for all future Gmsh
sessions, use the `Tools->Options->Save' button.

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

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

@cindex Non-interactive mode

Gmsh's second operating mode is the non-interactive (or `batch') mode. In
this mode, there is no graphical user interface, and all operations are
performed without any user interaction@footnote{If you compile Gmsh without
the graphical user interface, i.e., with @code{./configure --disable-gui},
this is the only mode you have access to.}. For example, to mesh the first
tutorial in non-interactive mode, just type:

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

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

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

For the list of all command-line options, see @ref{Command-line options}.

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

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

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

@include command_line.texi

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

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

@cindex Mouse, actions
@cindex Bindings, mouse

In the following, for a 2 button mouse, @kbd{Middle button} =
@kbd{Shift+Left button}. For a 1 button mouse, @kbd{Middle button} =
@kbd{Shift+Left button} and @kbd{Right button} = @kbd{Alt+Left button}.

@kbd{Move the mouse}:
@itemize @bullet
@item
Highlight the elementary geometrical entity currently under the mouse
pointer and display its properties in the status bar
@item
Resize a lasso zoom or a lasso selection started with @kbd{Ctrl+Left
button}
@end itemize

@kbd{Left button}:
@itemize @bullet
@item
Rotate
@item
Select an entity
@item
Accept a lasso zoom or a lasso selection started with @kbd{Ctrl+Left
button}
@end itemize

@kbd{Ctrl+Left button}: Start a lasso zoom or a lasso selection

@kbd{Middle button}:
@itemize @bullet
@item
Zoom
@item
Unselect an entity
@item
Cancel a lasso zoom or a lasso selection
@end itemize

@kbd{Ctrl+Middle button}: Orthogonalize display

@kbd{Right button}:
@itemize @bullet
@item
Pan
@item
Cancel a lasso zoom or a lasso selection
@item
Pop-up menu on post-processing view button
@end itemize

@kbd{Ctrl+Right button}: Reset to default viewpoint

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

@node Keyboard shortcuts,  , Mouse actions, Running Gmsh
@section Keyboard shortcuts

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

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

@include shortcuts.texi

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

@node File formats, Programming notes, Running Gmsh, Top
@chapter File formats

@cindex File formats

This chapter describes Gmsh's native mesh and post-processing file
formats. (These formats have version numbers that are independent of Gmsh's
main version number.)

All non-parsed file formats have sections enclosed between @code{$Key} and
@code{$EndKey} tags.

@menu
* Gmsh mesh file formats::      
* Gmsh post-processing file formats::  
* Gmsh node ordering::          
@end menu

@c -------------------------------------------------------------------------
@c Gmsh mesh file formats
@c -------------------------------------------------------------------------

@node Gmsh mesh file formats, Gmsh post-processing file formats, File formats, File formats
@section Gmsh mesh file formats

@cindex Mesh, file format
@cindex File format, mesh
@cindex @file{.msh} file

Please note that the list of nodes and elements in Gmsh's mesh files do not
have to be dense or ordered (i.e., the node and element numbers do not have
to be given in a consecutive or even an ordered way). A sample C++ program
to transform the formats so that all lists are dense and ordered is
available in the source distribution (@file{utils/misc/mshsort.cpp}). This
program is also a good example on how to read and write files in the
@file{.msh} format.

@menu
* Version 1.0::                 
* Version 2.0::                 
@end menu

@c .........................................................................
@c Version 1.0
@c .........................................................................

@node Version 1.0, Version 2.0, Gmsh mesh file formats, Gmsh mesh file formats
@subsection Version 1.0

The @file{.msh} file format, version 1.0, is Gmsh's old native mesh file
format, now superseded by the format described in @ref{Version 2.0}.

In the @file{.msh} file format, version 1.0, the file is divided in two
sections, defining the nodes (@code{$NOD}-@code{$ENDNOD}) and the elements
(@code{$ELM}-@code{$ENDELM}) in the mesh:

@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. Note that the
@w{@var{node-number}s} do not have to be given in a consecutive (or even an
ordered) way.

@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. Note that the
@w{@var{elm-number}s} do not have to be given in a consecutive (or even an
ordered) way.

@item @var{elm-type}
defines the geometrical type of the @var{n}-th element:
@table @code
@item 1
Line (2 nodes).
@item 2
Triangle (3 nodes).
@item 3
Quadrangle (4 nodes).
@item 4
Tetrahedron (4 nodes).
@item 5
Hexahedron (8 nodes).
@item 6
Prism (6 nodes).
@item 7
Pyramid (5 nodes).
@item 8
Second order line (3 nodes: 2 associated with the vertices and 1 with the
edge).
@item 9
Second order triangle (6 nodes: 3 associated with the vertices and 3 with
the edges).
@item 10
Second order quadrangle (9 nodes: 4 associated with the vertices, 4 with the
edges and 1 with the face).
@item 11
Second order tetrahedron (10 nodes: 4 associated with the vertices and 6
with the edges).
@item 12
Second order hexahedron (27 nodes: 8 associated with the vertices, 12 with
the edges, 6 with the faces and 1 with the volume).
@item 13
Second order prism (18 nodes: 6 associated with the vertices, 9 with the
edges and 3 with the quadrangular faces).
@item 14
Second order pyramid (14 nodes: 5 associated with the vertices, 8 with the
edges and 1 with the quadrangular face).
@item 15
Point (1 node).
@end table
See below for the ordering of the nodes.

@item @var{reg-phys}
is the number of the physical entity to which the element belongs. 

@item @var{reg-elem}
is the number of the elementary entity to which the element belongs.

@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{Gmsh node ordering}; for
second order elements, the first order nodes are given first, followed by
the nodes associated with the edges, followed by the nodes associated with
the quadrangular faces (if any), followed by the nodes associated with the
volume (if any). The ordering of these additional nodes follows the ordering
of the edges and quadrangular faces given in @ref{Gmsh node ordering}.
@end table

@c .........................................................................
@c Version 2.0
@c .........................................................................

@node Version 2.0,  , Version 1.0, Gmsh mesh file formats
@subsection Version 2.0

Version 2.0 of the @file{.msh} file format is Gmsh's new native mesh file
format. It is very similar to the old one (@pxref{Version 1.0}), but is more
general: it contains information about itself and allows to associate an
arbitrary number of integer tags with each element.

The @file{.msh} file format, version 2.0, is divided in three sections,
defining the file format (@code{$MeshFormat}-@code{$EndMeshFormat}), the
nodes (@code{$Nodes}-@code{$EndNodes}) and the elements
(@code{$Elements}-@code{$EndElements}) in the mesh:

@example
$MeshFormat
2.0 @var{file-type} @var{data-size}
$EndMeshFormat
$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
@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{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. Note that the
@w{@var{node-number}s} do not have to be given in a consecutive (or even an
ordered) way.

@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. Note that the
@w{@var{elm-number}s} do not have to be given in a consecutive (or even an
ordered) way.

@item @var{elm-type}
defines the geometrical type of the @var{n}-th element:
@table @code
@item 1
Line (2 nodes).
@item 2
Triangle (3 nodes).
@item 3
Quadrangle (4 nodes).
@item 4
Tetrahedron (4 nodes).
@item 5
Hexahedron (8 nodes).
@item 6
Prism (6 nodes).
@item 7
Pyramid (5 nodes).
@item 8
Second order line (3 nodes: 2 associated with the vertices and 1 with the
edge).
@item 9
Second order triangle (6 nodes: 3 associated with the vertices and 3 with
the edges).
@item 10
Second order quadrangle (9 nodes: 4 associated with the vertices, 4 with the
edges and 1 with the face).
@item 11
Second order tetrahedron (10 nodes: 4 associated with the vertices and 6
with the edges).
@item 12
Second order hexahedron (27 nodes: 8 associated with the vertices, 12 with
the edges, 6 with the faces and 1 with the volume).
@item 13
Second order prism (18 nodes: 6 associated with the vertices, 9 with the
edges and 3 with the quadrangular faces).
@item 14
Second order pyramid (14 nodes: 5 associated with the vertices, 8 with the
edges and 1 with the quadrangular face).
@item 15
Point (1 node).
@end table
See below for the ordering of the nodes.

@item @var{number-of-tags}
gives the number of tags for the @var{n}-th element. By default, Gmsh
generates meshes with two tags and reads files with an arbitrary number of
tags: see below.

@item @var{tag}
is an integer tag associated with the @var{n}-th element. By default, the
first tag is the number of the physical entity to which the element belongs;
the second is the number of the elementary geometrical entity to which the
element belongs; the third is the number of a mesh partition to which the
element belongs.

@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{Gmsh node ordering}; for second order elements,
the first order nodes are given first, followed by the nodes associated with
the edges, followed by the nodes associated with the quadrangular faces (if
any), followed by the nodes associated with the volume (if any). The
ordering of these additional nodes follows the ordering of the edges and
quadrangular faces given in @ref{Gmsh node ordering}.
@end table

@c -------------------------------------------------------------------------
@c Gmsh post-processing file formats
@c -------------------------------------------------------------------------

@node Gmsh post-processing file formats, Gmsh node ordering, Gmsh mesh file formats, File formats
@section Gmsh post-processing file formats

@cindex @file{.pos} file

Gmsh can read and write data sets in three different file formats: the
``parsed'', ``ASCII'' and ``binary'' file formats. The parsed format is the
oldest and most flexible, but also the slowest to read/write. The ASCII and
binary formats are less flexible but allow for faster read/write operations,
which is useful for (very) large data sets.

Gmsh can convert any format to any other, either in a script (cf. @code{Save
View} and @code{PostProcessing.Format} in @ref{Post-processing commands},
and @ref{Post-processing options}, respectively) or in the graphical user
interface (using the `View->Save As' menu).

@menu
* Parsed post-processing file format::  
* ASCII post-processing file format::  
* Binary post-processing file format::  
@end menu

@c .........................................................................
@c Parsed post-processing file format
@c .........................................................................

@node Parsed post-processing file format, ASCII post-processing file format, Gmsh post-processing file formats, Gmsh post-processing file formats
@subsection Parsed post-processing file format

@cindex Post-processing, parsed file format
@cindex File format, post-processing, parsed
@cindex @file{.pos} file

Gmsh's oldest post-processing format (``parsed'') is read by Gmsh's script
parser (see also @ref{Post-processing commands}). You can thus, for example,
embed parsed post-processing views directly into your geometrical
descriptions (see, e.g., @ref{t4.geo}). 

The parsed format is very powerful, since all the values are
@var{expressions}, and it can be easily generated ``on-the-fly'', as there
is no header containing @emph{a priori} information on the size of the data
set. Its syntax is also very permissive, which makes it ideal for testing
purposes. Its main disadvantage resides in the overhead introduced by the
parser, which makes loading a view in parsed format slower than loading a
view in ASCII or binary format. This is only a disadvantage for very large
data sets, though.

A post-processing view in parsed format is defined as follows (there can be
one or more views in the same file):

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

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

@example
                                 @var{type}  #@var{list-of-coords}  #@var{list-of-values}
--------------------------------------------------------------------
Scalar point                     SP    3            1  * @var{nb-time-steps}
Vector point                     VP    3            3  * @var{nb-time-steps}
Tensor point                     TP    3            9  * @var{nb-time-steps}
Scalar line                      SL    6            2  * @var{nb-time-steps}
Vector line                      VL    6            6  * @var{nb-time-steps}
Tensor line                      TL    6            18 * @var{nb-time-steps}
Scalar triangle                  ST    9            3  * @var{nb-time-steps}
Vector triangle                  VT    9            9  * @var{nb-time-steps}
Tensor triangle                  TT    9            27 * @var{nb-time-steps}
Scalar quadrangle                SQ    12           4  * @var{nb-time-steps}
Vector quadrangle                VQ    12           12 * @var{nb-time-steps}
Tensor quadrangle                TQ    12           36 * @var{nb-time-steps}
Scalar tetrahedron               SS    12           4  * @var{nb-time-steps}
Vector tetrahedron               VS    12           12 * @var{nb-time-steps}
Tensor tetrahedron               TS    12           36 * @var{nb-time-steps}
Scalar hexahedron                SH    24           8  * @var{nb-time-steps}
Vector hexahedron                VH    24           24 * @var{nb-time-steps}
Tensor hexahedron                TH    24           72 * @var{nb-time-steps}
Scalar prism                     SI    18           6  * @var{nb-time-steps}
Vector prism                     VI    18           18 * @var{nb-time-steps}
Tensor prism                     TI    18           54 * @var{nb-time-steps}
Scalar pyramid                   SY    15           5  * @var{nb-time-steps}
Vector pyramid                   VY    15           15 * @var{nb-time-steps}
Tensor pyramid                   TY    15           45 * @var{nb-time-steps}
Second order scalar line         SL2   9            3  * @var{nb-time-steps}
Second order vector line         VL2   9            9  * @var{nb-time-steps}
Second order tensor line         TL2   9            27 * @var{nb-time-steps}
Second order scalar triangle     ST2   18           6  * @var{nb-time-steps}
Second order vector triangle     VT2   18           18 * @var{nb-time-steps}
Second order tensor triangle     TT2   18           54 * @var{nb-time-steps}
Second order scalar quadrangle   SQ2   27           9  * @var{nb-time-steps}
Second order vector quadrangle   VQ2   27           27 * @var{nb-time-steps}
Second order tensor quadrangle   TQ2   27           81 * @var{nb-time-steps}
Second order scalar tetrahedron  SS2   30           10 * @var{nb-time-steps}
Second order vector tetrahedron  VS2   30           30 * @var{nb-time-steps}
Second order tensor tetrahedron  TS2   30           90 * @var{nb-time-steps}
Second order scalar hexahedron   SH2   81           27 * @var{nb-time-steps}
Second order vector hexahedron   VH2   81           81 * @var{nb-time-steps}
Second order tensor hexahedron   TH2   81           243* @var{nb-time-steps}
Second order scalar prism        SI2   54           18 * @var{nb-time-steps}
Second order vector prism        VI2   54           54 * @var{nb-time-steps}
Second order tensor prism        TI2   54           162* @var{nb-time-steps}
Second order scalar pyramid      SY2   42           14 * @var{nb-time-steps}
Second order vector pyramid      VY2   42           42 * @var{nb-time-steps}
Second order tensor pyramid      TY2   42           126* @var{nb-time-steps}
2D text                          T2    3            arbitrary
3D text                          T3    4            arbitrary
@end example

The coordinates are given `by node'@footnote{Beware that this is different
from the ordering of the node coordinates in the ASCII and binary
post-processing file formats.}, 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{Gmsh node ordering}. For second
order elements, the first order nodes are given first, followed by the nodes
associated with the edges, followed by the nodes associated with the
quadrangular faces (if any), followed by the nodes associated with the
volume (if any). The ordering of these additional nodes follows the ordering
of the edges and quadrangular faces given in @ref{Gmsh node ordering}.

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

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

For the 3D text objects, the three first @w{@var{expression}s} in
@var{list-of-coords} give the XYZ position of the string in model (real
world) coordinates.  The fourth @var{expression} has the same meaning as the
third @var{expression} in 2D text objects.

For both 2D and 3D text objects, the @var{list-of-values} can contain an
arbitrary number of @w{@var{char-expression}s}.

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.

@c .........................................................................
@c ASCII post-processing file format
@c .........................................................................

@node ASCII post-processing file format, Binary post-processing file format, Parsed post-processing file format, Gmsh post-processing file formats
@subsection ASCII post-processing file format

@cindex Post-processing, ASCII file format
@cindex File format, post-processing, ASCII

The ASCII post-processing file is divided in several sections: one format
section, enclosed between @code{$PostFormat}-@code{$EndPostFormat} tags, and
one or more post-processing views, enclosed between
@code{$View}-@code{$EndView} tags:

@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{Gmsh node ordering}. For second
order elements, the first order nodes are given first, followed by the nodes
associated with the edges, followed by the nodes associated with the
quadrangular faces (if any), followed by the nodes associated with the
volume (if any). The ordering of these additional nodes follows the ordering
of the edges and quadrangular faces given in @ref{Gmsh 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 Binary post-processing file format
@c .........................................................................

@node Binary post-processing file format,  , ASCII post-processing file format, Gmsh post-processing file formats
@subsection Binary post-processing file format

@cindex Post-processing, binary file format
@cindex File format, post-processing, binary

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

@enumerate
@item
@var{file-type} equals 1.
@item 
all lists of floating point numbers and characters are written in binary
format
@item
there is an additional integer, of value 1, written before
@var{time-step-values}. This integer is used for detecting if the computer
on which the binary file was written and the computer on which the file is
read are of the same type (little or big endian).
@end enumerate

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

@example
int one = 1;

fprintf(file, "$PostFormat\n");
fprintf(file, "%g %d %d\n", 1.4, 1, sizeof(double));
fprintf(file, "$EndPostFormat\n");
fprintf(file, "$View\n");
fprintf(file, "%s %d "
  "%d %d %d %d %d %d %d %d %d "
  "%d %d %d %d %d %d %d %d %d "
  "%d %d %d %d %d %d %d %d %d "
  "%d %d %d %d %d %d %d %d %d "
  "%d %d %d %d %d %d %d %d %d "
  "%d %d %d %d\n", 
  view-name, nb-time-steps,
  nb-scalar-points, nb-vector-points, nb-tensor-points,
  nb-scalar-lines, nb-vector-lines, nb-tensor-lines,
  nb-scalar-triangles, nb-vector-triangles, nb-tensor-triangles,
  nb-scalar-quadrangles, nb-vector-quadrangles, nb-tensor-quadrangles,
  nb-scalar-tetrahedra, nb-vector-tetrahedra, nb-tensor-tetrahedra,
  nb-scalar-hexahedra, nb-vector-hexahedra, nb-tensor-hexahedra,
  nb-scalar-prisms, nb-vector-prisms, nb-tensor-prisms,
  nb-scalar-pyramids, nb-vector-pyramids, nb-tensor-pyramids,
  nb-scalar-lines2, nb-vector-lines2, nb-tensor-lines2,
  nb-scalar-triangles2, nb-vector-triangles2, nb-tensor-triangles2,
  nb-scalar-quadrangles2, nb-vector-quadrangles2, nb-tensor-quadrangles2,
  nb-scalar-tetrahedra2, nb-vector-tetrahedra2, nb-tensor-tetrahedra2,
  nb-scalar-hexahedra2, nb-vector-hexahedra2, nb-tensor-hexahedra2,
  nb-scalar-prisms2, nb-vector-prisms2, nb-tensor-prisms2,
  nb-scalar-pyramids2, nb-vector-pyramids2, nb-tensor-pyramids2,
  nb-text2d, nb-text2d-chars, nb-text3d, nb-text3d-chars);
fwrite(&one, sizeof(int), 1, file);
fwrite(time-step-values, sizeof(double), nb-time-steps, file);
fwrite(all-scalar-point-values, sizeof(double), ..., file);
...
fprintf(file, "\n$EndView\n");
@end example
In this pseudo-code, @var{all-scalar-point-values} is the array of double
precision numbers containing all the @var{scalar-point-value} lists, put one
after each other in order to form a long array of doubles. The principle is
the same for all other kinds of values.

@c -------------------------------------------------------------------------
@c Gmsh node ordering
@c -------------------------------------------------------------------------

@node Gmsh node ordering,  , Gmsh post-processing file formats, File formats
@section Gmsh node ordering

@cindex Nodes, ordering
@cindex Edges, ordering
@cindex Faces, ordering

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

@c FIXME: changer la doc des faces pour les definir de maniere sensee
@c sans butterflies.

@example
@group
Point:
        v
        |
        |
   -----1-----u
        |
        |
@end group
@end example

@example
@group
Line:
                  edge 1: nodes 1 2
        v
        |
        |
   --1-----2--u
        |
        |
@end group
@end example

@example
@group
Triangle:
                  edge 1: nodes 1 2
   v                   2:       2 3
   |                   3:       3 1
   |
   3
   |\
   | \
   |__\___u
   1   2
@end group
@end example

@example
@group
Quadrangle:
                  edge 1: nodes 1 2   quad. face 1: nodes 1 2 3 4
        v              2:       2 3
        |              3:       3 4
     4--|--3           4:       4 1
     |  |  |
   -----------u
     |  |  |
     1--|--2
        |
@end group
@end example

@example
@group
Tetrahedron:
                  edge 1: nodes 1 2
   v                   2:       2 3
   |                   3:       3 1
   |                   4:       4 1
   |                   5:       4 3
   3                   6:       4 2
   |\                
   | \
   |__\2_____u
   1\ /
     \4
      \
       w
@end group
@end example

@example
@group
Hexahedron:
                  edge 1: nodes 1 2   quad. face 1: nodes 1 2 3 4
        v              2:       1 4              2:       1 2 5 6
        |              3:       1 5              3:       1 4 5 8
        |              4:       2 3              4:       2 3 6 7
   4----|--3           5:       2 6              5:       3 4 7 8
   |\   |  |\          6:       3 4              6:       5 6 7 8
   | 8-------7         7:       3 7
   | |   ----|---u     8:       4 8
   1-|---\-2 |         9:       5 6
    \|    \ \|        10:       5 8
     5-----\-6        11:       6 7
            \         12:       7 8
             w
@end group
@end example

@example
@group
Prism:
                  edge 1: nodes 1 2   quad. face 1: nodes 1 2 4 5
      v                2:       1 3              2:       1 3 4 6
    3 |                3:       1 4              3:       2 3 5 6
    |\|                4:       2 3
    | |                5:       2 5
    1_|2               6:       3 6
     \| 6              7:       4 5
      |_|_\___u        8:       4 6
       \|  \           9:       5 6
        4 __5
         \
          \
           w
@end group
@end example

@example
@group
Pyramid:
                  edge 1: nodes 1 2   quad. face 1: nodes 1 2 3 4
        v              2        1 4
        |              3        1 5
        |              4        2 3
    4---|---3          5        2 5
    | \ |  /|          6        3 4
    |  \ -/-|---u      7        3 5
    |  / 5\ |          8        4 5
    1/----\-2
           \
            \
             w
@end group
@end example

@c =========================================================================
@c Programming notes
@c =========================================================================

@node Programming notes, Bugs and versions, File formats, Top
@chapter Programming notes

@cindex Programming, notes

Gmsh was originally written in C, and later enhanced with various C++
additions. The resulting code is a hybrid C/C++ beast, hopefully not too
badly structured... The scripting language is parsed using Lex and Yacc
(actually, Flex and Bison), while the GUI relies on OpenGL for the 3D
graphics and FLTK for the widget set. See @uref{http://www.opengl.org},
@uref{http://www.mesa3d.org} and @uref{http://www.fltk.org} for more
information.

Gmsh's build system is based on autoconf, and should work on most modern
platforms providing standard compliant C and C++ compilers. Practical notes
on how to compile Gmsh's source code are included in the distribution. Note
that compiling the Windows version requires the Cygwin tools (freely
available from @uref{http://www.cygwin.com}). See @ref{Frequently asked
questions}, for more information.

@menu
* Coding style::                
* Option handling::             
@end menu

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

@node Coding style, Option handling, Programming notes, Programming notes
@section Coding style

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

@enumerate
@item
please enable full warnings for your compiler (e.g., add @code{-Wall} to
@code{FLAGS} in the @file{variables} file);
@item
always use the @code{Msg()} function to print information, errors, @dots{};
@item 
indent your files using @file{utils/misc/indent.sh};
@end enumerate

@c -------------------------------------------------------------------------
@c Option handling
@c -------------------------------------------------------------------------

@node Option handling,  , Coding style, Programming notes
@section Option handling

To add a new option in Gmsh:

@enumerate
@item
create the option in the @code{Context_T} class (@file{Common/Context.h}) if
it's a classical option, or in the @code{Post_View} class
(@file{Common/View.h}) if it's a post-processing view-dependent option;
@item
in @file{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 @file{Common/Options.cpp} (and
add the prototype in @file{Common/Options.h});
@item
optional: create the associated widget in @file{Fltk/GUI.cpp};
@item
optional: if no special callback is to be associated with the widget, add the
handling routine @code{opt_XXX} to the OK callback for the corresponding
option panel (in @file{Fltk/Callbacks.cpp}).
@end enumerate

@c todo:
@c Tools to check memory leaks
@c * LIBNJAMD
@c   export LD_PRELOAD=libnjamd.so
@c   kill -USR1
@c * valgrind --leak-check=yes --show-reachable=yes gmsh file.geo -3
@c * purify
@c * memprof

@c =========================================================================
@c Bugs, versions and credits
@c =========================================================================

@node Bugs and versions, Tips and tricks, Programming notes, Top
@chapter Bugs, versions and credits

@menu
* Bugs::                        
* Versions::                    
* Credits::                     
@end menu

@c -------------------------------------------------------------------------
@c Bugs
@c -------------------------------------------------------------------------

@node Bugs, Versions, Bugs and versions, Bugs and versions
@section Bugs

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

If you think you have found a bug in Gmsh, you can report it by electronic
mail to the Gmsh mailing list at @email{gmsh@@geuz.org}.  Please send as
precise a description of the problem as you can, including sample input
files that produce the bug. Don't forget to mention both the version of Gmsh
and the version of your operation system (@pxref{Command-line options} to
see how to get this information).

See @ref{Frequently asked questions}, and the @file{TODO} file in the
distribution to see which problems we already know about.

@c -------------------------------------------------------------------------
@c Versions
@c -------------------------------------------------------------------------

@node Versions, Credits, Bugs, Bugs and versions
@section Versions

@cindex Versions
@cindex History, versions
@cindex Changelog

@verbatiminclude ../VERSIONS

@c -------------------------------------------------------------------------
@c Credits
@c -------------------------------------------------------------------------

@node Credits,  , Versions, Bugs and versions
@section Credits

@cindex Acknowledgments
@cindex Contributors, list
@cindex Credits 

@verbatiminclude ../CREDITS

@c =========================================================================
@c Tips ans Tricks
@c =========================================================================

@node Tips and tricks, Frequently asked questions, Bugs and versions, Top
@appendix Tips and tricks

@cindex Tips
@cindex Tricks
@cindex Efficiency, tips

@itemize @bullet
@item
Install the `info' version of this user's guide! On your (Unix) system, this
can be achieved by

@enumerate
@item
copying all @file{gmsh.info*} files to the place where your info files live
(usually @file{/usr/info}), and
@item
issuing the command @code{install-info /usr/info/gmsh.info /usr/info/dir}.
@end enumerate

You will then be able to access the documentation with the command
@code{info gmsh}. Note that particular sections (`nodes') can be accessed
directly. For example, @code{info gmsh surfaces} or @code{info gmsh surf}
will take you directly to @ref{Surfaces}.
@item
Use emacs to edit your files, and load the C++ mode! This permits automatic
syntax highlighting and easy indentation. Automatic loading of the C++ mode
for @file{.geo} files can be achieved by adding the following command in
your @code{.emacs} file: @code{(setq auto-mode-alist (append '(("\\.geo$"
. c++-mode)) auto-mode-alist))}.
@item
Define common geometrical objects and options in separate files, reusable in
all your problem definition structures.
@item
Save your preferred options with `Tools->Options->Save'. To reset default
options, erase the @code{General.OptionsFileName} (usually
@file{.gmsh-options} in your home directory) or use the `Restore default
options' button in `Tools->Options->General->Output'.
@item
In the graphical user interface:

@itemize --
@item
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
selecting the content of an input field, or lines in the message console
(`Tools->Message Console'), copies the selected text to the clipboard;
@end itemize

@item
Read @ref{Frequently asked questions}...
@end itemize

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

@node Frequently asked questions, License, Tips and tricks, Top
@appendix Frequently asked questions

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

@verbatiminclude ../FAQ

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

@node License, Concept index, Frequently asked questions, Top
@appendix License

@cindex License

@include license.texi

@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
