Gmsh 2.15

Table of Contents

Gmsh

Christophe Geuzaine and Jean-François Remacle

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

Obtaining Gmsh

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

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

Copying conditions

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

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

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

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

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

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

1 Overview

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

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

1.1 Geometry: geometrical entity definition

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

1.2 Mesh: finite element mesh generation

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

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

For each meshing step, all structured mesh directives are executed first, and serve as additional constraints for the unstructured parts ¹.

1.3 Solver: external solver interface

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

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

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

1.5 What Gmsh is pretty good at …

Here is a tentative list of what Gmsh does best:

• quickly describe simple and/or “repetitive” geometries, thanks to user-defined macros, loops, conditionals and includes (see User-defined macros, Loops and conditionals, and General commands);
• parametrize these geometries. Gmsh’s scripting language enables all commands and command arguments to depend on previous calculations (see Expressions, and Geometry commands);
• generate 1D, 2D and 3D simplicial (i.e., using line segments, triangles and tetrahedra) finite element meshes for CAD models in their native format (without translations) when linked with the appropriate CAD kernel (see Mesh module);
• specify target element sizes accurately. Gmsh provides several mechanisms to control the size of the elements in the final mesh: through interpolation from sizes specified at geometry points or using flexible mesh size fields (see Mesh commands);
• create simple extruded geometries and meshes (see Geometry commands, and Mesh commands);
• interact with external solvers through a simple client-server architecture (see Solver module);
• visualize and export computational results in a great variety of ways. Gmsh can display scalar, vector and tensor datasets, perform various operations on the resulting post-processing views (see Post-processing module), can export plots in many different formats (see General options list), and can generate complex animations (see General tools, and t8.geo);
• run on low end machines and/or machines with no graphical interface. Gmsh can be compiled with or without the GUI (see Compiling the source code), and all versions can be used either interactively or directly from the command line (see Running Gmsh on your system);
• configure your preferred options. Gmsh has a large number of configuration options that can be set interactively using the GUI, scattered inside command files, changed on the fly in scripts, set in per-user configuration files, or specified on the command-line (see Running Gmsh on your system and Options);
• and do all the above on various platforms (Windows, Mac and Unix), for free (see Copying conditions), using simple script files and/or a small but powerful GUI.

1.6 … and what Gmsh is not so good at

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

