| [Top] | [Contents] | [Index] | [ ? ] |
Christophe Geuzaine and Jean-François Remacle
Gmsh is an automatic 3D finite element mesh generator with build-in pre- and post-processing facilities. This is the Gmsh Reference Manual for Gmsh 2.2 (July, 18 2008).
Copying conditions Terms and conditions of use. 1. Overview What is Gmsh? 2. General tools Description of general commands and options. 3. Geometry module Description of all Geometry commands. 4. Mesh module Description of all Mesh commands. 5. Solver module Description of all Solver commands. 6. Post-processing module Description of all Post-Processing commands. 7. Tutorial A step-by-step tutorial. 8. Running Gmsh How to run Gmsh on your operating system. 9. File formats Input and output file formats. 10. Programming notes Random notes for developers. 11. Bugs, versions and credits Contact information and ChangeLog A. Tips and tricks Some tips to make your life easier with Gmsh. B. Frequently asked questions The Gmsh FAQ C. License Complete copy of the license. Concept index Index of concepts. Syntax index Index of reserved keywords in the Gmsh language.
-- The Detailed Node Listing ---
Overview
General tools
2.1 Expressions 2.2 Operators 2.3 Built-in functions 2.4 User-defined functions 2.5 Loops and conditionals 2.6 General commands 2.7 General options
Expressions
2.1.1 Floating point expressions 2.1.2 Character expressions 2.1.3 Color expressions
Geometry module
3.1 Geometry commands 3.2 Geometry options
Geometry commands
3.1.1 Points 3.1.2 Lines 3.1.3 Surfaces 3.1.4 Volumes 3.1.5 Extrusions 3.1.6 Transformations 3.1.7 Miscellaneous
Mesh module
4.1 Elementary vs. physical entities 4.2 Mesh commands 4.3 Mesh options
Mesh commands
4.2.1 Characteristic lengths 4.2.2 Structured grids 4.2.3 Miscellaneous
Solver module
5.1 Solver options 5.2 Solver example
Post-processing module
6.1 Post-processing commands 6.2 Post-processing plugins 6.3 Post-processing options
Tutorial
7.1 `t1.geo' 7.2 `t2.geo' 7.3 `t3.geo' 7.4 `t4.geo' 7.5 `t5.geo' 7.6 `t6.geo' 7.7 `t7.geo' 7.8 `t8.geo' 7.9 `t9.geo'
Running Gmsh
8.1 Interactive mode 8.2 Non-interactive mode 8.3 Command-line options 8.4 Mouse actions 8.5 Keyboard shortcuts
File formats
9.1 MSH ASCII file format 9.2 MSH binary file format 9.3 Node ordering 9.4 Legacy formats
Legacy formats
9.4.1 MSH file format version 1.0 9.4.2 POS ASCII file format 9.4.3 POS binary file format
Programming notes
10.1 Main code structure 10.2 Coding style 10.3 Option handling
Bugs, versions and credits
11.1 Bugs 11.2 Versions 11.3 Credits
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gmsh is "free software"; this means that everyone is free to use it and to redistribute it on a free basis. Gmsh is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of Gmsh that they might get from you.
Specifically, we want to make sure that you have the right to give away copies of Gmsh, that you receive source code or else can get it if you want it, that you can change Gmsh or use pieces of Gmsh in new free programs, and that you know you can do these things.
To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of Gmsh, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.
Also, for our own protection, we must make certain that everyone finds out that there is no warranty for Gmsh. If Gmsh is modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.
The precise conditions of the license for Gmsh are found in the General Public License that accompanies the source code (see section C. License). Further information about this license is available from the GNU Project webpage http://www.gnu.org/copyleft/gpl-faq.html. Detailed copyright information can be found in 11.3 Credits.
The source code and various pre-compiled versions of Gmsh (for Unix, Windows and Mac OS) can be downloaded from the webpage http://geuz.org/gmsh/.
If you use Gmsh, we would appreciate that you mention it in your work. References, as well as the latest news about Gmsh development, are always available on http://geuz.org/gmsh/. Please send all Gmsh-related questions to the public Gmsh mailing list at gmsh@geuz.org.
If you want to integrate Gmsh into a closed-source software, or want to sell a modified closed-source version of Gmsh, please contact one of the authors. You can purchase a version of Gmsh under a different license, with "no strings attached" (for example allowing you to take parts of Gmsh and integrate them into your own proprietary code).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gmsh is an automatic three-dimensional finite element mesh generator with built-in pre- and post-processing facilities. Its design goal is to provide a simple meshing tool for academic problems with parametric input and advanced visualization capabilities.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gmsh uses a boundary representation ("b-rep") to describe geometries. Models are created in a bottom-up flow by successively defining points, oriented lines (line segments, circles, ellipses, splines, ...), oriented surfaces (plane surfaces, ruled surfaces, triangulated surfaces, ...) and volumes. Compound groups of geometrical entities (called "physical groups") can also be defined, based on these elementary geometric entities. Gmsh's scripting language allows all geometrical entities to be fully parameterized.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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(1). This automatically assures the conformity of the mesh when, for example, two surfaces share a common line. But this also implies that the discretization of an "isolated" (n-1)-th dimensional entity inside an n-th dimensional entity does not constrain the n-th dimensional mesh. Every meshing step is constrained by the characteristic length field, which can be uniform, specified by characteristic lengths associated with points in the geometry, or defined by general "fields" (a scalar field defined on another mesh using post-processing view, threshold fields associated with point or line "attractors", etc.).
For each meshing step, all structured mesh directives are executed first, and serve as additional constraints for the unstructured parts (2).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
External solvers can be interfaced with Gmsh through Unix or TCP/IP sockets, which permits to launch external computations and to collect and process the results directly from within Gmsh's post-processing module. The default solver interfaced with Gmsh is GetDP (http://www.geuz.org/getdp/). Examples on how to interface solvers written in C, C++, Perl and Python are available in the source distribution (in the `utils/solvers/' directory).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gmsh can load and manipulate multiple post-processing scalar, vector or tensor maps along with the geometry and the mesh. Scalar fields are represented by iso-value lines/surfaces or color maps, while vector fields are represented by three-dimensional arrows or displacement maps. Post-processing functions include section computation, offset, elevation, boundary and component extraction, color map and range modification, animation, vector graphic output, etc. All the post-processing options can be accessed either interactively or through the input ASCII text files. Scripting permits to automate all post-processing operations, as for example to create animations. User-defined operations can also be performed on post-processing views through dynamically loadable plugins.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gmsh is a (relatively) small program, and was principally developed "in academia, to solve academic problems"... 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:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Due to its historical background and limited developer manpower, Gmsh has also some (a lot of?) weaknesses:
If you have the skills and some free time, feel free to join the project! We gladly accept any code contributions (see section 10. Programming notes) to remedy the aforementioned (and all other) shortcomings...
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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).
this.
:) after a metasyntactic variable separates the variable
from its definition.
< > pairs.
|.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All Gmsh ASCII text input files support both C and C++ style comments:
/* and */ pairs is ignored;
// is ignored.
These commands won't have the described effects inside double quotes or inside keywords. Also note that `white space' (spaces, tabs, new line characters) is ignored inside all expressions.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 3. Geometry module, 4. Mesh module, 5. Solver module, and 6. 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 8. 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 7. Tutorial), you might want to come back here to learn more about the specific syntax of Gmsh's commands and esoteric options.
2.1 Expressions 2.2 Operators 2.3 Built-in functions 2.4 User-defined functions 2.5 Loops and conditionals 2.6 General commands 2.7 General options
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The two constant types used in Gmsh are real and string (there is no integer type). These types have the same meaning and syntax as in the C or C++ programming languages.
2.1.1 Floating point expressions 2.1.2 Character expressions 2.1.3 Color expressions
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Floating point expressions (or, more simply, "expressions") are denoted by the metasyntactic variable expression (remember the definition of the syntactic rules in 1.7 Syntactic rules used in this document), and are evaluated during the parsing of the data file:
expression:
real |
string |
string [ expression ] |
# string [ ] |
( expression ) |
operator-unary-left expression |
expression operator-unary-right |
expression operator-binary expression |
expression operator-ternary-left expression operator-ternary-right expression |
built-in-function |
real-option |
GetValue("string", expression)
|
Such expressions 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 operator-unary-left, operator-unary-right, operator-binary, operator-ternary-left and operator-ternary-right are defined in 2.2 Operators. For the definition of built-in-functions, see 2.3 Built-in functions. The various real-options are listed in 2.7 General options, 3.2 Geometry options, 4.3 Mesh options, 5.1 Solver options, and 6.3 Post-processing options.
The last case in the definition allows to ask the user for a value
interactively. For example, inserting GetValue("Value of parameter
alpha?", 5.76) in an input file will query the user for the value of a
certain parameter alpha, assuming the default value is 5.76. If the option
General.NoPopup is set (see section 2.7 General options), no question is
asked and the default value is automatically used.
List of expressions are also widely used, and are defined as:
expression-list: expression-list-item <, expression-list-item> ... |
with
expression-list-item:
expression |
expression : expression |
expression : expression : expression |
string [ ] |
string [ { expression-list } ] |
Point { expression } |
transform |
extrude
|
The second case in this last definition permits to create a list containing the range of numbers comprised between two expressions, with a unit incrementation step. The third case also permits to create a list containing the range of numbers comprised between two expressions, but with a positive or negative incrementation step equal to the third expression. The fourth 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 expression-list). The sixth case permits to retrieve the coordinates of a given geometry point (see section 3.1.1 Points). The last two cases permit to retrieve the indices of entities created through geometrical transformations and extrusions (see 3.1.6 Transformations, and 3.1.5 Extrusions).
To see the practical use of such expressions, have a look at the first
couple of examples in 7. Tutorial. Note that, in order to lighten the
syntax, you can always omit the braces {} enclosing an
expression-list if this expression-list only contains a single
item. Also note that a braced expression-list can be preceded by a
minus sign in order to change the sign of all the
expression-list-items.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Character expressions are defined as:
char-expression: "string" | Today | StrPrefix ( char-expression ) | StrRelative ( char-expression ) | StrCat ( char-expression , char-expression ) | Sprintf ( char-expression , expression-list ) | Sprintf ( char-expression ) Sprintf ( char-option ) |
The third and fourth cases in this definition permit to take the
prefix (e.g. to remove the extension) or the relative path of a string. The
fifth case permits to concatenate two character expressions, and the sixth
and seventh are equivalent to the sprintf C function (where
char-expression is a format string that can contain floating point
formatting characters: %e, %g, etc.). The last case permits to
use the value of a char-option as a char-expression. The
various char-options are listed in 2.7 General options,
3.2 Geometry options, 4.3 Mesh options, 5.1 Solver options, and
6.3 Post-processing options.
Character expressions are mostly used to specify non-numeric options and input/output file names. See 7.8 `t8.geo', for an interesting usage of char-expressions in an animation script.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Colors expressions are hybrids between fixed-length braced expression-lists and strings:
color-expression:
string |
{ expression, expression, expression } |
{ expression, expression, expression, expression } |
color-option
|
The first case permits to use the X Windows names to refer to colors,
e.g., Red, SpringGreen, LavenderBlush3, ...
(see `Common/Colors.h' in 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 color-option as a color-expression. The
various color-options are listed in 2.7 General options,
3.2 Geometry options, 4.3 Mesh options, 5.1 Solver options, and
6.3 Post-processing options.
See 7.3 `t3.geo', for an example of the use of color expressions.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gmsh's operators are similar to the corresponding operators in C and C++. Here is the list of the unary, binary and ternary operators currently implemented.
operator-unary-left:
-
!
operator-unary-right:
++
--
operator-binary:
^
*
/
%
+
-
==
!=
>
>=
<
<=
&&
||
|| is evaluated even if the first one is true).
operator-ternary-left:
?
:
The evaluation priorities are summarized below(3) (from stronger to
weaker, i.e., * has a highest evaluation priority than +).
Parentheses () may be used anywhere to change the order of
evaluation:
(), [], ., #
^
!, ++, --, - (unary)
*, /, %
+, -
<, >, <=, >=
==, !=
&&
||
?:
=, +=, -=, *=, /=
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A built-in function is composed of an identifier followed by a pair of parentheses containing an expression-list (the list of its arguments)(4). Here is the list of the built-in functions currently implemented:
build-in-function:
Acos ( expression )
Asin ( expression )
Atan ( expression )
Atan2 ( expression, expression )
Ceil ( expression )
Cos ( expression )
Cosh ( expression )
Exp ( expression )
Fabs ( expression )
Fmod ( expression, expression )
Floor ( expression )
Hypot ( expression, expression )
Log ( expression )
Log10 ( expression )
Modulo ( expression, expression )
Fmod( expression, expression ).
Rand ( expression )
Sqrt ( expression )
Sin ( expression )
Sinh ( expression )
Tan ( expression )
Tanh ( expression )
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
User-defined functions take no arguments, and are evaluated as if a file
containing the function body was included at the location of the Call
statement.
Function string
Function
string', and can contain any Gmsh command.
Return
Call string;
See 7.5 `t5.geo', for an example of a user-defined function.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Loops and conditionals are defined as follows, and can be imbricated:
For ( expression : expression )
For ( expression :
expression )' and the matching EndFor are executed.
For ( expression : expression : expression )
For ( expression : expression :
expression )' and the matching EndFor are executed.
For string In { expression : expression }
For string In {
expression : expression }' and the matching EndFor are
executed.
For string In { expression : expression : expression }
For string In { expression :
expression : expression }' and the matching EndFor are
executed.
EndFor
For command.
If ( expression )
If ( expression )' and the matching
Endif is evaluated if expression is non-zero.
EndIf
If command.
See 7.5 `t5.geo', for an example of For and If commands. Gmsh
does not provide any Else (or similar) command at the time of this
writing.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following commands can be used anywhere in a Gmsh ASCII text input file:
string = expression;
Pi
GMSH_MAJOR_VERSION
GMSH_MINOR_VERSION
GMSH_PATCH_VERSION
MPI_Size
MPI_Rank
newp
newp permits to know the highest number already attributed (plus
one). This is mostly useful when writing user-defined functions
(see section 2.4 User-defined functions) or general geometric primitives, when one
does not know a priori which numbers are already attributed, and
which ones are still available.
newl
news
newv
newll
newsl
newreg
newreg returns the
maximum of newp, newl, news, newv and all
physical entity numbers(5).
string [ ] = { };
string[] with an
empty list.
string [ ] = { expression-list };
string[] with the
list expression-list, or affects expression-list to an
existing expression list identifier. (Remember the remark we made when
we defined expression-lists: the braces enclosing an
expression-list are optional if the list only contains a single
item.)
string [ { expression-list } ] = { expression-list };
real-option = expression;
char-option = char-expression;
color-option = color-expression;
string | real-option += expression;
string | real-option -= expression;
string | real-option *= expression;
string | real-option /= expression;
string [ ] += { expression-list };
string [ { expression-list } ] += { expression-list };
string [ { expression-list } ] -= { expression-list };
string [ { expression-list } ] *= { expression-list };
string [ { expression-list } ] /= { expression-list };
Exit;
Printf ( char-expression , expression-list );
Printf is equivalent to the printf C function:
char-expression is a format string that can contain formatting
characters (%f, %e, etc.). Note that all expressions
are evaluated as floating point values in Gmsh (see section 2.1 Expressions), so
that only valid floating point formatting characters make sense in
char-expression. See 7.5 `t5.geo', for an example of the use of
Printf.
Printf ( char-expression , expression-list ) > char-expression;
Printf above, but output the expression in a file.
Printf ( char-expression , expression-list ) >> char-expression;
Printf above, but appends the expression at the end of
the file.
Merge char-expression;
Draw;
BoundingBox;