• the BRep approach for describing geometries can become inconvenient/inefficient for large models. For complex models, or if you want to use a solid-modeler approach, you should link Gmsh with an external CAD kernel and import native files directly. (The binary versions available on http://gmsh.info are linked with the free CAD kernel OpenCASCADE, which enables native BREP import as well as STEP and IGES import.)
• Gmsh’s internal CAD engine is fairly limited: it only handles simple primitives and does not perform any complex geometrical operations (e.g. no calculation of intersections). For such features you should link Gmsh with an external CAD kernel (see above).
• Gmsh is not a multi-bloc mesh generator: all meshes produced by Gmsh are conforming in the sense of finite element meshes;
• Gmsh’s user interface is only exposing a limited number of the available features, and many aspects of the interface could be enhanced (especially manipulators).
• Gmsh’s scripting language is fairly limited, providing only very crude loop controls and user-defined macros, with no local variables.
• there is no global “undo” capability. You will often need to edit a text file to correct mistakes.

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

1.7 Bug reports

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

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

2 How to read this reference manual?

Gmsh can be used at three levels:

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

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

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

Finally, to use Gmsh at the third level (i.e., to link the Gmsh library with your own code), you will need to learn the internal Gmsh Application Programming Interface (API). No complete documentation of this API is available yet; a good starting point is Source code structure, which gives a short introduction to Gmsh’s internal source code structure. Then have a look e.g. at the examples in the utils/api_demos⁴ directory in the source code. To build the library see the instructions in Compiling the source code and in the top-level README.txt file in the source distribution.

2.1 Syntactic rules used in the manual

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

1. Keywords and literal symbols are printed like this.
2. Metasyntactic variables (i.e., text bits that are not part of the syntax, but stand for other text bits) are printed like this.
3. A colon (:) after a metasyntactic variable separates the variable from its definition.
4. Optional rules are enclosed in < > pairs.
5. Multiple choices are separated by |.
6. Three dots (…) indicate a possible (multiple) repetition of the preceding rule.

3 Running Gmsh on your system

3.1 Interactive mode

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

> gmsh

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

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

> gmsh t1.geo

To perform the mesh generation, go to the mesh module (by selecting ‘Mesh’ in the tree) and choose the dimension (‘1D’ will mesh all the lines; ‘2D’ will mesh all the surfaces—as well as all the lines if ‘1D’ was not called before; ‘3D’ will mesh all the volumes—and all the surfaces if ‘2D’ was not called before). To save the resulting mesh in the current mesh format click on ‘Save’, or select the appropriate format and file name with the ‘File->Save As’ menu. The default mesh file name is based on the name of the current active model, with an appended extension depending on the mesh format⁶.

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

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

> gmsh t1.geo view1.pos view5.msh

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

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

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

3.2 Non-interactive mode

Gmsh can be run non-interactively in ‘batch’ mode, without GUI⁸. For example, to mesh the first tutorial in batch mode, just type:

> gmsh t1.geo -2

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

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

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

> gmsh script.geo -

The script can contain e.g. meshing commands, like Mesh 3;.

3.3 Command-line options

Geometry options:

-0

Output model, then exit

-tol float

Set geometrical tolerance

-match

Match geometries and meshes

Mesh options:

-1, -2, -3

Perform 1D, 2D or 3D mesh generation, then exit

-o file

Specify output file name

-format string

Select output mesh format (auto (default), msh, msh1, msh2, unv, vrml, ply2, stl, mesh, bdf, cgns, p3d, diff, med, ...)

-bin

Use binary format when available

-refine

Perform uniform mesh refinement, then exit

-part int

Partition after batch mesh generation

-partWeight tri|quad|tet|prism|hex int

Weight of a triangle/quad/etc. during partitioning

-saveall

Save all elements (discard physical group definitions)

-parametric

Save vertices with their parametric coordinates

-algo string

Select mesh algorithm (meshadapt, del2d, front2d, delquad, del3d, front3d, mmg3d, pack)

-smooth int

Set number of mesh smoothing steps

-order int

Set mesh order (1, ..., 5)

-optimize[_netgen]

Optimize quality of tetrahedral elements

-optimize_ho

Optimize high order meshes

-ho_[min,max,nlayers]

High-order optimization parameters

-optimize_lloyd

Optimize 2D meshes using Lloyd algorithm

-clscale float

Set global mesh element size scaling factor

-clmin float

Set minimum mesh element size

-clmax float

Set maximum mesh element size

-anisoMax float

Set maximum anisotropy (only used in bamg for now)

-smoothRatio float

Set smoothing ration between mesh sizes at nodes of a same edge (only used in bamg)

-clcurv

Automatically compute element sizes from curvatures

-epslc1d

Set accuracy of evaluation of LCFIELD for 1D mesh

-swapangle

Set the threshold angle (in degree) between two adjacent faces below which a swap is allowed

-rand float

Set random perturbation factor

-bgm file

Load background mesh from file

-check

Perform various consistency checks on mesh

-ignorePartBound

Ignore partitions boundaries

Post-processing options:

-link int

Select link mode between views (0, 1, 2, 3, 4)

-combine

Combine views having identical names into multi-time-step views

Solver options:

-listen

Always listen to incoming connection requests

-minterpreter string

Name of Octave interpreter

-pyinterpreter string

Name of Python interpreter

-run

Run ONELAB solver(s)

Display options:

-n

Hide all meshes and post-processing views on startup

-nodb

Disable double buffering

-numsubedges

Set num of subdivisions for high order element display

-fontsize int

Specify the font size for the GUI

-theme string

Specify FLTK GUI theme

-display string

Specify display

-camera

Use camera mode view;

-stereo

OpenGL quad-buffered stereo rendering (requires special graphic card)

-gamepad

Use gamepad controller if available

Other options:

-, -parse_and_exit

Parse input files, then exit

-new

Create new model before merge next file

-merge

Merge next files

-open

Open next files

-a, -g, -m, -s, -p

Start in automatic, geometry, mesh, solver or post-processing mode

-pid

Print process id on stdout

-watch pattern

Pattern of files to merge as they become available

-bg file

Load background (image or PDF) file

-v int

Set verbosity level

-nopopup

Don’t popup dialog windows in scripts

-string "string"

Parse command string at startup

-setnumber name value

Set constant number name=value

-setstring name value

Set constant string name=value

-option file

Parse option file at startup

-convert files

Convert files into latest binary formats, then exit

-cpu

Report CPU times for all operations

-version

Show version number

-info

Show detailed version information

-help

Show command line usage

3.4 Mouse actions

Move

- Highlight the entity under the mouse pointer and display its properties

- Resize a lasso zoom or a lasso (un)selection

Left button

- Rotate

- Select an entity

- Accept a lasso zoom or a lasso selection

Ctrl+Left button

Start a lasso zoom or a lasso (un)selection

Middle button

- Zoom

- Unselect an entity

- Accept a lasso zoom or a lasso unselection

Ctrl+Middle button

Orthogonalize display

Right button

- Pan

- Cancel a lasso zoom or a lasso (un)selection

- Pop-up menu on post-processing view button

Ctrl+Right button

Reset to default viewpoint

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

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

3.5 Keyboard shortcuts

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

Left arrow

Go to previous time step

Right arrow

Go to next time step

Up arrow

Make previous view visible

Down arrow

Make next view visible

0

Reload geometry

Ctrl+0

Reload full project

1 or F1

Mesh lines

2 or F2

Mesh surfaces

3 or F3

Mesh volumes

Escape

Cancel lasso zoom/selection, toggle mouse selection ON/OFF

g

Go to geometry module

m

Go to mesh module

p

Go to post-processing module

s

Go to solver module

Shift+a

Bring all windows to front

Shift+g

Show geometry options

Shift+m

Show mesh options

Shift+o

Show general options

Shift+p

Show post-processing options

Shift+s

Show solver options

Shift+u

Show post-processing view plugins

Shift+w

Show post-processing view options

Shift+Escape

Enable full mouse selection

Ctrl+d

Attach/detach menu

Ctrl+f

Enter full screen

Ctrl+i

Show statistics window

Ctrl+j

Save model options

Ctrl+l

Show message console

Ctrl+m

Minimize window

Ctrl+n

Create new project file

Ctrl+o

Open project file

Ctrl+q

Quit

Ctrl+r

Rename project file

Ctrl+s

Save file as

Shift+Ctrl+c

Show clipping plane window

Shift+Ctrl+h

Show current options and workspace window

Shift+Ctrl+j

Save options as default

Shift+Ctrl+m

Show manipulator window

Shift+Ctrl+n

Show option window

Shift+Ctrl+o

Merge file(s)

Shift+Ctrl+s

Save mesh in default format

Shift+Ctrl+u

Show plugin window

Shift+Ctrl+v

Show visibility window

Alt+a

Loop through axes modes

Alt+b

Hide/show bounding boxes

Alt+c

Loop through predefined color schemes

Alt+e

Hide/Show element outlines for visible post-pro views

Alt+f

Change redraw mode (fast/full)

Alt+h

Hide/show all post-processing views

Alt+i

Hide/show all post-processing view scales

Alt+l

Hide/show geometry lines

Alt+m

Toggle visibility of all mesh entities

Alt+n

Hide/show all post-processing view annotations

Alt+o

Change projection mode (orthographic/perspective)

Alt+p

Hide/show geometry points

Alt+r

Loop through range modes for visible post-pro views

Alt+s

Hide/show geometry surfaces

Alt+t

Loop through interval modes for visible post-pro views

Alt+v

Hide/show geometry volumes

Alt+w

Enable/disable all lighting

Alt+x

Set X view

Alt+y

Set Y view

Alt+z

Set Z view

Alt+Shift+a

Hide/show small axes

Alt+Shift+b

Hide/show mesh volume faces

Alt+Shift+c

Loop through predefined colormaps

Alt+Shift+d

Hide/show mesh surface faces

Alt+Shift+l

Hide/show mesh lines

Alt+Shift+p

Hide/show mesh points

Alt+Shift+s

Hide/show mesh surface edges

Alt+Shift+t

Same as Alt+t, but with numeric mode included

Alt+Shift+v

Hide/show mesh volume edges

Alt+Shift+x

Set -X view

Alt+Shift+y

Set -Y view

Alt+Shift+z

Set -Z view

4 General tools

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

4.1 Comments

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

1. any text comprised between /* and */ pairs is ignored;
2. the rest of a line after a double slash // is ignored.

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

4.2 Expressions

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

4.2.1 Floating point expressions

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

expression:
  real |
  string |
  string ~ { expression }
  string [ expression ] |
  # 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 |
  Find(expression-list-item, expression-list-item) |
  StrFind(char-expression, char-expression) |
  StrCmp(char-expression, char-expression) |
  StrLen(char-expression) |
  TextAttributes(char-expression<,char-expression…>) |
  Exists(string) | Exists(string~{ expression }) |
  FileExists(char-expression) |
  StringToName(char-expression) | S2N(char-expression) |
  GetNumber(char-expression <,expression>) |
  GetValue("string", expression) |
  DefineNumber(expression, onelab-options) |

Such expressions are used in most of Gmsh’s scripting commands. When ~{expression} is appended to a string string, the result is a new string formed by the concatenation of string, _ (an underscore) and the value of the expression. This is most useful in loops (see Loops and conditionals), where it permits to define unique strings automatically. For example,

For i In {1:3}
  x~{i} = i;
EndFor

is the same as

x_1 = 1;
x_2 = 2;
x_3 = 3;

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

DefineNumber allows to define a ONELAB variable in-line. The expression given as the first argument is the default value; this is followed by the various ONELAB options. See http://onelab.info/wiki/ONELAB_Syntax_for_Gmsh_and_GetDP for more information.

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 [ ] | 
  List [ string ] |
  List [ expression-list-item ] |
  List [ { expression-list } ] |
  string [ { expression-list } ] | 
  Point { expression } |
  transform |
  extrude
  Point { expression } |
  <Physical> Point|Line|Surface|Volume "*" |
  Point|Line|Surface|Volume In BoundingBox { expression-list } |
  Physical Point|Line|Surface|Volume { expression-list }

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

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

4.2.2 Character expressions

Character expressions are defined as:

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

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

DefineString allows to define a ONELAB variable in-line. The char-expression given as the first argument is the default value; this is followed by the various ONELAB options. See http://onelab.info/wiki/ONELAB_Syntax_for_Gmsh_and_GetDP for more information.

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

List of character expressions are defined as:

char-expression-list: 
  char-expression <,…>

4.2.3 Color expressions

Colors expressions are hybrids between fixed-length braced expression-lists and strings:

color-expression:
  char-expression |
  { expression, expression, expression } |
  { expression, expression, expression, expression } |
  color-option

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

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

4.3 Operators

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

operator-unary-left:

-

Unary minus.

!

Logical not.

operator-unary-right:

++

Post-incrementation.

--

Post-decrementation.

operator-binary:

^

Exponentiation.

*

Multiplication.

/

Division.

%

Modulo.

+

Addition.

-

Subtraction.

==

Equality.

!=

Inequality.

>

Greater.

>=

Greater or equality.

<

Less.

<=

Less or equality.

&&

Logical ‘and’.

||

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

operator-ternary-left:

?

operator-ternary-right:

:

The only ternary operator, formed by operator-ternary-left and operator-ternary-right, returns the value of its second argument if the first argument is non-zero; otherwise it returns the value of its third argument.

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

1. (), [], ., #
2. ^
3. !, ++, --, - (unary)
4. *, /, %
5. +, -
6. <, >, <=, >=
7. ==, !=
8. &&
9. ||
10. ?:
11. =, +=, -=, *=, /=

4.4 Built-in functions

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

build-in-function:

Acos ( expression )

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

Asin ( expression )

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

Atan ( expression )

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

Atan2 ( expression, expression )

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

Ceil ( expression )

Rounds expression up to the nearest integer.

Cos ( expression )

Cosine of expression.

Cosh ( expression )

Hyperbolic cosine of expression.

Exp ( expression )

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

Fabs ( expression )

Absolute value of expression.

Fmod ( expression, expression )

Remainder of the division of the first expression by the second, with the sign of the first.

Floor ( expression )

Rounds expression down to the nearest integer.

Hypot ( expression, expression )

Returns the square root of the sum of the square of its two arguments.

Log ( expression )

Natural logarithm of expression (expression > 0).

Log10 ( expression )

Base 10 logarithm of expression (expression > 0).

Modulo ( expression, expression )

see Fmod( expression, expression ).

Rand ( expression )

Random number between zero and expression.

Round ( expression )

Rounds expression to the nearest integer.

Sqrt ( expression )

Square root of expression (expression >= 0).

Sin ( expression )

Sine of expression.

Sinh ( expression )

Hyperbolic sine of expression.

Tan ( expression )

Tangent of expression.

Tanh ( expression )

Hyperbolic tangent of expression.

4.5 User-defined macros

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

Macro string | char-expression

Begins the declaration of a user-defined macro named string. The body of the macro starts on the line after ‘Macro string’, and can contain any Gmsh command. A synonym for Macro is Function.

Return

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

Call string | char-expression ;

Executes the body of a (previously defined) macro named string.

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

4.6 Loops and conditionals

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

For ( expression : expression )

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

For ( expression : expression : expression )

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

For string In { expression : expression }

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

For string In { expression : expression : expression }

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

EndFor

Ends a matching For command.

If ( expression )

The body enclosed between ‘If ( expression )’ and the matching ElseIf, Else or EndIf, is evaluated if expression is non-zero.

ElseIf ( expression )

The body enclosed between ‘ElseIf ( expression )’ and the next matching ElseIf, Else or EndIf, is evaluated if expression is non-zero and none of the expression of the previous matching codes If and ElseIf were non-zero.

Else

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

EndIf

Ends a matching If command.

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

4.7 General commands

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

string = expression;

Creates a new expression identifier string, or affects expression to an existing expression identifier. Thirteen expression identifiers are predefined (hardcoded in Gmsh’s parser):

Pi

Returns 3.1415926535897932.

GMSH_MAJOR_VERSION

Returns Gmsh’s major version number.

GMSH_MINOR_VERSION

Returns Gmsh’s minor version number.

GMSH_PATCH_VERSION

Returns Gmsh’s patch version number.

MPI_Size

Returns the number of processors on which Gmsh is running. It is always 1, except if you compiled Gmsh with ENABLE_MPI (see Compiling the source code).

MPI_Rank

Returns the rank of the current processor.

Cpu

Returns the current CPU time (in seconds).

Memory

Returns the current memory usage (in Mb).

TotalMemory

Returns the total memory available (in Mb).

newp

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

newl

Returns the next available line number.

news

Returns the next available surface number.

newv

Returns the next available volume number.

newll

Returns the next available line loop number.

newsl

Returns the next available surface loop number.

newreg

Returns the next available region number. That is, newreg returns the maximum of newp, newl, news, newv, newll, newsl and all physical entity numbers¹².

string = { };

Creates a new expression list identifier string with an empty list.

string[] = { expression-list };

Creates a new expression list identifier string with the list expression-list, or affects expression-list to an existing expression list identifier. Parentheses are also allowed instead of square brackets; although not recommended, brackets and parentheses can also be completely ommitted.

string [ { expression-list } ] = { expression-list };

Affects each item in the right hand side expression-list to the elements (indexed by the left hand side expression-list) of an existing expression list identifier. The two expression-lists must contain the same number of items. Parentheses can also be used instead of brackets.

string += expression;

Adds and affects expression to an existing expression identifier.

string -= expression;

Subtracts and affects expression to an existing expression identifier.

string *= expression;

Multiplies and affects expression to an existing expression identifier.

string /= expression;

Divides and affects expression to an existing expression identifier.

string += { expression-list };

Appends expression-list to an existing expression list or creates a new expression list with expression-list.

string -= { expression-list };

Removes the items in expression-list from the existing expression list.

string [ { expression-list } ] += { expression-list };

Adds and affects, item per item, the right hand side expression-list to an existing expression list identifier. Parentheses can also be used instead of brackets.

string [ { expression-list } ] -= { expression-list };

Subtracts and affects, item per item, the right hand side expression-list to an existing expression list identifier. Parentheses can also be used instead of brackets.

string [ { expression-list } ] *= { expression-list };

Multiplies and affects, item per item, the right hand side expression-list to an existing expression list identifier. Parentheses can also be used instead of brackets.

string [ { expression-list } ] /= { expression-list };

Divides and affects, item per item, the right hand side expression-list to an existing expression list identifier. Parentheses can also be used instead of brackets.

string = char-expression;

Creates a new character expression identifier string with a given char-expression.

string[] = Str( char-expression-list ) ;

Creates a new character expression list identifier string with a given char-expression-list. Parentheses can also be used instead of brackets.

string[] += Str( char-expression-list ) ;

Appends a character expression list to an existing list. Parentheses can also be used instead of brackets.

DefineConstant[ string = expression|char-expression <, ...>];

Creates a new expression identifier string, with value expression, only if has not been defined before.

DefineConstant[ string = { expression|char-expression, onelab-options } <, ...>];

Same as the previous case, except that the variable is also exchanged with the ONELAB database if it has not been defined before. See http://onelab.info/wiki/ONELAB_Syntax_for_Gmsh_and_GetDP for more information.

SetNumber( char-expression , expression );

Sets the value a numeric ONELAB variable char-expression.

SetString( char-expression , char-expression );

Sets the value a string ONELAB variable char-expression.

real-option = expression;

Affects expression to a real option.

char-option = char-expression;

Affects char-expression to a character option.

color-option = color-expression;

Affects color-expression to a color option.

real-option += expression;

Adds and affects expression to a real option.

real-option -= expression;

Subtracts and affects expression to a real option.

real-option *= expression;

Multiplies and affects expression to a real option.

real-option /= expression;

Divides and affects expression to a real option.

Abort;

Aborts the current script.

Exit;

Exits Gmsh.

CreateDir char-expression;

Create the directory char-expression.

Printf ( char-expression <, expression-list> );

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

Printf ( char-expression , expression-list ) > char-expression;

Same as Printf above, but output the expression in a file.

Printf ( char-expression , expression-list ) >> char-expression;

Same as Printf above, but appends the expression at the end of the file.

Error ( char-expression <, expression-list> );

Same as Printf, but raises an error.

Merge char-expression;

Merges a file named char-expression. This command is equivalent to the ‘File->Merge’ menu in the GUI. If the path in char-expression is not absolute, char-expression is appended to the path of the current file.

Draw;

Redraws the scene.

SetChanged;

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

BoundingBox;

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

1. If there is a mesh (i.e., at least one mesh vertex), the bounding box is taken as the box enclosing all the mesh vertices;
2. If there is no mesh but there is a geometry (i.e., at least one geometrical point), the bounding box is taken as the box enclosing all the geometrical points;
3. If there is no mesh and no geometry, but there are some post-processing views, the bounding box is taken as the box enclosing all the primitives in the views.

BoundingBox { expression, expression, expression, expression, expression, expression };

Forces the bounding box of the scene to the given expressions (X min, X max, Y min, Y max, Z min, Z max).

Delete Model;

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

Delete Physicals;

Deletes all physical groups.

Delete Variables;

Deletes all the expressions.

Delete Options;

Deletes the current options and revert to the default values.

Delete string;

Deletes the expression string.

Print char-expression;

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

Sleep expression;

Suspends the execution of Gmsh during expression seconds.

SystemCall char-expression;

Executes a (blocking) system call.

NonBlockingSystemCall char-expression;

Executes a (non-blocking) system call.

OnelabRun ( char-expression <, char-expression > )

Runs a ONELAB client (first argument is the client name, second optional arguement is the command line).

SetName char-expression;

Changes the name of the current model.

SyncModel;

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

NewModel;

Creates a new current model.

Include char-expression;

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

4.8 General options

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

5 Geometry module

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

These geometrical entities are called “elementary” in Gmsh’s jargon, and are assigned identification numbers (stricly positive) when they are created:

1. each elementary point must possess a unique identification number;
2. each elementary line must possess a unique identification number;
3. each elementary surface must possess a unique identification number;
4. each elementary volume must possess a unique identification number.

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

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

5.1 Geometry commands

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

5.1.1 Points

Point ( expression ) = { expression, expression, expression <, expression > };

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

Physical Point ( expression | char-expression <, expression> ) <+|->= { expression-list };

Creates a physical point. The expression inside the parentheses is the physical point’s identification number; the expression-list on the right hand side should contain the identification numbers of all the elementary points that need to be grouped inside the physical point. If a char-expression is given instead instead of expression inside the parentheses, a string label is associated with the physical identification number, which can be either provided explicitly (after the comma) or not (in which case a unique identification number is automatically created).

5.1.2 Lines

BSpline ( expression ) = { expression-list };

Creates a B-spline curve. The expression inside the parentheses is the B-spline curve’s identification number; the expression-list on the right hand side should contain the identification numbers of all the B-spline’s control points. Repeating control points has the expected effect.

Circle ( expression ) = { expression, expression, expression };

Creates a circle arc (strictly) smaller than Pi. The expression inside the parentheses is the circle arc’s identification number; the first expression inside the braces on the right hand side gives the identification number of the start point of the arc; the second expression gives the identification number of the center of the circle; the last expression gives the identification number of the end point of the arc.

CatmullRom ( expression ) = { expression-list };

CatmullRom is a synonym for Spline.

Ellipse ( expression ) = { expression, expression, expression, expression };

Creates an ellipse arc. The expression inside the parentheses is the ellipse arc’s identification number; the first expression inside the braces on the right hand side gives the identification number of the start point of the arc; the second expression gives the identification number of the center of the ellipse; the third expression gives the identification number of any point located on the major axis of the ellipse; the last expression gives the identification number of the end point of the arc.

Line ( expression ) = { expression, expression };

Creates a straight line segment. The expression inside the parentheses is the line segment’s identification number; the two expressions inside the braces on the right hand side give identification numbers of the start and end points of the segment.

Spline ( expression ) = { expression-list };

Creates a spline curve. The expression inside the parentheses is the spline’s identification number; the expression-list on the right hand side should contain the identification numbers of all the spline’s control points.

Line Loop ( expression ) = { expression-list };

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

Compound Line ( expression ) = { expression-list };

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

Physical Line ( expression | char-expression <, expression> ) <+|->= { expression-list };

Creates a physical line. The expression inside the parentheses is the physical line’s identification number; the expression-list on the right hand side should contain the identification numbers of all the elementary lines that need to be grouped inside the physical line. If a char-expression is given instead instead of expression inside the parentheses, a string label is associated with the physical identification number, which can be either provided explicitly (after the comma) or not (in which case a unique identification number is automatically created). Specifying negative identification numbers in the expression-list will reverse the orientation of the mesh elements belonging to the corresponding elementary lines in the saved mesh.

5.1.3 Surfaces

Plane Surface ( expression ) = { expression-list };

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

Ruled Surface ( expression ) = { expression-list } < In Sphere { expression } >;

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

Surface Loop ( expression ) = { expression-list };

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

Compound Surface ( expression ) = { expression-list } < Boundary { { expression-list }, { expression-list }, { expression-list }, { expression-list } } > ;

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

Physical Surface ( expression | char-expression <, expression> ) <+|->= { expression-list };

Creates a physical surface. The expression inside the parentheses is the physical surface’s identification number; the expression-list on the right hand side should contain the identification numbers of all the elementary surfaces that need to be grouped inside the physical surface. If a char-expression is given instead instead of expression inside the parentheses, a string label is associated with the physical identification number, which can be either provided explicitly (after the comma) or not (in which case a unique identification number is automatically created). Specifying negative identification numbers in the expression-list will reverse the orientation of the mesh elements belonging to the corresponding elementary surfaces in the saved mesh.

5.1.4 Volumes

Volume ( expression ) = { expression-list };

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

Compound Volume ( expression ) = { expression-list };

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

Physical Volume ( expression | char-expression <, expression> ) <+|->= { expression-list };

Creates a physical volume. The expression inside the parentheses is the physical volume’s identification number; the expression-list on the right hand side should contain the identification numbers of all the elementary volumes that need to be grouped inside the physical volume. If a char-expression is given instead instead of expression inside the parentheses, a string label is associated with the physical identification number, which can be either provided explicitly (after the comma) or not (in which case a unique identification number is automatically created).

5.1.5 Extrusions

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

extrude:

Extrude { expression-list } { extrude-list }

Extrudes all elementary entities (points, lines or surfaces) in extrude-list using a translation. The expression-list should contain three expressions giving the X, Y and Z components of the translation vector.

Extrude { { expression-list }, { expression-list }, expression } { extrude-list }

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

Extrude { { expression-list }, { expression-list }, { expression-list }, expression } { extrude-list }

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

with

extrude-list: 
  Point | Line | Surface { expression-list }; …

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

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

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

5.1.6 Transformations

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

transform:

Dilate { { expression-list }, expression } { transform-list }

Scales all elementary entities in transform-list by a factor expression. The expression-list should contain three expressions giving the X, Y and Z direction of the homothetic transformation.

Rotate { { expression-list }, { expression-list }, expression } { transform-list }

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

Symmetry { expression-list } { transform-list }

Transforms all elementary entities symmetrically to a plane. The expression-list should contain four expressions giving the coefficients of the plane’s equation.

Translate { expression-list } { transform-list }

Translates all elementary entities in transform-list. The expression-list should contain three expressions giving the X, Y and Z components of the translation vector.

Boundary { transform-list }

(Not a transformation per-se.) Returns the boundary of the elementary entities in transform-list.

CombinedBoundary { transform-list }

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

with

transform-list: 
  Point | Line | Surface | Volume { expression-list }; … |
  Duplicata { Point | Line | Surface | Volume { expression-list }; … } |
  transform

5.1.7 Miscellaneous

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

Coherence;

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

Delete { Point | Line | Surface | Volume { expression-list }; … }

Deletes all elementary entities whose identification numbers are given in expression-list. If an entity is linked to another entity (for example, if a point is used as a control point of a curve), Delete has no effect (the line will have to be deleted before the point can).

< Recursive > Hide { Point | Line | Surface | Volume { expression-list }; … }

Hide the entities listed in expression-list, if General.VisibilityMode is set to 0 or 1.

Hide char-expression;

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

< Recursive > Show { Point | Line | Surface | Volume { expression-list }; … }

Show the entities listed in expression-list, if General.VisibilityMode is set to 0 or 1.

Show char-expression;

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

5.2 Geometry options

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

6 Mesh module

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

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

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

6.1 Choosing the right unstructured algorithm

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

For all 2D unstructured algorithms a Delaunay mesh that contains all the points of the 1D mesh is initially constructed using a divide-and-conquer algorithm¹³. Missing edges are recovered using edge swaps¹⁴. After this initial step three different algorithms can be applied to generate the final mesh:

1. The “MeshAdapt” algorithm¹⁵ is based on local mesh modifications. This technique makes use of edge swaps, splits, and collapses: long edges are split, short edges are collapsed, and edges are swapped if a better geometrical configuration is obtained.
2. The “Delaunay” algorithm is inspired by the work of the GAMMA team at INRIA¹⁶. New points are inserted sequentially at the circumcenter of the element that has the largest adimensional circumradius. The mesh is then reconnected using an anisotropic Delaunay criterion.
3. The “Frontal” algorithm is inspired by the work of S. Rebay¹⁷.

These algorithms can be ranked as follows:

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

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

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

In 3D two unstructured algorithms are available:

1. The “Delaunay” algorithm is split into two separate steps. First, an initial mesh of the union of all the volumes in the model is performed using H. Si’s Tetgen algorithm¹⁸. Then a three-dimensional version of the 2D Delaunay algorithm described above is applied.
2. The “Frontal” algorithm uses J. Schoeberl’s Netgen algorithm ¹⁹.

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

6.2 Elementary vs. physical entities

If only elementary geometrical entities are defined (or if the Mesh.SaveAll option is set; see Mesh options list), the grid produced by the mesh module will be saved “as is”. That is, all the elements in the grid will be saved using the identification number of the elementary entities they discretize as their elementary region number (and 0 as their physical region number²⁰; File formats). This can sometimes be inconvenient:

• mesh elements cannot be duplicated;
• the orientation of the mesh elements (the ordering of their nodes) is determined entirely by the orientation of their “parent” elementary entities, and cannot be modified;
• elements belonging to different elementary entities cannot be linked as being part of a larger group having a physical or mathematical meaning (like ‘Left wing’, ‘Metallic part’, ‘Dirichlet boundary condition’, …).

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

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

In all cases, Gmsh reindexes the mesh vertices and elements so that they are numbered in a continuous sequence in the output files. Note that the numbers displayed on screen after mesh generation thus usually differ from the ones saved in the mesh files. To check the actual numbers saved in the output file just load the file back using ‘File->Open’.

6.3 Mesh commands

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

6.3.1 Specifying mesh element sizes

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

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

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

2. Second, if Mesh.CharacteristicLengthFromCurvature is set (it is not by default), the mesh will be adapted with respect to the curvature of the geometrical entities.
3. Finally, you can specify general mesh size “fields”. Various fields exist:
   • A PostView field specifies an explicit background mesh in the form of a scalar post-processing view (see Post-processing commands, and File formats) in which the nodal values are the target element sizes. This method is very general but it requires a first (usually rough) mesh and a way to compute the target sizes on this mesh (usually through an error estimation procedure, in an iterative process of mesh adaptation). Warning: only parsed (.pos) files can currently be used as background meshes (.msh files cannot be used, since the mesh used to define the field will be destroyed during the meshing process).

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

   • A Box field specifies the size of the elements inside and outside of a parallelepipedic region.
   • A Threshold field specifies the size of the mesh according to the distance to some geometrical entities. These entities can for example be geometry points and lines specified by an Attractor field.
   • A MathEval field specifies the size of the mesh using an explicit mathematical function.
   • A Min field specifies the size as the minimum of the sizes computed using other fields
   • …

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

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

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

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

Characteristic Length { expression-list } = expression;

Modify the prescribed mesh element size of the points whose identification numbers are listed in expression-list. The new value is given by expression.

Field[expression] = string;

Create a new field (with id number expression), of type string.

Field[expression].string = char-expression | expression | expression-list;

Set the option string of the expression-th field.

Background Field = expression;

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

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

Attractor

Compute the distance from the nearest node in a list. It can also be used to compute the distance from curves, in which case each curve is replaced by NNodesByEdge equidistant nodes and the distance from those nodes is computed.
Options:

EdgesList

Indices of curves in the geometric model
type: list
default value: {}

FacesList

Indices of surfaces in the geometric model (Warning, this feature is still experimental. It might (read: will probably) give wrong results for complex surfaces)
type: list
default value: {}

FieldX

Id of the field to use as x coordinate.
type: integer
default value: -1

FieldY

Id of the field to use as y coordinate.
type: integer
default value: -1

FieldZ

Id of the field to use as z coordinate.
type: integer
default value: -1

NNodesByEdge

Number of nodes used to discretized each curve
type: integer
default value: 20

NodesList

Indices of nodes in the geometric model
type: list
default value: {}

AttractorAnisoCurve

Compute the distance from the nearest curve in a list. Then the mesh size can be specified independently in the direction normal to the curve and in the direction parallel to the curve (Each curve is replaced by NNodesByEdge equidistant nodes and the distance from those nodes is computed.)
Options:

EdgesList

Indices of curves in the geometric model
type: list
default value: {}

NNodesByEdge

Number of nodes used to discretized each curve
type: integer
default value: 20

dMax

Maxmium distance, above this distance from the curves, prescribe the maximum mesh sizes.
type: float
default value: 0.5

dMin

Minimum distance, bellow this distance from the curves, prescribe the minimum mesh sizes.
type: float
default value: 0.1

lMaxNormal

Maximum mesh size in the direction normal to the closest curve.
type: float
default value: 0.5

lMaxTangent

Maximum mesh size in the direction tangeant to the closest curve.
type: float
default value: 0.5

lMinNormal

Minimum mesh size in the direction normal to the closest curve.
type: float
default value: 0.05

lMinTangent

Minimum mesh size in the direction tangeant to the closest curve.
type: float
default value: 0.5

Ball

The value of this field is VIn inside a spherical ball, VOut outside. The ball is defined by

||dX||^2 < R^2 &&
dX = (X - XC)^2 + (Y-YC)^2 + (Z-ZC)^2
Options:

Radius

Radius
type: float
default value: 0

VIn

Value inside the ball
type: float
default value: 0

VOut

Value outside the ball
type: float
default value: 0

XCenter

X coordinate of the ball center
type: float
default value: 0

YCenter

Y coordinate of the ball center
type: float
default value: 0

ZCenter

Z coordinate of the ball center
type: float
default value: 0

BoundaryLayer

hwall * ratio^(dist/hwall)
Options:

AnisoMax

Threshold angle for creating a mesh fan in the boundary layer
type: float
default value: 10000000000

EdgesList

Indices of curves in the geometric model for which a boundary layer is needed
type: list
default value: {}

FanNodesList

Indices of vertices in the geometric model for which a fan is created
type: list
default value: {}

IntersectMetrics

Intersect metrics of all faces
type: integer
default value: 0

NodesList

Indices of vertices in the geometric model for which a BL ends
type: list
default value: {}

Quads

Generate recombined elements in the boundary layer
type: integer
default value: 0

hfar

Element size far from the wall
type: float
default value: 1

hwall_n

Mesh Size Normal to the The Wall
type: float
default value: 0.1

hwall_n_nodes

Mesh Size Normal to the The Wall at nodes (overwrite hwall_n when defined)
type: list_double
default value: {}

ratio

Size Ratio Between Two Successive Layers
type: float
default value: 1.1

thickness

Maximal thickness of the boundary layer
type: float
default value: 0.01

Box

The value of this field is VIn inside the box, VOut outside the box. The box is given by

Xmin <= x <= XMax &&
YMin <= y <= YMax &&
ZMin <= z <= ZMax
Options:

VIn

Value inside the box
type: float
default value: 0

VOut

Value outside the box
type: float
default value: 0

XMax

Maximum X coordinate of the box
type: float
default value: 0

XMin

Minimum X coordinate of the box
type: float
default value: 0

YMax

Maximum Y coordinate of the box
type: float
default value: 0

YMin

Minimum Y coordinate of the box
type: float
default value: 0

ZMax

Maximum Z coordinate of the box
type: float
default value: 0

ZMin

Minimum Z coordinate of the box
type: float
default value: 0

Centerline

The value of this field is the distance to the centerline.

You should specify a fileName that contains the centerline. The centerline of a surface can be obtained with the open source software vmtk (http://www.vmtk.org/) using the following script:

vmtk vmtkcenterlines -seedselector openprofiles -ifile mysurface.stl -ofile centerlines.vtp –pipe vmtksurfacewriter -ifile centerlines.vtp -ofile centerlines.vtk

Options:

FileName

File name for the centerlines
type: string
default value: "centerlines.vtk"

closeVolume

Action: Create In/Outlet planar faces
type: integer
default value: 0

extrudeWall

Action: Extrude wall
type: integer
default value: 0

hLayer

Thickness (% of radius) of the extruded layer
type: float
default value: 0.3

hSecondLayer

Thickness (% of radius) of the second extruded layer
type: float
default value: 0.3

nbElemLayer

Number of mesh elements the extruded layer
type: integer
default value: 3

nbElemSecondLayer

Number of mesh elements the second extruded layer
type: integer
default value: 0

nbPoints

Number of mesh elements in a circle
type: integer
default value: 25

reMesh

Action: Cut the initial mesh in different mesh partitions using the centerlines
type: integer
default value: 0

Actions:

run

Run actions (closeVolume, extrudeWall, cutMesh)

Curvature

Compute the curvature of Field[IField]:

F = div(norm(grad(Field[IField])))
Options:

Delta

Step of the finite differences
type: float
default value: 0

IField

Field index
type: integer
default value: 1

Cylinder

The value of this field is VIn inside a frustrated cylinder, VOut outside. The cylinder is given by

||dX||^2 < R^2 &&
(X-X0).A < ||A||^2
dX = (X - X0) - ((X - X0).A)/(||A||^2) . A
Options:

Radius

Radius
type: float
default value: 0

VIn

Value inside the cylinder
type: float
default value: 0

VOut

Value outside the cylinder
type: float
default value: 0

XAxis

X component of the cylinder axis
type: float
default value: 0

XCenter

X coordinate of the cylinder center
type: float
default value: 0

YAxis

Y component of the cylinder axis
type: float
default value: 0

YCenter

Y coordinate of the cylinder center
type: float
default value: 0

ZAxis

Z component of the cylinder axis
type: float
default value: 1

ZCenter

Z coordinate of the cylinder center
type: float
default value: 0

ExternalProcess

**This Field is experimental**
Call an external process that received coordinates triple (x,y,z) as binary double precision numbers on stdin and is supposed to write the field value on stdout as a binary double precision number.
NaN,NaN,NaN is sent as coordinate to indicate the end of the process.

Example of client (python2):
import os
import struct
import math
import sys
if sys.platform == "win32" :
import msvcrt
msvcrt.setmode(0, os.O_BINARY)
msvcrt.setmode(1, os.O_BINARY)
while(True):
____xyz = struct.unpack("ddd", os.read(0,24))
____if math.isnan(xyz[0]):
_________break
____f = 0.001 + xyz[1]*0.009
____os.write(1,struct.pack("d",f))

Example of client (python3):
import struct
import sys
import math
while(True):
____xyz = struct.unpack("ddd", sys.stdin.buffer.read(24))
____if math.isnan(xyz[0]):
________break
____f = 0.001 + xyz[1]*0.009
____sys.stdout.buffer.write(struct.pack("d",f))
____sys.stdout.flush()

Example of client (c, unix):
#include <unistd.h>
int main(int argc, char **argv) {
__double xyz[3];
__while(read(STDIN_FILENO, &xyz, 3*sizeof(double)) == 3*sizeof(double)) {
____if (xyz[0] != xyz[0]) break; //nan
____double f = 0.001 + 0.009 * xyz[1];
____write(STDOUT_FILENO, &f, sizeof(double));
__}
__return 0;
}

Example of client (c, windows):
#include <stdio.h>
#include <io.h>
#include <fcntl.h>
int main(int argc, char **argv) {
__double xyz[3];
__setmode(fileno(stdin),O_BINARY);
__setmode(fileno(stdout),O_BINARY);
__while(read(fileno(stdin), &xyz, 3*sizeof(double)) == 3*sizeof(double)) {
____if (xyz[0] != xyz[0])
______break;
____double f = f = 0.01 + 0.09 * xyz[1];
____write(fileno(stdout), &f, sizeof(double));
__}
}

Options:

CommandLine

Command line to launch.
type: string
default value: ""

Frustum

This field is an extended cylinder with inner (i) and outer (o) radiuseson both endpoints (1 and 2). Length scale is bilinearly interpolated betweenthese locations (inner and outer radiuses, endpoints 1 and 2)The field values for a point P are given by : u = P1P.P1P2/||P1P2|| r = || P1P - u*P1P2 || Ri = (1-u)*R1i + u*R2i Ro = (1-u)*R1o + u*R2o v = (r-Ri)/(Ro-Ri) lc = (1-v)*( (1-u)*v1i + u*v2i ) + v*( (1-u)*v1o + u*v2o ) where (u,v) in [0,1]x[0,1]
Options:

R1_inner

Inner radius of Frustum at endpoint 1
type: float
default value: 0

R1_outer

Outer radius of Frustum at endpoint 1
type: float
default value: 1

R2_inner

Inner radius of Frustum at endpoint 2
type: float
default value: 0

R2_outer

Outer radius of Frustum at endpoint 2
type: float
default value: 1

V1_inner

Element size at point 1, inner radius
type: float
default value: 0.1

V1_outer

Element size at point 1, outer radius
type: float
default value: 1

V2_inner

Element size at point 2, inner radius
type: float
default value: 0.1

V2_outer

Element size at point 2, outer radius
type: float
default value: 1

X1

X coordinate of endpoint 1
type: float
default value: 0

X2

X coordinate of endpoint 2
type: float
default value: 0

Y1

Y coordinate of endpoint 1
type: float
default value: 0

Y2

Y coordinate of endpoint 2
type: float
default value: 0

Z1

Z coordinate of endpoint 1
type: float
default value: 1

Z2

Z coordinate of endpoint 2
type: float
default value: 2.53244204493764e-86

Gradient

Compute the finite difference gradient of Field[IField]:

F = (Field[IField](X + Delta/2) - Field[IField](X - Delta/2)) / Delta
Options:

Delta

Finite difference step
type: float
default value: 0

IField

Field index
type: integer
default value: 1

Kind

Component of the gradient to evaluate: 0 for X, 1 for Y, 2 for Z, 3 for the norm
type: integer
default value: 0

IntersectAniso

Take the intersection of 2 anisotropic fields according to Alauzet.
Options:

FieldsList

Field indices
type: list
default value: {}

Laplacian

Compute finite difference the Laplacian of Field[IField]:

F = G(x+d,y,z) + G(x-d,y,z) +
G(x,y+d,z) + G(x,y-d,z) +
G(x,y,z+d) + G(x,y,z-d) - 6 * G(x,y,z),

where G=Field[IField] and d=Delta
Options:

Delta

Finite difference step
type: float
default value: 0.1

IField

Field index
type: integer
default value: 1

LonLat

Evaluate Field[IField] in geographic coordinates (longitude, latitude):

F = Field[IField](atan(y/x), asin(z/sqrt(x^2+y^2+z^2))
Options:

FromStereo

if = 1, the mesh is in stereographic coordinates. xi = 2Rx/(R+z), eta = 2Ry/(R+z)
type: integer
default value: 0

IField

Index of the field to evaluate.
type: integer
default value: 1

RadiusStereo

radius of the sphere of the stereograpic coordinates
type: float
default value: 6371000

MathEval

Evaluate a mathematical expression. The expression can contain x, y, z for spatial coordinates, F0, F1, ... for field values, and and mathematical functions.
Options:

F

Mathematical function to evaluate.
type: string
default value: "F2 + Sin(z)"

MathEvalAniso

Evaluate a metric expression. The expressions can contain x, y, z for spatial coordinates, F0, F1, ... for field values, and and mathematical functions.
Options:

m11

element 11 of the metric tensor.
type: string
default value: "F2 + Sin(z)"

m12

element 12 of the metric tensor.
type: string
default value: "F2 + Sin(z)"

m13

element 13 of the metric tensor.
type: string
default value: "F2 + Sin(z)"

m22

element 22 of the metric tensor.
type: string
default value: "F2 + Sin(z)"

m23

element 23 of the metric tensor.
type: string
default value: "F2 + Sin(z)"

m33

element 33 of the metric tensor.
type: string
default value: "F2 + Sin(z)"

Max

Take the maximum value of a list of fields.
Options:

FieldsList

Field indices
type: list
default value: {}

MaxEigenHessian

Compute the maximum eigenvalue of the Hessian matrix of Field[IField], with the gradients evaluated by finite differences:

F = max(eig(grad(grad(Field[IField]))))
Options:

Delta

Step used for the finite differences
type: float
default value: 0

IField

Field index
type: integer
default value: 1

Mean

Simple smoother:

F = (G(x+delta,y,z) + G(x-delta,y,z) +
G(x,y+delta,z) + G(x,y-delta,z) +
G(x,y,z+delta) + G(x,y,z-delta) +
G(x,y,z)) / 7,

where G=Field[IField]
Options:

Delta

Distance used to compute the mean value
type: float
default value: 0.0001

IField

Field index
type: integer
default value: 0

Min

Take the minimum value of a list of fields.
Options:

FieldsList

Field indices
type: list
default value: {}

MinAniso

Take the intersection of a list of possibly anisotropic fields.
Options:

FieldsList

Field indices
type: list
default value: {}

Param

Evaluate Field IField in parametric coordinates:

F = Field[IField](FX,FY,FZ)

See the MathEval Field help to get a description of valid FX, FY and FZ expressions.
Options:

FX

X component of parametric function
type: string
default value: ""

FY

Y component of parametric function
type: string
default value: ""

FZ

Z component of parametric function
type: string
default value: ""

IField

Field index
type: integer
default value: 1

PostView

Evaluate the post processing view IView.
Options:

CropNegativeValues

return LC_MAX instead of a negative value (this option is needed for backward compatibility with the BackgroundMesh option
type: boolean
default value: 1

IView

Post-processing view index
type: integer
default value: 0

Restrict

Restrict the application of a field to a given list of geometrical points, curves, surfaces or volumes.
Options:

EdgesList

Curve indices
type: list
default value: {}

FacesList

Surface indices
type: list
default value: {}

IField

Field index
type: integer
default value: 1

RegionsList

Volume indices
type: list
default value: {}

VerticesList

Point indices
type: list
default value: {}

Structured

Linearly interpolate between data provided on a 3D rectangular structured grid.

The format of the input file is:

Ox Oy Oz
Dx Dy Dz
nx ny nz
v(0,0,0) v(0,0,1) v(0,0,2) ...
v(0,1,0) v(0,1,1) v(0,1,2) ...
v(0,2,0) v(0,2,1) v(0,2,2) ...
... ... ...
v(1,0,0) ... ...

where O are the coordinates of the first node, D are the distances between nodes in each direction, n are the numbers of nodes in each direction, and v are the values on each node.
Options:

FileName

Name of the input file
type: path
default value: ""

OutsideValue

Value of the field outside the grid (only used if the "SetOutsideValue" option is true).
type: float
default value: 0

SetOutsideValue

True to use the "OutsideValue" option. If False, the last values of the grid are used.
type: boolean
default value: 0

TextFormat

True for ASCII input files, false for binary files (4 bite signed integers for n, double precision floating points for v, D and O)
type: boolean
default value: 0

Threshold

F = LCMin if Field[IField] <= DistMin,
F = LCMax if Field[IField] >= DistMax,
F = interpolation between LcMin and LcMax if DistMin < Field[IField] < DistMax
Options:

DistMax

Distance from entity after which element size will be LcMax
type: float
default value: 10

DistMin

Distance from entity up to which element size will be LcMin
type: float
default value: 1

IField

Index of the field to evaluate
type: integer
default value: 0

LcMax

Element size outside DistMax
type: float
default value: 1

LcMin

Element size inside DistMin
type: float
default value: 0.1

Sigmoid

True to interpolate between LcMin and LcMax using a sigmoid, false to interpolate linearly
type: boolean
default value: 0

StopAtDistMax

True to not impose element size outside DistMax (i.e., F = a very big value if Field[IField] > DistMax)
type: boolean
default value: 0

6.3.2 Structured grids

Extrude { expression-list } { extrude-list layers }

Extrudes both the geometry and the mesh using a translation (see Extrusions). The layers option determines how the mesh is extruded and has the following syntax:

layers:

  Layers { expression } | 
  Layers { { expression-list }, { expression-list } } | 
  Recombine < expression >; …
  QuadTriNoNewVerts <RecombLaterals>; | 
  QuadTriAddVerts <RecombLaterals>; ...

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

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

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

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

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

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

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

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

QuadTriNoNewVerts and QuadTriAddVerts may be used interchangeably, but QuadTriAddVerts often gives better element quality.

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

Extrude { { expression-list }, { expression-list }, expression } { extrude-list layers }

Extrudes both the geometry and the mesh using a rotation (see Extrusions). The layers option is defined as above.

Extrude { { expression-list }, { expression-list }, { expression-list }, expression } { extrude-list layers }

Extrudes both the geometry and the mesh using a combined translation and rotation (see Extrusions). The layers option is defined as above.

Extrude { Surface { expression-list }; layers < Using Index[expr]; > < Using View[expr]; > < ScaleLastLayer; > }

Extrudes a boundary layer from the specified surfaces. If no view is specified, the boundary layer is created using gouraud-shaped (smoothed) normal field. Specifying a boundary layer index allows to extrude several independent boundary layers (with independent normal smoothing).

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

Transfinite Line { expression-list } | "*" = expression < Using Progression | Bump expression >;

Selects the lines in expression-list to be meshed with the 1D transfinite algorithm. The expression on the right hand side gives the number of nodes that will be created on the line (this overrides any other mesh element size prescription—see Specifying mesh element sizes). The optional argument ‘Using Progression expression’ instructs the transfinite algorithm to distribute the nodes following a geometric progression (Progression 2 meaning for example that each line element in the series will be twice as long as the preceding one). The optional argument ‘Using Bump expression’ instructs the transfinite algorithm to distribute the nodes with a refinement at both ends of the line.

Transfinite Surface { expression-list } | "*" < = { expression-list } > < Left | Right | Alternate | AlternateRight | AlternateLeft > ;

Selects surfaces to be meshed with the 2D transfinite algorithm. The expression-list on the right-hand-side should contain the identification numbers of three or four points on the boundary of the surface that define the corners of the transfinite interpolation. If no identification numbers are given, the transfinite algorithm will try to find the corners automatically. The optional argument specifies the way the triangles are oriented when the mesh is not recombined. (Alternate is a synonym for AlternateRight).

Transfinite Volume { expression-list } | "*" < = { expression-list } > ;

Selects five- or six-face volumes to be meshed with the 3D transfinite algorithm. The expression-list on the right-hand-side should contain the identification numbers of the six or eight points on the boundary of the volume that define the corners of the transfinite interpolation. If no identification numbers are given, the transfinite algorithm will try to find the corners automatically.

TransfQuadTri { expression-list } | "*";

Applies the transfinite QuadTri algorithm on the expression-list list of volumes ("*" can be used to apply TransfQuadTri to all existing volumes). A transfinite volume with any combination of recombined and un-recombined transfinite boundary surfaces is valid when meshed with TransfQuadTri. When applied to non-Transfinite volumes, TransfQuadTri has no effect on those volumes.

6.3.3 Miscellaneous

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

Mesh expression;

Generates expression-D mesh.

RefineMesh;

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

OptimizeMesh char-expression;

Optimizes the current mesh with the given algorithm (currently "Gmsh" or "Netgen").

AdaptMesh { expression-list } { expression-list } { { expression-list < , … > } };

Performs adaptive mesh generation. Documentation not yet available.

RelocateMesh Point | Line | Surface { expression-list } | "*";

Relocates the mesh vertices on the given entities using the parametric coordinates stored in the vertices. Useful for creating perturbation of meshes e.g. for sensitivity analyzes.

SetOrder expression;

Changes the order of the elements in the current mesh.

PartitionMesh expression;

Partitions the mesh into expression, using current partitioning options.

Point | Line { expression-list } In Surface { expression };

Embed the point(s) or line(s) in the given surface. The surface mesh will conform to the mesh of the point(s) or lines(s).

Surface { expression-list } In Volume { expression };

Embed the surface in the given volume. The volume mesh will conform to the mesh of the surface.

Periodic Line { expression-list } = { expression-list } ;

Force mesh of lines on the left-hand side (slaves) to match the mesh of the lines on the right-hand side (masters).

Periodic Surface expression { expression-list } = expression { expression-list } ;

Force mesh of the surface on the left-hand side (slave, with boundary edges specified between braces) to match the mesh of the surface on the right-hand side (master, with boundary edges specified between braces).

Periodic Line | Surface { expression-list } = { expression-list } Affine | Rotate | Translate { expression-list } ;

Force mesh of lines or surfaces on the left-hand side (slaves) to match the mesh of the lines on the right-hand side (masters), using prescribed geometrical transformations. Affine takes a 4 x 4 affine transform matrix given by row; Rotate and Translate are specified as in Transformations.

Coherence Mesh;

Removes all duplicate mesh vertices.

SetPartition expression { Point | Line | Surface | Volume { expression-list }; … }

Sets the partition tag of the mesh elements in the entities in expression-list to expression.

< Recursive > Color color-expression { Point | Line | Surface | Volume { expression-list }; … }

Sets the mesh color of the entities in expression-list to color-expression.

< Recursive > Hide { Point | Line | Surface | Volume { expression-list }; … }

Hides the mesh of the entities in expression-list, if General.VisibilityMode is set to 0 or 2.

Hide char-expression;

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

Recombine Surface { expression-list } | "*" < = expression >;

Recombines the triangular meshes of the surfaces listed in expression-list into mixed triangular/quadrangular meshes. The optional expression on the right hand side specifies the maximum difference (in degrees) allowed between the largest angle of a quadrangle and a right angle (a value of 0 would only accept quadrangles with right angles; a value of 90 would allow degenerate quadrangles; default value is 45).

MeshAlgorithm Surface { expression-list } = expression;

Forces the meshing algorithm per surface.

Reverse Line | Surface { expression-list } | "*" ;

Reverses the mesh of the given line(s) or surface(s).

Save char-expression;

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

< Recursive > Show { Point | Line | Surface | Volume { expression-list }; … }

Shows the mesh of the entities in expression-list, if General.VisibilityMode is set to 0 or 2.

Show char-expression;

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

Smoother Surface { expression-list } = expression;

Sets number of elliptic smoothing steps for the surfaces listed in expression-list (smoothing only applies to transfinite meshes at the moment).

Homology ( { expression-list } ) { { expression-list } , { expression-list } };

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

Cohomology ( { expression-list } ) { { expression-list } , { expression-list } };

Similar to command Homology, but computes a basis representation for cohomology spaces instead.

6.4 Mesh options

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

7 Solver module

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

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

7.1 Solver options

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

8 Post-processing module

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

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

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

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

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

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

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

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

8.1 Post-processing commands

Alias View[expression];

Creates an alias of the expression-th post-processing view.

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

AliasWithOptions View[expression];

Creates an alias of the expression-th post-processing view and copies all the options of the expression-th view to the new aliased view.

CopyOptions View[expression, expression];

Copy all the options from the first expression-th post-processing view to the second one.

Combine ElementsByViewName;

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

Combine ElementsFromAllViews | Combine Views;

Combines all the post-processing views into a single new view. The combination is done “spatially”, i.e., simply by appending the elements at the end of the new view.

Combine ElementsFromVisibleViews;

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

Combine TimeStepsByViewName | Combine TimeSteps;

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

Combine TimeStepsFromAllViews;

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

Combine TimeStepsFromVisibleViews;

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

Delete View[expression];

Deletes (removes) the expression-th post-processing view. Note that post-processing view numbers start at 0.

Delete Empty Views;

Deletes (removes) all the empty post-processing views.

Background Mesh View[expression];

Applies the expression-th post-processing view as the current background mesh. Note that post-processing view numbers start at 0.

Plugin (string) . Run;

Executes the plugin string. The list of default plugins is given in Post-processing plugins.

Plugin (string) . string = expression | char-expression;

Sets an option for a given plugin. See Post-processing plugins, for a list of default plugins and t9.geo, for some examples.

Save View[expression] char-expression;

Saves the the expression-th post-processing view in a file named char-expression. If the path in char-expression is not absolute, char-expression is appended to the path of the current file.

View "string" { string < ( expression-list ) > { expression-list }; … };

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

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

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

View "string" {
  type ( list-of-coords ) { list-of-values }; …
  < TIME { expression-list }; >
  < INTERPOLATION_SCHEME { val-coef-matrix } { val-exp-matrix }
                  < { geo-coef-matrix } { geo-exp-matrix } > ; >
};

where the 47 object types that can be displayed are:

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

The coordinates are given ‘by node’, i.e.,

• (coord1, coord2, coord3) for a point,
• (coord1-node1, coord2-node1, coord3-node1,
coord1-node2, coord2-node2, coord3-node2) for a line,
• (coord1-node1, coord2-node1, coord3-node1,
coord1-node2, coord2-node2, coord3-node2,
coord1-node3, coord2-node3, coord3-node3) for a triangle,
• etc.

The ordering of the nodes is given in Node ordering.

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

comp1-node1-time1, comp2-node1-time1, comp3-node1-time1,
comp1-node2-time1, comp2-node2-time1, comp3-node2-time1,
comp1-node3-time1, comp2-node3-time1, comp3-node3-time1,
comp1-node1-time2, comp2-node1-time2, comp3-node1-time2,
comp1-node2-time2, comp2-node2-time2, comp3-node2-time2,
comp1-node3-time2, comp2-node3-time2, comp3-node3-time2,
…

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

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

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

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

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

Let us assume that the approximation of the view’s value over an element is written as a linear combination of d basis functions f[i], i=0, ..., d-1 (the coefficients being stored in list-of-values). Defining f[i] = Sum(j=0, ..., d-1) F[i][j] p[j], with p[j] = u^P[j][0] v^P[j][1] w^P[j][2] (u, v and w being the coordinates in the element’s parameter space), then val-coef-matrix denotes the d x d matrix F and val-exp-matrix denotes the d x 3 matrix P.

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

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

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

8.2 Post-processing plugins

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

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

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

Plugin(AnalyseCurvedMesh)

Plugin(AnalyseCurvedMesh) analyse all elements of a given dimension. According to what is asked, it computes the minimum of the Jacobian determinant (J), of the scaled Jacobian and/or of the isotropy measure. Statistics are printed and if asked a Pview is created for each measure. The plugin hides elements for which the measure mu > ’Hidding threshold’, where mu is the isotropy measure if asked otherwise the scaled Jacobian if asked otherwise the Jacobian determinant.

J is faster to compute but gives informations only on validity while the other measure gives also informations on quality.
Warning: the scaled Jacobian is experimental for triangles, tetrahedra, prisms and pyramids. Computation may take a lot of time for those elements!

Parameters:

- Jacobian determinant = {0, 1}
- Scaled Jacobian = {0, 1}
- Isotropy = {0, 1}

- Hidding threshold = [0, 1]: Does nothing if Isotropy == 0 and Scaled Jacobian == 0. Otherwise, hides all element for which min(mu) is strictly greater than the threshold, where mu is the isotropy if Isotropy == 1, otherwise it is the Scaled Jacobian. If threshold == 1, no effect, if == 0 hide all elements except invalid.

- Draw PView = {0, 1}: Creates a PView of min(J)/max(J), min(scaled Jac) and/or min(isotropy) according to what is asked. If ’Recompute’ = 1, a new PView is redrawed.

- Recompute = {0,1}: If the mesh has changed, set to 1 to recompute the bounds.

- Dimension = {-1, 1, 2, 3, 4}: If == -1, analyse element of the greater dimension. If == 4, analyse 2D and 3D elements. Numeric options:

Jacobian determinant

Default value: 1

Scaled Jacobian

Default value: 0

Isotropy

Default value: 1

Hidding threshold

Default value: 9

Draw PView

Default value: 0

Recompute

Default value: 0

Dimension of elements

Default value: -1

Plugin(Annotate)

Plugin(Annotate) adds the text string ‘Text’, in font ‘Font’ and size ‘FontSize’, in the view ‘View’. The string is aligned according to ‘Align’.

If ‘ThreeD’ is equal to 1, the plugin inserts the string in model coordinates at the position (‘X’,‘Y’,‘Z’). If ‘ThreeD’ is equal to 0, the plugin inserts the string in screen coordinates at the position (‘X’,‘Y’).

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Annotate) is executed in-place for list-based datasets or creates a new view for other datasets. String options:

Text

Default value: "My Text"

Font

Default value: "Helvetica"

Align

Default value: "Left"

Numeric options:

X

Default value: 50

Y

Default value: 30

Z

Default value: 0

ThreeD

Default value: 0

FontSize

Default value: 14

View

Default value: -1

Plugin(Bubbles)

Plugin(Bubbles) constructs a geometry consisting of ‘bubbles’ inscribed in the Voronoi of an input triangulation. ‘ShrinkFactor’ allows to change the size of the bubbles. The plugin expects a triangulation in the ‘z = 0’ plane to exist in the current model.

Plugin(Bubbles) creates one ‘.geo’ file. String options:

OutputFile

Default value: "bubbles.geo"

Numeric options:

ShrinkFactor

Default value: 0

Plugin(Crack)

Plugin(Crack) creates a crack around the physical group ‘PhysicalGroup’ of dimension ‘Dimension’ (1 or 2), embedded in a mesh of dimension ‘Dimension’ + 1. The plugin duplicates the vertices and the elements on the crack and stores them in a new discrete curve (‘Dimension’ = 1) or surface (‘Dimension’ = 2). The elements touching the crack on the “negative” side are modified to use the newly generated vertices.If ‘OpenBoundaryPhysicalGroup’ is given (> 0), its vertices are duplicated and the crack will be left open on that (part of the) boundary. Otherwise, the lips of the crack are sealed, i.e., its vertices are not duplicated. For 1D cracks, ‘NormalX’, ‘NormalY’ and ‘NormalZ’ provide the reference normal of the surface in which the crack is supposed to be embedded. Numeric options:

Dimension

Default value: 1

PhysicalGroup

Default value: 1

OpenBoundaryPhysicalGroup

Default value: 0

NormalX

Default value: 0

NormalY

Default value: 0

NormalZ

Default value: 1

Plugin(Curl)

Plugin(Curl) computes the curl of the field in the view ‘View’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Curl) creates one new view. Numeric options:

View

Default value: -1

Plugin(CurvedBndDist)

Plugin(CurvedBndDist) ...

Plugin(CutBox)

Plugin(CutBox) cuts the view ‘View’ with a rectangular box defined by the 4 points (‘X0’,‘Y0’,‘Z0’) (origin), (‘X1’,‘Y1’,‘Z1’) (axis of U), (‘X2’,‘Y2’,‘Z2’) (axis of V) and (‘X3’,‘Y3’,‘Z3’) (axis of W).

The number of points along U, V, W is set with the options ‘NumPointsU’, ‘NumPointsV’ and ‘NumPointsW’.

If ‘ConnectPoints’ is zero, the plugin creates points; otherwise, the plugin generates hexahedra, quadrangles, lines or points depending on the values of ‘NumPointsU’, ‘NumPointsV’ and ‘NumPointsW’.

If ‘Boundary’ is zero, the plugin interpolates the view inside the box; otherwise the plugin interpolates the view at its boundary.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(CutBox) creates one new view. Numeric options:

X0

Default value: 0

Y0

Default value: 0

Z0

Default value: 0

X1

Default value: 1

Y1

Default value: 0

Z1

Default value: 0

X2

Default value: 0

Y2

Default value: 1

Z2

Default value: 0

X3

Default value: 0

Y3

Default value: 0

Z3

Default value: 1

NumPointsU

Default value: 20

NumPointsV

Default value: 20

NumPointsW

Default value: 20

ConnectPoints

Default value: 1

Boundary

Default value: 1

View

Default value: -1

Plugin(CutGrid)

Plugin(CutGrid) cuts the view ‘View’ with a rectangular grid defined by the 3 points (‘X0’,‘Y0’,‘Z0’) (origin), (‘X1’,‘Y1’,‘Z1’) (axis of U) and (‘X2’,‘Y2’,‘Z2’) (axis of V).

The number of points along U and V is set with the options ‘NumPointsU’ and ‘NumPointsV’.

If ‘ConnectPoints’ is zero, the plugin creates points; otherwise, the plugin generates quadrangles, lines or points depending on the values of ‘NumPointsU’ and ‘NumPointsV’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(CutGrid) creates one new view. Numeric options:

X0

Default value: 0

Y0

Default value: 0

Z0

Default value: 0

X1

Default value: 1

Y1

Default value: 0

Z1

Default value: 0

X2

Default value: 0

Y2

Default value: 1

Z2

Default value: 0

NumPointsU

Default value: 20

NumPointsV

Default value: 20

ConnectPoints

Default value: 1

View

Default value: -1

Plugin(CutParametric)

Plugin(CutParametric) cuts the view ‘View’ with the parametric function (‘X’(u,v), ‘Y’(u,v), ‘Z’(u,v)), using ‘NumPointsU’ values of the parameter u in [‘MinU’, ‘MaxU’] and ‘NumPointsV’ values of the parameter v in [‘MinV’, ‘MaxV’].

If ‘ConnectPoints’ is set, the plugin creates surface or line elements; otherwise, the plugin generates points.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(CutParametric) creates one new view. String options:

X

Default value: "2 * Cos(u) * Sin(v)"

Y

Default value: "4 * Sin(u) * Sin(v)"

Z

Default value: "0.1 + 0.5 * Cos(v)"

Numeric options:

MinU

Default value: 0

MaxU

Default value: 6.2832

NumPointsU

Default value: 180

MinV

Default value: 0

MaxV

Default value: 6.2832

NumPointsV

Default value: 180

ConnectPoints

Default value: 0

View

Default value: -1

Plugin(CutPlane)

Plugin(CutPlane) cuts the view ‘View’ with the plane ‘A’*X + ‘B’*Y + ‘C’*Z + ‘D’ = 0.

If ‘ExtractVolume’ is nonzero, the plugin extracts the elements on one side of the plane (depending on the sign of ‘ExtractVolume’).

If ‘View’ < 0, the plugin is run on the current view.

Plugin(CutPlane) creates one new view. Numeric options:

A

Default value: 1

B

Default value: 0

C

Default value: 0

D

Default value: -0.01

ExtractVolume

Default value: 0

RecurLevel

Default value: 4

TargetError

Default value: 0

View

Default value: -1

Plugin(CutSphere)

Plugin(CutSphere) cuts the view ‘View’ with the sphere (X-‘Xc’)^2 + (Y-‘Yc’)^2 + (Z-‘Zc’)^2 = ‘R’^2.

If ‘ExtractVolume’ is nonzero, the plugin extracts the elements inside (if ‘ExtractVolume’ < 0) or outside (if ‘ExtractVolume’ > 0) the sphere.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(CutSphere) creates one new view. Numeric options:

Xc

Default value: 0

Yc

Default value: 0

Zc

Default value: 0

R

Default value: 0.25

ExtractVolume

Default value: 0

RecurLevel

Default value: 4

TargetError

Default value: 0

View

Default value: -1

Plugin(DiscretizationError)

Plugin(DiscretizationError) computes the error between the mesh and the geometry. It does so by supersampling the elements and computing the distance between the supersampled points dans their projection on the geometry. Numeric options:

SuperSamplingNodes

Default value: 10

Plugin(Distance)

Plugin(Distance) computes distances to physical entities in a mesh.

Define the physical entities to which the distance is computed. If Point=0, Line=0, and Surface=0, then the distance is computed to all the boundaries of the mesh (edges in 2D and faces in 3D).

Computation<0. computes the geometrical euclidian distance (warning: different than the geodesic distance), and Computation=a>0.0 solves a PDE on the mesh with the diffusion constant mu = a*bbox, with bbox being the max size of the bounding box of the mesh (see paper Legrand 2006).

Min Scale and max Scale, scale the distance function. If min Scale<0 and max Scale<0, then no scaling is applied to the distance function.

Plugin(Distance) creates a new distance view and also saves the view in the fileName.pos file. String options:

Filename

Default value: "distance.pos"

Numeric options:

PhysPoint

Default value: 0

PhysLine

Default value: 0

PhysSurface

Default value: 0

Computation

Default value: -1

MinScale

Default value: -1

MaxScale

Default value: -1

Orthogonal

Default value: -1

Plugin(Divergence)

Plugin(Divergence) computes the divergence of the field in the view ‘View’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Divergence) creates one new view. Numeric options:

View

Default value: -1

Plugin(DuplicateBoundaries)

Plugin(DuplicateBoundaries) is not documented yet. Numeric options:

Dummy

Default value: 1

Plugin(Eigenvalues)

Plugin(Eigenvalues) computes the three real eigenvalues of each tensor in the view ‘View’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Eigenvalues) creates three new scalar views. Numeric options:

View

Default value: -1

Plugin(Eigenvectors)

Plugin(Eigenvectors) computes the three (right) eigenvectors of each tensor in the view ‘View’ and sorts them according to the value of the associated eigenvalues.

If ‘ScaleByEigenvalues’ is set, each eigenvector is scaled by its associated eigenvalue. The plugin gives an error if the eigenvectors are complex.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Eigenvectors) creates three new vector view. Numeric options:

ScaleByEigenvalues

Default value: 1

View

Default value: -1

Plugin(ExtractEdges)

Plugin(ExtractEdges) extracts sharp edges from a triangular mesh.

Plugin(ExtractEdges) creates one new view. Numeric options:

Angle

Default value: 40

IncludeBoundary

Default value: 1

Plugin(ExtractElements)

Plugin(ExtractElements) extracts some elements from the view ‘View’. If ‘MinVal’ != ‘MaxVal’, it extracts the elements whose ‘TimeStep’-th values (averaged by element) are comprised between ‘MinVal’ and ‘MaxVal’. If ‘Visible’ != 0, it extracts visible elements.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(ExtractElements) creates one new view. Numeric options:

MinVal

Default value: 0

MaxVal

Default value: 0

TimeStep

Default value: 0

Visible

Default value: 1

Dimension

Default value: -1

View

Default value: -1

Plugin(FaultZone)

Plugin(FaultZone) convert all the embedded lines of an existing surfacic mesh to flat quadrangles. Flat quadrangles represent joint elements suitable to model a fault zone with Code_Aster.

‘SurfaceTag’ must be an existing plane surface containing embedded lines. Embedded lines must have been added to the surface via the command Line In Surface. The surface must be meshed with quadratic incomplete elements.

‘Thickness’ is the thichness of the flat quadrangles. Set a value different to zero can be helpfull to check the connectivity.

‘Prefix’ is the prefix of the name of physicals containing the new embedded. All physicals containing embedded lines are replaced by physicals containing the coresponding joint elements. String options:

Prefix

Default value: "FAMI_"

Numeric options:

SurfaceTag

Default value: 1

Thickness

Default value: 0

Plugin(FieldFromAmplitudePhase)

Plugin(FieldFromAmplitudePhase) builds a complex field ’u’ from amplitude ’a’ (complex) and phase ’phi’ given in two different ’Views’ u = a * exp(k*phi), with k the wavenumber.

The result is to be interpolated in a sufficiently fine mesh: ’MeshFile’.

Plugin(FieldFromAmplitudePhase) generates one new view. String options:

MeshFile

Default value: "fine.msh"

Numeric options:

Wavenumber

Default value: 5

AmplitudeView

Default value: 0

PhaseView

Default value: 1

Plugin(Gradient)

Plugin(Gradient) computes the gradient of the field in the view ‘View’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Gradient) creates one new view. Numeric options:

View

Default value: -1

Plugin(HarmonicToTime)

Plugin(HarmonicToTime) takes the values in the time steps ‘RealPart’ and ‘ImaginaryPart’ of the view ‘View’, and creates a new view containing

‘View’[‘RealPart’] * cos(p) +- ‘View’[‘ImaginaryPart’] * sin(p)

with p = 2*Pi*k/‘NumSteps’, k = 0, ..., ‘NumSteps’-1.
The + or - sign is controlled by ‘TimeSign’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(HarmonicToTime) creates one new view. Numeric options:

RealPart

Default value: 0

ImaginaryPart

Default value: 1

NumSteps

Default value: 20

TimeSign

Default value: -1

View

Default value: -1

Plugin(HomologyComputation)

Plugin(HomologyComputation) computes representative chains of basis elements of (relative) homology and cohomology spaces.

Define physical groups in order to specify the computation domain and the relative subdomain. Otherwise the whole mesh is the domain and the relative subdomain is empty.

Plugin(HomologyComputation) creates new views, one for each basis element. The resulting basis chains of desired dimension together with the mesh are saved to the given file. String options:

DomainPhysicalGroups

Default value: ""

SubdomainPhysicalGroups

Default value: ""

ReductionImmunePhysicalGroups

Default value: ""

DimensionOfChainsToSave

Default value: "0, 1, 2, 3"

Filename

Default value: "homology.msh"

Numeric options:

ComputeHomology

Default value: 1

ComputeCohomology

Default value: 0

HomologyPhysicalGroupsBegin

Default value: -1

CohomologyPhysicalGroupsBegin

Default value: -1

CreatePostProcessingViews

Default value: 1

ReductionOmit

Default value: 1

ReductionCombine

Default value: 3

PostProcessSimplify

Default value: 1

ReductionHeuristic

Default value: 1

Plugin(HomologyPostProcessing)

Plugin(HomologyPostProcessing) operates on representative basis chains of homology and cohomology spaces. Functionality:

1. (co)homology basis transformation:
’TransformationMatrix’: Integer matrix of the transformation.
’PhysicalGroupsOfOperatedChains’: (Co)chains of a (co)homology space basis to be transformed.
Results a new (co)chain basis that is an integer cobination of the given basis.

2. Make basis representations of a homology space and a cohomology space compatible:
’PhysicalGroupsOfOperatedChains’: Chains of a homology space basis.
’PhysicalGroupsOfOperatedChains2’: Cochains of a cohomology space basis.
Results a new basis for the homology space such that the incidence matrix of the new basis and the basis of the cohomology space is the identity matrix.

Options:
’PhysicalGroupsToTraceResults’: Trace the resulting (co)chains to the given physical groups.
’PhysicalGroupsToProjectResults’: Project the resulting (co)chains to the complement of the given physical groups.
’NameForResultChains’: Post-processing view name prefix for the results.
’ApplyBoundaryOperatorToResults’: Apply boundary operator to the resulting chains.

String options:

TransformationMatrix

Default value: "1, 0; 0, 1"

PhysicalGroupsOfOperatedChains

Default value: "1, 2"

PhysicalGroupsOfOperatedChains2

Default value: ""

PhysicalGroupsToTraceResults

Default value: ""

PhysicalGroupsToProjectResults

Default value: ""

NameForResultChains

Default value: "c"

Numeric options:

ApplyBoundaryOperatorToResults

Default value: 0

Plugin(Integrate)

Plugin(Integrate) integrates a scalar field over all the elements of the view ‘View’ (if ‘Dimension’ < 0), or over all elements of the prescribed dimension (if ‘Dimension’ > 0). If the field is a vector field,the circulation/flux of the field over line/surface elements is calculated.

If ‘View’ < 0, the plugin is run on the current view.

If ‘OverTime’ = i > -1 , the plugin integrates the scalar view over time instead of over space, starting at iteration i.If ‘Visible’ = 1, the plugin only integrates overvisible entities.

Plugin(Integrate) creates one new view. Numeric options:

View

Default value: -1

OverTime

Default value: -1

Dimension

Default value: -1

Visible

Default value: 1

Plugin(Isosurface)

Plugin(Isosurface) extracts the isosurface of value ‘Value’ from the view ‘View’, and draws the ‘OtherTimeStep’-th step of the view ‘OtherView’ on this isosurface.

If ‘ExtractVolume’ is nonzero, the plugin extracts the isovolume with values greater (if ‘ExtractVolume’ > 0) or smaller (if ‘ExtractVolume’ < 0) than the isosurface ‘Value’.

If ‘OtherTimeStep’ < 0, the plugin uses, for each time step in ‘View’, the corresponding time step in ‘OtherView’. If ‘OtherView’ < 0, the plugin uses ‘View’ as the value source.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Isosurface) creates as many views as there are time steps in ‘View’. Numeric options:

Value

Default value: 0

ExtractVolume

Default value: 0

RecurLevel

Default value: 4

TargetError

Default value: 0

View

Default value: -1

OtherTimeStep

Default value: -1

OtherView

Default value: -1

Plugin(Lambda2)

Plugin(Lambda2) computes the eigenvalues Lambda(1,2,3) of the tensor (S_ik S_kj + Om_ik Om_kj), where S_ij = 0.5 (ui,j + uj,i) and Om_ij = 0.5 (ui,j - uj,i) are respectively the symmetric and antisymmetric parts of the velocity gradient tensor.

Vortices are well represented by regions where Lambda(2) is negative.

If ‘View’ contains tensor elements, the plugin directly uses the tensors as the values of the velocity gradient tensor; if ‘View’ contains vector elements, the plugin uses them as the velocities from which to derive the velocity gradient tensor.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Lambda2) creates one new view. Numeric options:

Eigenvalue

Default value: 2

View

Default value: -1

Plugin(LongitudeLatitude)

Plugin(LongituteLatitude) projects the view ‘View’ in longitude-latitude.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(LongituteLatitude) is executed in place. Numeric options:

View

Default value: -1

Plugin(MakeSimplex)

Plugin(MakeSimplex) decomposes all non-simplectic elements (quadrangles, prisms, hexahedra, pyramids) in the view ‘View’ into simplices (triangles, tetrahedra).

If ‘View’ < 0, the plugin is run on the current view.

Plugin(MakeSimplex) is executed in-place. Numeric options:

View

Default value: -1

Plugin(MathEval)

Plugin(MathEval) creates a new view using data from the time step ‘TimeStep’ in the view ‘View’.

If only ‘Expression0’ is given (and ‘Expression1’, ..., ‘Expression8’ are all empty), the plugin creates a scalar view. If ‘Expression0’, ‘Expression1’ and/or ‘Expression2’ are given (and ‘Expression3’, ..., ‘Expression8’ are all empty) the plugin creates a vector view. Otherwise the plugin creates a tensor view.

In addition to the usual mathematical functions (Exp, Log, Sqrt, Sin, Cos, Fabs, etc.) and operators (+, -, *, /, ^), all expressions can contain:

- the symbols v0, v1, v2, ..., vn, which represent the n components in ‘View’;

- the symbols w0, w1, w2, ..., wn, which represent the n components of ‘OtherView’, at time step ‘OtherTimeStep’;

- the symbols x, y and z, which represent the three spatial coordinates.

If ‘TimeStep’ < 0, the plugin extracts data from all the time steps in the view.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(MathEval) creates one new view.If ‘PhysicalRegion’ < 0, the plugin is run on all physical regions.

Plugin(MathEval) creates one new view. String options:

Expression0

Default value: "Sqrt(v0^2+v1^2+v2^2)"

Expression1

Default value: ""

Expression2

Default value: ""

Expression3

Default value: ""

Expression4

Default value: ""

Expression5

Default value: ""

Expression6

Default value: ""

Expression7

Default value: ""

Expression8

Default value: ""

Numeric options:

TimeStep

Default value: -1

View

Default value: -1

OtherTimeStep

Default value: -1

OtherView

Default value: -1

ForceInterpolation

Default value: 0

PhysicalRegion

Default value: -1

Plugin(MeshSubEntities)

Plugin(MeshSubEntities) creates mesh elements for the entities of dimension ‘OutputDimension’ (0 for vertices, 1 for edges, 2 for faces) of the ‘InputPhysicalGroup’ of dimension ‘InputDimension’. The plugin creates new elements belonging to ‘OutputPhysicalGroup’. Numeric options:

InputDimension

Default value: 1

InputPhysicalGroup

Default value: 1

OuputDimension

Default value: 0

OuputPhysicalGroup

Default value: 2000

Plugin(MinMax)

Plugin(MinMax) computes the min/max of a view.

If ‘View’ < 0, the plugin is run on the current view. If ‘OverTime’ = 1, the plugin calculates the min/max over space and time. If ‘Argument’ = 1, the plugin calculates the min/max and the argmin/argmax. If ‘Visible’ = 1, the plugin is only applied to visible entities.

Plugin(MinMax) creates two new views. Numeric options:

View

Default value: -1

OverTime

Default value: 0

Argument

Default value: 0

Visible

Default value: 1

Plugin(ModifyComponents)

Plugin(ModifyComponents) modifies the components of the ‘TimeStep’-th time step in the view ‘View’, using the expressions provided in ‘Expression0’, ..., ‘Expression8’. If an expression is empty, the corresponding component in the view is not modified.

The expressions can contain:

- the usual mathematical functions (Log, Sqrt, Sin, Cos, Fabs, ...) and operators (+, -, *, /, ^);

- the symbols x, y and z, to retrieve the coordinates of the current node;

- the symbols Time and TimeStep, to retrieve the current time and time step values;

- the symbols v0, v1, v2, ..., v8, to retrieve each component of the field in ‘View’ at the ‘TimeStep’-th time step;

- the symbols w0, w1, w2, ..., w8, to retrieve each component of the field in ‘OtherView’ at the ‘OtherTimeStep’-th time step. If ‘OtherView’ and ‘View’ are based on different spatial grids, or if their data types are different, ‘OtherView’ is interpolated onto ‘View’.

If ‘TimeStep’ < 0, the plugin automatically loops over all the time steps in ‘View’ and evaluates the expressions for each one.

If ‘OtherTimeStep’ < 0, the plugin uses ‘TimeStep’ instead.

If ‘View’ < 0, the plugin is run on the current view.

If ‘OtherView’ < 0, the plugin uses ‘View’ instead.

Plugin(ModifyComponents) is executed in-place. String options:

Expression0

Default value: "v0 * Sin(x)"

Expression1

Default value: ""

Expression2

Default value: ""

Expression3

Default value: ""

Expression4

Default value: ""

Expression5

Default value: ""

Expression6

Default value: ""

Expression7

Default value: ""

Expression8

Default value: ""

Numeric options:

TimeStep

Default value: -1

View

Default value: -1

OtherTimeStep

Default value: -1

OtherView

Default value: -1

ForceInterpolation

Default value: 0

Plugin(ModulusPhase)

Plugin(ModulusPhase) interprets the time steps ‘realPart’ and ‘imaginaryPart’ in the view ‘View’ as the real and imaginary parts of a complex field and replaces them with their corresponding modulus and phase.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(ModulusPhase) is executed in-place. Numeric options:

RealPart

Default value: 0

ImaginaryPart

Default value: 1

View

Default value: -1

Plugin(NearToFarField)

Plugin(NearToFarField) computes the far field pattern from the near electric E and magnetic H fields on a surface enclosing the radiating device (antenna).

Parameters: the wavenumber, the angular discretisation (phi in [0, 2*Pi] and theta in [0, Pi]) of the far field sphere and the indices of the views containing the complex-valued E and H fields. If ‘Normalize’ is set, the far field is normalized to 1. If ‘dB’ is set, the far field is computed in dB. If ‘NegativeTime’ is set, E and H are assumed to have exp(-iwt) time dependency; otherwise they are assume to have exp(+iwt) time dependency. If ‘MatlabOutputFile’ is given the raw far field data is also exported in Matlab format.

Plugin(NearToFarField) creates one new view. String options:

MatlabOutputFile

Default value: "farfield.m"

Numeric options:

Wavenumber

Default value: 1

PhiStart

Default value: 0

PhiEnd

Default value: 6.28319

NumPointsPhi

Default value: 60

ThetaStart

Default value: 0

ThetaEnd

Default value: 3.14159

NumPointsTheta

Default value: 30

EView

Default value: 0

HView

Default value: 1

Normalize

Default value: 1

dB

Default value: 1

NegativeTime

Default value: 0

RFar

Default value: 0

Plugin(NearestNeighbor)

Plugin(NearestNeighbor) computes the distance from each point in ‘View’ to its nearest neighbor.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(NearestNeighbor) is executed in-place. Numeric options:

View

Default value: -1

Plugin(NewView)

Plugin(NewView) creates a new view from a mesh.The parameter ‘Dimension’ gives the dimensionof the initialized to zero NodeData vector Numeric options:

View

Default value: -1

Dimension

Default value: 1

Plugin(Particles)

Plugin(Particles) computes the trajectory of particules in the force field given by the ‘TimeStep’-th time step of a vector view ‘View’.

The plugin takes as input a grid defined by the 3 points (‘X0’,‘Y0’,‘Z0’) (origin), (‘X1’,‘Y1’,‘Z1’) (axis of U) and (‘X2’,‘Y2’,‘Z2’) (axis of V).

The number of particles along U and V that are to be transported is set with the options ‘NumPointsU’ and ‘NumPointsV’. The equation

A2 * d^2X(t)/dt^2 + A1 * dX(t)/dt + A0 * X(t) = F

is then solved with the initial conditions X(t=0) chosen as the grid, dX/dt(t=0)=0, and with F interpolated from the vector view.

Time stepping is done using a Newmark scheme with step size ‘DT’ and ‘MaxIter’ maximum number of iterations.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Particles) creates one new view containing multi-step vector points. Numeric options:

X0

Default value: 0

Y0

Default value: 0

Z0

Default value: 0

X1

Default value: 1

Y1

Default value: 0

Z1

Default value: 0

X2

Default value: 0

Y2

Default value: 1

Z2

Default value: 0

NumPointsU

Default value: 10

NumPointsV

Default value: 1

A2

Default value: 1

A1

Default value: 0

A0

Default value: 0

DT

Default value: 0.1

MaxIter

Default value: 100

TimeStep

Default value: 0

View

Default value: -1

Plugin(Probe)

Plugin(Probe) gets the value of the view ‘View’ at the point (‘X’,‘Y’,‘Z’).

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Probe) creates one new view. Numeric options:

X

Default value: 0

Y

Default value: 0

Z

Default value: 0

View

Default value: -1

Plugin(Remove)

Plugin(Remove) removes the marked items from the view ‘View’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Remove) is executed in-place. Numeric options:

Text2D

Default value: 1

Text3D

Default value: 1

Points

Default value: 0

Lines

Default value: 0

Triangles

Default value: 0

Quadrangles

Default value: 0

Tetrahedra

Default value: 0

Hexahedra

Default value: 0

Prisms

Default value: 0

Pyramids

Default value: 0

Scalar

Default value: 1

Vector

Default value: 1

Tensor

Default value: 1

View

Default value: -1

Plugin(Scal2Tens)

Plugin(Scal2Tens) converts some scalar fields into a tensor field. The number of components must be given (max. 9). The new view ’NameNewView’ contains the new tensor field. If the number of a view is -1, the value of the corresponding component is 0. String options:

NameNewView

Default value: "NewView"

Numeric options:

NumberOfComponents

Default value: 9

View0

Default value: -1

View1

Default value: -1

View2

Default value: -1

View3

Default value: -1

View4

Default value: -1

View5

Default value: -1

View6

Default value: -1

View7

Default value: -1

View8

Default value: -1

Plugin(Scal2Vec)

Plugin(Scal2Vec) converts the scalar fields into a vectorial field. The new view ’NameNewView’ contains it. If the number of a view is -1, the value of the corresponding component of the vector field is 0. String options:

NameNewView

Default value: "NewView"

Numeric options:

ViewX

Default value: -1

ViewY

Default value: -1

ViewZ

Default value: -1

Plugin(ShowNeighborElements)

Plugin(ShowNeighborElements) allows to set visible some given elements and a layer of elements around them, the other being set invisible. Numeric options:

NumLayers

Default value: 1

Element1

Default value: 0

Element2

Default value: 0

Element3

Default value: 0

Element4

Default value: 0

Element5

Default value: 0

Plugin(SimplePartition)

Plugin(SimplePartition) partitions the current mesh into ‘NumSlices’ slices, along the X-, Y- or Z-axis depending on the value of ‘Direction’ (0,1,2). The plugin creates partition boundaries if ‘CreateBoundaries’ is set. String options:

Mapping

Default value: "t"

Numeric options:

NumSlices

Default value: 4

Direction

Default value: 0

CreateBoundaries

Default value: 1

Plugin(Skin)

Plugin(Skin) extracts the boundary (skin) of the current mesh (if ‘FromMesh’ = 1), or from the the view ‘View’ (in which case it creates a new view). If ‘View’ < 0 and ‘FromMesh’ = 0, the plugin is run on the current view.
If ‘Visible’ is set, the plugin only extracts the skin of visible entities. Numeric options:

Visible

Default value: 1

FromMesh

Default value: 0

View

Default value: -1

Plugin(Smooth)

Plugin(Smooth) averages the values at the nodes of the view ‘View’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Smooth) is executed in-place. Numeric options:

View

Default value: -1

Plugin(SphericalRaise)

Plugin(SphericalRaise) transforms the coordinates of the elements in the view ‘View’ using the values associated with the ‘TimeStep’-th time step.

Instead of elevating the nodes along the X, Y and Z axes as with the View[‘View’].RaiseX, View[‘View’].RaiseY and View[‘View’].RaiseZ options, the raise is applied along the radius of a sphere centered at (‘Xc’, ‘Yc’, ‘Zc’).

To produce a standard radiation pattern, set ‘Offset’ to minus the radius of the sphere the original data lives on.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(SphericalRaise) is executed in-place. Numeric options:

Xc

Default value: 0

Yc

Default value: 0

Zc

Default value: 0

Raise

Default value: 1

Offset

Default value: 0

TimeStep

Default value: 0

View

Default value: -1

Plugin(StreamLines)

Plugin(StreamLines) computes stream lines from the ‘TimeStep’-th time step of a vector view ‘View’ and optionally interpolates the scalar view ‘OtherView’ on the resulting stream lines.

The plugin takes as input a grid defined by the 3 points (‘X0’,‘Y0’,‘Z0’) (origin), (‘X1’,‘Y1’,‘Z1’) (axis of U) and (‘X2’,‘Y2’,‘Z2’) (axis of V).

The number of points along U and V that are to be transported is set with the options ‘NumPointsU’ and ‘NumPointsV’. The equation

dX(t)/dt = V(x,y,z)

is then solved with the initial condition X(t=0) chosen as the grid and with V(x,y,z) interpolated on the vector view.

The time stepping scheme is a RK44 with step size ‘DT’ and ‘MaxIter’ maximum number of iterations.

If ‘TimeStep’ < 0, the plugin tries to compute streamlines of the unsteady flow.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(StreamLines) creates one new view. This view contains multi-step vector points if ‘OtherView’ < 0, or single-step scalar lines if ‘OtherView’ >= 0. Numeric options:

X0

Default value: 0

Y0

Default value: 0

Z0

Default value: 0

X1

Default value: 1

Y1

Default value: 0

Z1

Default value: 0

X2

Default value: 0

Y2

Default value: 1

Z2

Default value: 0

NumPointsU

Default value: 10

NumPointsV

Default value: 1

DT

Default value: 0.1

MaxIter

Default value: 100

TimeStep

Default value: 0

View

Default value: -1

OtherView

Default value: -1

Plugin(Tetrahedralize)

Plugin(Tetrahedralize) tetrahedralizes the points in the view ‘View’.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Tetrahedralize) creates one new view. Numeric options:

View

Default value: -1

Plugin(ThinLayerFixMesh)

Fix the mesh in thin parts

Plugin(Transform)

Plugin(Transform) transforms the homogeneous node coordinates (x,y,z,1) of the elements in the view ‘View’ by the matrix

[‘A11’ ‘A12’ ‘A13’ ‘Tx’]
[‘A21’ ‘A22’ ‘A23’ ‘Ty’]
[‘A31’ ‘A32’ ‘A33’ ‘Tz’].

If ‘SwapOrientation’ is set, the orientation of the elements is reversed.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Transform) is executed in-place. Numeric options:

A11

Default value: 1

A12

Default value: 0

A13

Default value: 0

A21

Default value: 0

A22

Default value: 1

A23

Default value: 0

A31

Default value: 0

A32

Default value: 0

A33

Default value: 1

Tx

Default value: 0

Ty

Default value: 0

Tz

Default value: 0

SwapOrientation

Default value: 0

View

Default value: -1

Plugin(Triangulate)

Plugin(Triangulate) triangulates the points in the view ‘View’, assuming that all the points belong to a surface that can be projected one-to-one onto a plane. Algorithm selects the old (0) or new (1) meshing algorithm.

If ‘View’ < 0, the plugin is run on the current view.

Plugin(Triangulate) creates one new view. Numeric options:

Algorithm

Default value: 0

View

Default value: -1

Plugin(Warp)

Plugin(Warp) transforms the elements in the view ‘View’ by adding to their node coordinates the vector field stored in the ‘TimeStep’-th time step of the view ‘OtherView’, scaled by ‘Factor’.

If ‘View’ < 0, the plugin is run on the current view.

If ‘OtherView’ < 0, the vector field is taken as the field of surface normals multiplied by the ‘TimeStep’ value in ‘View’. (The smoothing of the surface normals is controlled by the ‘SmoothingAngle’ parameter.)

Plugin(Warp) is executed in-place. Numeric options:

Factor

Default value: 1

TimeStep

Default value: 0

SmoothingAngle

Default value: 180

View

Default value: -1

OtherView

Default value: -1