Gmsh 4.14.0 (development version)

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 4.14.0 (development version) (December 4, 2024).

Obtaining Gmsh

The source code and pre-compiled binary versions of Gmsh (for Windows, macOS and Linux) can be downloaded from https://gmsh.info. Gmsh packages are also directly available in various Linux and BSD distributions (Debian, Fedora, 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 https://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 https://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.

Reporting a bug

If, after reading this reference manual, you think you have found a bug in Gmsh, please file an issue on https://gitlab.onelab.info/gmsh/gmsh/issues. Provide as precise a description of the problem as you can, including sample input files that produce the bug. Don’t forget to mention both the version of Gmsh and your operation system.

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

1 Overview of Gmsh

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

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

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

1.1 Geometry module

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

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

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

Both model entities (also referred to as “elementary entities”) and physical groups are uniquely defined by a pair of integers: their dimension (0 for points, 1 for curves, 2 for surfaces, 3 for volumes) and their tag, a strictly positive global identification number. Entity and group tags are unique per dimension:

1. each point must possess a unique tag;
2. each curve must possess a unique tag;
3. each surface must possess a unique tag;
4. each volume must possess a unique tag.

Zero or negative tags are reserved by Gmsh for internal use.

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

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

In addition to CAD-type geometrical entities, whose geometry is provided by a CAD kernel, Gmsh also supports discrete model entities, which are defined by a mesh (e.g. STL). Gmsh does not perform geometrical operations on such discrete entities, but they can be equipped with a geometry through a so-called “reparametrization” procedure¹. The parametrization is then used for meshing, in exactly the same way as for CAD entities. See t13 for an example.

1.2 Mesh module

A finite element mesh of a model is a tessellation of its geometry by simple geometrical elements of various shapes (in Gmsh: lines, triangles, quadrangles, tetrahedra, prisms, hexahedra and pyramids), arranged in such a way that if two of them intersect, they do so along a face, an edge or a node, and never otherwise. This defines a so-called conformal mesh. The mesh module implements several algorithms to generate such meshes automatically. By default, meshes produced by Gmsh are considered as unstructured, even if they were generated in a structured way (e.g., by extrusion). This implies that the mesh elements are completely defined simply by an ordered list of their nodes, and that no predefined ordering relation is assumed between any two elements.

In order to guarantee the conformity of the mesh, mesh generation is performed in a bottom-up flow: curves are discretized first; the mesh of the curves is then used to mesh the surfaces; then the mesh of the surfaces is used to mesh the volumes. In this process, the mesh of an entity is only constrained by the mesh of its boundary, unless entities of lower dimensions are explicitly embedded in entities of higher dimension. For example, in three dimensions, the triangles discretizing a surface will be forced to be faces of tetrahedra in the final 3D mesh only if the surface is part of the boundary of a volume, or if that surface has been explicitly embedded in the volume. This automatically ensures the conformity of the mesh when, for example, two volumes share a common surface. Mesh elements are oriented according to the geometrical orientation of the underlying entity. Every meshing step is constrained by a mesh size field, which prescribes the desired size of the elements in the mesh. This size field can be uniform, specified by values associated with points in the geometry, or defined by general mesh size fields (for example related to the distance to some boundary, to a arbitrary scalar field defined on another mesh, etc.): see Gmsh mesh size fields. For each meshing step, all structured mesh directives are executed first, and serve as additional constraints for the unstructured parts. (The generation and handling of conformal meshes has important consequences on how meshes are stored internally in Gmsh, and how they are accessed through the API: see Gmsh application programming interface.)

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

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

1.2.1 Choosing the right unstructured algorithm

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

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

• 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.
• 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.
• The “Frontal-Delaunay” algorithm is inspired by the work of S. Rebay⁶.
• Other experimental algorithms with specific features are also available. In particular, “Frontal-Delaunay for Quads”⁷ is a variant of the “Frontal-Delaunay” algorithm aiming at generating right-angle triangles suitable for recombination; and “BAMG”⁸ allows to generate anisotropic triangulations.

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

Several 3D unstructured algorithms are also available:

• The “Delaunay” algorithm is split into three separate steps. First, an initial mesh of the union of all the volumes in the model is performed, without inserting points in the volume. The surface mesh is then recovered using H. Si’s boundary recovery algorithm Tetgen/BR. Then a three-dimensional version of the 2D Delaunay algorithm described above is applied to insert points in the volume to respect the mesh size constraints.
• The “Frontal” algorithm uses J. Schoeberl’s Netgen algorithm ⁹.
• The “HXT” algorithm¹⁰ is a new efficient and parallel reimplementaton of the Delaunay algorithm.
• Other experimental algorithms with specific features are also available. In particular, “MMG3D”¹¹ allows to generate anisotropic tetrahedralizations.

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

When Gmsh is configured with OpenMP support (see Compiling the source code), most of the meshing steps can be performed in parallel:

• 1D and 2D meshing is parallelized using a coarse-grained approach, i.e. curves (resp. surfaces) are each meshed sequentially, but several curves (resp. surfaces) can be meshed at the same time.
• 3D meshing using HXT is parallelized using a fine-grained approach, i.e. the actual meshing procedure for a single volume is done is parallel.

The number of threads can be controlled with the -nt flag on the command line (see Gmsh command-line interface), or with the General.NumThreads, Mesh.MaxNumThreads1D, Mesh.MaxNumThreads2D and Mesh.MaxNumThreads3D options (see General options and Mesh options).

1.2.2 Specifying mesh element sizes

To determine the size of mesh elements, Gmsh locally computes the minimum of

1. the size of the model bounding box;
2. if Mesh.MeshSizeFromPoints is set, the mesh size specified at geometrical points;
3. if Mesh.MeshSizeFromCurvature is positive, the mesh size based on the curvature of the curves and surfaces (the specified value is the number of elements per 2 Pi radians);
4. the background mesh size field, expressed as a combination of mesh size fields (see Gmsh mesh size fields):
   • Box fields specify the size inside and outside of a parallelepipedic region;
   • Distance fields specify the size according to the distance to model entities;
   • MathEval fields specify the size using an explicit mathematical function;
   • PostView fields specify an explicit background mesh in the form of a scalar post-processing view (see Post-processing module, and Gmsh file formats) in which the nodal values represent the target sizes. This method is very general but it requires a first (usually rough) mesh and a way to compute the target sizes on this mesh (usually through an error estimation procedure, e.g. in an iterative process of mesh adaptation);
   • Extend fields compute an extension of the sizes from a given boundary entity inside the enclosed surfaces or volumes;
   • Min and Max fields specify the size as the minimum or maximum of the sizes computed using other fields;
   • …
5. any per-entity mesh size constraint.

Using the Gmsh API, this value can then be further modified using a C++, C, Python, Julia or Fortran mesh size callback function provided via gmsh/model/mesh/setSizeCallback (see Namespace gmsh/model/mesh).

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

Boundary mesh sizes are interpolated during mesh generation inside surfaces and/or volumes depending on the value of Mesh.MeshSizeExtendFromBoundary (see Mesh options for the default values of all these options). When the mesh element sizes are fully specified by a background mesh size field, it is often desirable to set

Mesh.MeshSizeFromPoints = 0;
Mesh.MeshSizeFromCurvature = 0;
Mesh.MeshSizeExtendFromBoundary = 0;

to prevent over-refinement inside an entity due to small mesh sizes on its boundary.

In all cases, meshes are constrained by structured meshing constraints (e.g. transfinite or extruded meshes) as well as by any discrete model entity that is not equipped with a geometry (which will thus preserve its mesh during mesh generation). Meshes on curves are further constrainted by the Mesh.MinLineNodes, Mesh.MinCircleNodes and Mesh.MinCurveNodes options.

1.2.3 Elementary entities vs. physical groups

It is usually convenient to combine elementary geometrical entities into more meaningful groups, e.g. to define some mathematical (“domain”, “boundary with Neumann condition”), functional (“left wing”, “fuselage”) or material (“steel”, “carbon”) properties. Such grouping is done in Gmsh’s geometry module (see Geometry module) through the definition of “physical groups”.

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

1.3 Solver module

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

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

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

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

1.4 Post-processing module

The post-processing module can handle multiple scalar, vector or tensor datasets along with the geometry and the mesh. The datasets can be given in several formats: in human-readable “parsed” format (these are just part of a standard input script, but are usually put in separate files with a .pos extension – see Post-processing scripting commands), in native MSH files (ASCII or binary files with .msh extensions: see Gmsh file formats), or in standard third-party formats such as CGNS or MED. Datasets can also be directly imported using the Gmsh API (see Namespace gmsh/view).

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

Each dataset, along with the visualization options, is called a “post-processing view”, or simply a “view”. Each view is given a name, and can be manipulated either individually (each view has its own button in the GUI and can be referred to by its index or its unique tag in a script or in the API) or globally (see the PostProcessing.Link option in Post-processing options). Possible operations on post-processing views include section computation, offset, elevation, boundary and component extraction, color map and range modification, animation, vector graphic output, etc. These operations are either carried out nondestructively through the modification of post-processing options, or can lead to the actual modification of the view data or the creation of new views when done using post-processing plugins (see Gmsh plugins). Both can be fully automated in scripts or through the API (see e.g., t8, and t9).

By default, Gmsh treats all post-processing views as three-dimensional plots, i.e., draws the scalar, vector and tensor primitives (points, curves, triangles, tetrahedra, etc.) in 3D space. But Gmsh can also represent each post-processing view containing 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.

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

1.6 … and what Gmsh is not so good at

Here are some known weaknesses of Gmsh:

• Gmsh is not a multi-bloc mesh generator: all meshes produced by Gmsh are conforming in the sense of finite element meshes;
• Gmsh’s graphical user interface is only exposing a limited number of the available features, and many aspects of the interface could be enhanced (especially manipulators).
• While Gmsh can create and manipulate geometries interactively, it is in no way a full-fledged replacement for an advanced CAD system.
• Gmsh uses straightforward OpenGL 1.1 for graphics, without specific tricks to handle very large meshes and post-processing datasets (decimation and automatic level of detail, culling, advanced transparency, etc.).
• Your complaints about Gmsh here :-)

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 Installing and running Gmsh on your computer

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

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

As a library, Gmsh can still be used in the same way as the standalone Gmsh app, but in addition it can also be embedded in external codes using the Gmsh API (see Gmsh application programming interface). The API is available in C++, C, Python, Julia and Fortran. A binary Software Development Kit (SDK) for Windows, Linux and macOS, that contains the dynamic Gmsh library and the associated header and module files, can be downloaded from https://gmsh.info/#Download. Python users can use

pip install --upgrade gmsh

which will download the binary SDK and install the files in the appropriate system directories. Several Linux distributions also ship the Gmsh SDK. See Compiling the source code for instructions on how to compile the dynamic Gmsh library from source.

2 Gmsh tutorial

The following tutorials introduce new features gradually, starting with the first tutorial t1 (see t1). The corresponding files are available in the tutorials directory of the Gmsh distribution.

The .geo files (e.g. t1.geo) are written in Gmsh’s built-in scripting language (see Gmsh scripting language). You can open them directly with the Gmsh app: in the GUI (see Gmsh graphical user interface), use the ‘File->Open’ menu and select e.g. t1.geo. Or on the command line, run

> gmsh t1.geo

which will launch the GUI, or run

> gmsh t1.geo -2

to perform 2D meshing in batch mode (see Gmsh command-line interface).

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

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

Note that besides these tutorials, the Gmsh distribution contains many other examples written using both the built-in scripting language and the API: see examples and benchmarks.

2.1 t1: Geometry basics, elementary entities, physical groups

See t1.geo. Also available in C++ (t1.cpp), C (t1.c), Python (t1.py), Julia (t1.jl) and Fortran (t1.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 1
//
//  Geometry basics, elementary entities, physical groups
//
// -----------------------------------------------------------------------------

// The simplest construction in Gmsh's scripting language is the
// `affectation'. The following command defines a new variable `lc':

lc = 1e-2;

// This variable can then be used in the definition of Gmsh's simplest
// `elementary entity', a `Point'. A Point is uniquely identified by a tag (a
// strictly positive integer; here `1') and defined by a list of four numbers:
// three coordinates (X, Y and Z) and the target mesh size (lc) close to the
// point:

Point(1) = {0, 0, 0, lc};

// The distribution of the mesh element sizes will then be obtained by
// interpolation of these mesh sizes throughout the geometry. Another method to
// specify mesh sizes is to use general mesh size Fields (see `t10.geo'). A
// particular case is the use of a background mesh (see `t7.geo').

// If no target mesh size of provided, a default uniform coarse size will be
// used for the model, based on the overall model size.

// We can then define some additional points. All points should have different
// tags:

Point(2) = {.1, 0,  0, lc};
Point(3) = {.1, .3, 0, lc};
Point(4) = {0,  .3, 0, lc};

// Curves are Gmsh's second type of elementary entities, and, amongst curves,
// straight lines are the simplest. A straight line is identified by a tag and
// is defined by a list of two point tags. In the commands below, for example,
// the line 1 starts at point 1 and ends at point 2.
//
// Note that curve tags are separate from point tags - hence we can reuse tag
// `1' for our first curve. And as a general rule, elementary entity tags in
// Gmsh have to be unique per geometrical dimension.

Line(1) = {1, 2};
Line(2) = {3, 2};
Line(3) = {3, 4};
Line(4) = {4, 1};

// The third elementary entity is the surface. In order to define a simple
// rectangular surface from the four curves defined above, a curve loop has
// first to be defined. A curve loop is also identified by a tag (unique amongst
// curve loops) and defined by an ordered list of connected curves, a sign being
// associated with each curve (depending on the orientation of the curve to form
// a loop):

Curve Loop(1) = {4, 1, -2, 3};

// We can then define the surface as a list of curve loops (only one here,
// representing the external contour, since there are no holes--see `t4.geo' for
// an example of a surface with a hole):

Plane Surface(1) = {1};

// At this level, Gmsh knows everything to display the rectangular surface 1 and
// to mesh it. An optional step is needed if we want to group elementary
// geometrical entities into more meaningful groups, e.g. to define some
// mathematical ("domain", "boundary"), functional ("left wing", "fuselage") or
// material ("steel", "carbon") properties.
//
// Such groups are called "Physical Groups" in Gmsh. By default, if physical
// groups are defined, Gmsh will export in output files only mesh elements that
// belong to at least one physical group. (To force Gmsh to save all elements,
// whether they belong to physical groups or not, set `Mesh.SaveAll=1;', or
// specify `-save_all' on the command line.) Physical groups are also identified
// by tags, i.e. strictly positive integers, that should be unique per dimension
// (0D, 1D, 2D or 3D). Physical groups can also be given names.
//
// Here we define a physical curve that groups the left, bottom and right curves
// in a single group (with prescribed tag 5); and a physical surface with name
// "My surface" (with an automatic tag) containing the geometrical surface 1:

Physical Curve(5) = {1, 2, 4};
Physical Surface("My surface") = {1};

// Now that the geometry is complete, you can
// - either open this file with Gmsh and select `2D' in the `Mesh' module to
//   create a mesh; then select `Save' to save it to disk in the default format
//   (or use `File->Export' to export in other formats);
// - or run `gmsh t1.geo -2` to mesh in batch mode on the command line.

// You could also uncomment the following lines in this script:
//
//   Mesh 2;
//   Save "t1.msh";
//
// which would lead Gmsh to mesh and save the mesh every time the file is
// parsed. (To simply parse the file from the command line, you can use `gmsh
// t1.geo -')

// By default, Gmsh saves meshes in the latest version of the Gmsh mesh file
// format (the `MSH' format). You can save meshes in other mesh formats by
// specifying a filename with a different extension in the GUI, on the command
// line or in scripts. For example
//
//   Save "t1.unv";
//
// will save the mesh in the UNV format. You can also save the mesh in older
// versions of the MSH format:
//
// - In the GUI: open `File->Export', enter your `filename.msh' and then pick
//   the version in the dropdown menu.
// - On the command line: use the `-format' option (e.g. `gmsh file.geo -format
//   msh2 -2').
// - In a `.geo' script: add `Mesh.MshFileVersion = x.y;' for any version
//   number `x.y'.
// - As an alternative method, you can also not specify the format explicitly,
//   and just choose a filename with the `.msh2' or `.msh4' extension.

// Note that starting with Gmsh 3.0, models can be built using other geometry
// kernels than the default built-in kernel. By specifying
//
//   SetFactory("OpenCASCADE");
//
// any subsequent command in the `.geo' file would be handled by the OpenCASCADE
// geometry kernel instead of the built-in kernel. Different geometry kernels
// have different features. With OpenCASCADE, instead of defining the surface by
// successively defining 4 points, 4 curves and 1 curve loop, one can define the
// rectangular surface directly with
//
//   Rectangle(2) = {.2, 0, 0, .1, .3};
//
// The underlying curves and points could be accessed with the `Boundary' or
// `CombinedBoundary' operators.
//
// See e.g. `t16.geo', `t18.geo', `t19.geo' or `t20.geo' for complete examples
// based on OpenCASCADE, and `examples/boolean' for more.

2.2 t2: Transformations, extruded geometries, volumes

See t2.geo. Also available in C++ (t2.cpp), C (t2.c), Python (t2.py), Julia (t2.jl) and Fortran (t2.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 2
//
//  Transformations, extruded geometries, volumes
//
// -----------------------------------------------------------------------------

// We first include the previous tutorial file, in order to use it as a basis
// for this one. Including a file is equivalent to copy-pasting its contents:

Include "t1.geo";

// We can then add new points and curves in the same way as we did in `t1.geo':

Point(5) = {0, .4, 0, lc};
Line(5) = {4, 5};

// Gmsh also provides tools to transform (translate, rotate, etc.)
// elementary entities or copies of elementary entities. For example, point
// 5 can be moved by 0.02 to the left with:

Translate {-0.02, 0, 0} { Point{5}; }

// And it can be further rotated by -Pi/4 around (0, 0.3, 0) (with the rotation
// along the z axis) with:

Rotate {{0,0,1}, {0,0.3,0}, -Pi/4} { Point{5}; }

// Note that there are no units in Gmsh: coordinates are just numbers - it's up
// to the user to associate a meaning to them.

// Point 3 can be duplicated and translated by 0.05 along the y axis:

Translate {0, 0.05, 0} { Duplicata{ Point{3}; } }

// This command created a new point with an automatically assigned tag. This tag
// can be obtained using the graphical user interface by hovering the mouse over
// the point: in this case, the new point has tag `6'.

Line(7) = {3, 6};
Line(8) = {6, 5};
Curve Loop(10) = {5,-8,-7,3};
Plane Surface(11) = {10};

// To automate the workflow, instead of using the graphical user interface to
// obtain the tags of newly created entities, one can use the return value of
// the transformation commands directly. For example, the `Translate' command
// returns a list containing the tags of the translated entities. Let's
// translate copies of the two surfaces 1 and 11 to the right with the following
// command:

my_new_surfs[] = Translate {0.12, 0, 0} { Duplicata{ Surface{1, 11}; } };

// my_new_surfs[] (note the square brackets, and the `;' at the end of the
// command) denotes a list, which contains the tags of the two new surfaces
// (check `Tools->Message console' to see the message):

Printf("New surfaces '%g' and '%g'", my_new_surfs[0], my_new_surfs[1]);

// In Gmsh lists use square brackets for their definition (mylist[] = {1, 2,
// 3};) as well as to access their elements (myotherlist[] = {mylist[0],
// mylist[2]}; mythirdlist[] = myotherlist[];), with list indexing starting at
// 0. To get the size of a list, use the hash (pound): len = #mylist[].
//
// Note that parentheses can also be used instead of square brackets, so that we
// could also write `myfourthlist() = {mylist(0), mylist(1)};'.

// Volumes are the fourth type of elementary entities in Gmsh. In the same way
// one defines curve loops to build surfaces, one has to define surface loops
// (i.e. `shells') to build volumes. The following volume does not have holes
// and thus consists of a single surface loop:

Point(100) = {0., 0.3, 0.12, lc};  Point(101) = {0.1, 0.3, 0.12, lc};
Point(102) = {0.1, 0.35, 0.12, lc};

xyz[] = Point{5}; // Get coordinates of point 5
Point(103) = {xyz[0], xyz[1], 0.12, lc};

Line(110) = {4, 100};   Line(111) = {3, 101};
Line(112) = {6, 102};   Line(113) = {5, 103};
Line(114) = {103, 100}; Line(115) = {100, 101};
Line(116) = {101, 102}; Line(117) = {102, 103};

Curve Loop(118) = {115, -111, 3, 110};  Plane Surface(119) = {118};
Curve Loop(120) = {111, 116, -112, -7}; Plane Surface(121) = {120};
Curve Loop(122) = {112, 117, -113, -8}; Plane Surface(123) = {122};
Curve Loop(124) = {114, -110, 5, 113};  Plane Surface(125) = {124};
Curve Loop(126) = {115, 116, 117, 114}; Plane Surface(127) = {126};

Surface Loop(128) = {127, 119, 121, 123, 125, 11};
Volume(129) = {128};

// When a volume can be extruded from a surface, it is usually easier to use the
// `Extrude' command directly instead of creating all the points, curves and
// surfaces by hand. For example, the following command extrudes the surface 11
// along the z axis and automatically creates a new volume (as well as all the
// needed points, curves and surfaces):

Extrude {0, 0, 0.12} { Surface{my_new_surfs[1]}; }

// The following command permits to manually assign a mesh size to some of the
// new points:

MeshSize {103, 105, 109, 102, 28, 24, 6, 5} = lc * 3;

// We finally group volumes 129 and 130 in a single physical group with tag `1'
// and name "The volume":

Physical Volume("The volume", 1) = {129,130};

// Note that, if the transformation tools are handy to create complex
// geometries, it is also sometimes useful to generate the `flat' geometry, with
// an explicit representation of all the elementary entities.
//
// With the built-in geometry kernel, this can be achieved with `File->Export' by
// selecting the `Gmsh Unrolled GEO' format, or by adding
//
//   Save "file.geo_unrolled";
//
// in the script. It can also be achieved with `gmsh t2.geo -0' on the command
// line.
//
// With the OpenCASCADE geometry kernel, unrolling the geometry can be achieved
// with `File->Export' by selecting the `OpenCASCADE BRep' format, or by adding
//
//   Save "file.brep";
//
// in the script. (OpenCASCADE geometries can also be exported to STEP.)

// It is important to note that Gmsh never translates geometry data into a
// common representation: all the operations on a geometrical entity are
// performed natively with the associated geometry kernel. Consequently, one
// cannot export a geometry constructed with the built-in kernel as an
// OpenCASCADE BRep file; or export an OpenCASCADE model as an Unrolled GEO
// file.

2.3 t3: Extruded meshes, ONELAB parameters, options

See t3.geo. Also available in C++ (t3.cpp), Python (t3.py), Julia (t3.jl) and Fortran (t3.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 3
//
//  Extruded meshes, ONELAB parameters, options
//
// -----------------------------------------------------------------------------

// Again, we start by including the first tutorial:

Include "t1.geo";

// As in `t2.geo', we plan to perform an extrusion along the z axis.  But here,
// instead of only extruding the geometry, we also want to extrude the 2D
// mesh. This is done with the same `Extrude' command, but by specifying element
// 'Layers' (2 layers in this case, the first one with 8 subdivisions and the
// second one with 2 subdivisions, both with a height of h/2):

h = 0.1;

Extrude {0,0,h} {
  Surface{1}; Layers{ {8,2}, {0.5,1} };
}

// The extrusion can also be performed with a rotation instead of a translation,
// and the resulting mesh can be recombined into prisms (we use only one layer
// here, with 7 subdivisions). All rotations are specified by an axis direction
// ({0,1,0}), an axis point ({-0.1,0,0.1}) and a rotation angle (-Pi/2):

Extrude { {0,1,0} , {-0.1,0,0.1} , -Pi/2 } {
  Surface{28}; Layers{7}; Recombine;
}

// Using the built-in geometry kernel, only rotations with angles < Pi are
// supported. To do a full turn, you will thus need to apply at least 3
// rotations. The OpenCASCADE geometry kernel does not have this limitation.

// Note that a translation ({-2*h,0,0}) and a rotation ({1,0,0}, {0,0.15,0.25},
// Pi/2) can also be combined to form a "twist". Here the angle is specified as
// a ONELAB parameter, using the `DefineConstant' syntax. ONELAB parameters can
// be modified interactively in the GUI, and can be exchanged with other codes
// connected to the same ONELAB database:

DefineConstant[ angle = {90, Min 0, Max 120, Step 1,
                         Name "Parameters/Twisting angle"} ];

// In more details, `DefineConstant' allows you to assign the value of the
// ONELAB parameter "Parameters/Twisting angle" to the variable `angle'. If the
// ONELAB parameter does not exist in the database, `DefineConstant' will create
// it and assign the default value `90'. Moreover, if the variable `angle' was
// defined before the call to `DefineConstant', the `DefineConstant' call would
// simply be skipped. This allows to build generic parametric models, whose
// parameters can be frozen from the outside - the parameters ceasing to be
// "parameters".
//
// An interesting use of this feature is in conjunction with the `-setnumber
// name value' command line switch, which defines a variable `name' with value
// `value'. Calling `gmsh t3.geo -setnumber angle 30' would define `angle'
// before the `DefineConstant', making `t3.geo' non-parametric
// ("Parameters/Twisting angle" will not be created in the ONELAB database and
// will not be available for modification in the graphical user interface).

out[] = Extrude { {-2*h,0,0}, {1,0,0} , {0,0.15,0.25} , angle * Pi / 180 } {
  Surface{50}; Layers{10}; Recombine;
};

// In this last extrusion command we retrieved the volume number
// programmatically by using the return value (a list) of the `Extrude'
// command. This list contains the "top" of the extruded surface (in `out[0]'),
// the newly created volume (in `out[1]') and the tags of the lateral surfaces
// (in `out[2]', `out[3]', ...).

// We can then define a new physical volume (with tag 101) to group all the
// elementary volumes:

Physical Volume(101) = {1, 2, out[1]};

// Let us now change some options... Since all interactive options are
// accessible in Gmsh's scripting language, we can for example make point tags
// visible or redefine some colors directly in the input file:

Geometry.PointNumbers = 1;
Geometry.Color.Points = Orange;
General.Color.Text = White;
Mesh.Color.Points = {255, 0, 0};

// Note that all colors can be defined literally or numerically, i.e.
// `Mesh.Color.Points = Red' is equivalent to `Mesh.Color.Points = {255,0,0}';
// and also note that, as with user-defined variables, the options can be used
// either as right or left hand sides, so that the following command will set
// the surface color to the same color as the points:

Geometry.Color.Surfaces = Geometry.Color.Points;

// You can use the `Help->Current Options and Workspace' menu to see the current
// values of all options. To save all the options in a file, use
// `File->Export->Gmsh Options'. To associate the current options with the
// current file use `File->Save Model Options'. To save the current options for
// all future Gmsh sessions use `File->Save Options As Default'.

2.4 t4: Built-in functions, holes in surfaces, annotations, entity colors

See t4.geo. Also available in C++ (t4.cpp), Python (t4.py), Julia (t4.jl) and Fortran (t4.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 4
//
//  Built-in functions, holes in surfaces, annotations, entity colors
//
// -----------------------------------------------------------------------------

// As usual, we start by defining some variables:

cm = 1e-02;
e1 = 4.5 * cm; e2 = 6 * cm / 2; e3 =  5 * cm / 2;
h1 = 5 * cm; h2 = 10 * cm; h3 = 5 * cm; h4 = 2 * cm; h5 = 4.5 * cm;
R1 = 1 * cm; R2 = 1.5 * cm; r = 1 * cm;
Lc1 = 0.01;
Lc2 = 0.003;

// We can use all the usual mathematical functions (note the capitalized first
// letters), plus some useful functions like Hypot(a, b) := Sqrt(a^2 + b^2):

ccos = (-h5*R1 + e2 * Hypot(h5, Hypot(e2, R1))) / (h5^2 + e2^2);
ssin = Sqrt(1 - ccos^2);

// Then we define some points and some lines using these variables:

Point(1) = {-e1-e2, 0    , 0, Lc1}; Point(2) = {-e1-e2, h1   , 0, Lc1};
Point(3) = {-e3-r , h1   , 0, Lc2}; Point(4) = {-e3-r , h1+r , 0, Lc2};
Point(5) = {-e3   , h1+r , 0, Lc2}; Point(6) = {-e3   , h1+h2, 0, Lc1};
Point(7) = { e3   , h1+h2, 0, Lc1}; Point(8) = { e3   , h1+r , 0, Lc2};
Point(9) = { e3+r , h1+r , 0, Lc2}; Point(10)= { e3+r , h1   , 0, Lc2};
Point(11)= { e1+e2, h1   , 0, Lc1}; Point(12)= { e1+e2, 0    , 0, Lc1};
Point(13)= { e2   , 0    , 0, Lc1};

Point(14)= { R1 / ssin, h5+R1*ccos, 0, Lc2};
Point(15)= { 0        , h5        , 0, Lc2};
Point(16)= {-R1 / ssin, h5+R1*ccos, 0, Lc2};
Point(17)= {-e2       , 0.0       , 0, Lc1};

Point(18)= {-R2 , h1+h3   , 0, Lc2}; Point(19)= {-R2 , h1+h3+h4, 0, Lc2};
Point(20)= { 0  , h1+h3+h4, 0, Lc2}; Point(21)= { R2 , h1+h3+h4, 0, Lc2};
Point(22)= { R2 , h1+h3   , 0, Lc2}; Point(23)= { 0  , h1+h3   , 0, Lc2};

Point(24)= { 0, h1+h3+h4+R2, 0, Lc2}; Point(25)= { 0, h1+h3-R2,    0, Lc2};

Line(1)  = {1 , 17};
Line(2)  = {17, 16};

// Gmsh provides other curve primitives than straight lines: splines, B-splines,
// circle arcs, ellipse arcs, etc. Here we define a new circle arc, starting at
// point 14 and ending at point 16, with the circle's center being the point 15:

Circle(3) = {14,15,16};

// Note that, in Gmsh, circle arcs should always be smaller than Pi. The
// OpenCASCADE geometry kernel does not have this limitation.

// We can then define additional lines and circles, as well as a new surface:

Line(4)  = {14, 13}; Line(5)   = {13, 12};   Line(6)    = {12, 11};
Line(7)  = {11, 10}; Circle(8) = {8, 9, 10}; Line(9)    = {8, 7};
Line(10) = {7, 6};   Line(11)  = {6, 5};     Circle(12) = {3, 4, 5};
Line(13) = {3, 2};   Line(14)  = {2, 1};     Line(15)   = {18, 19};
Circle(16) = {21, 20, 24}; Circle(17) = {24, 20, 19};
Circle(18) = {18, 23, 25}; Circle(19) = {25, 23, 22};
Line(20) = {21,22};

Curve Loop(21) = {17, -15, 18, 19, -20, 16};
Plane Surface(22) = {21};

// But we still need to define the exterior surface. Since this surface has a
// hole, its definition now requires two curves loops:

Curve Loop(23) = {11, -12, 13, 14, 1, 2, -3, 4, 5, 6, 7, -8, 9, 10};
Plane Surface(24) = {23, 21};

// As a general rule, if a surface has N holes, it is defined by N+1 curve loops:
// the first loop defines the exterior boundary; the other loops define the
// boundaries of the holes.

// Finally, we can add some comments by embedding a post-processing view
// containing some strings:

View "comments" {
  // Add a text string in window coordinates, 10 pixels from the left and 10
  // pixels from the bottom, using the `StrCat' function to concatenate strings:
  T2(10, -10, 0){ StrCat("Created on ", Today, " with Gmsh") };

  // Add a text string in model coordinates centered at (X,Y,Z) = (0, 0.11, 0):
  T3(0, 0.11, 0, TextAttributes("Align", "Center", "Font", "Helvetica")){
    "Hole"
  };

  // If a string starts with `file://', the rest is interpreted as an image
  // file. For 3D annotations, the size in model coordinates can be specified
  // after a `@' symbol in the form `widthxheight' (if one of `width' or
  // `height' is zero, natural scaling is used; if both are zero, original image
  // dimensions in pixels are used):
  T3(0, 0.09, 0, TextAttributes("Align", "Center")){
    "file://t4_image.png@0.01x0"
  };

  // The 3D orientation of the image can be specified by proving the direction
  // of the bottom and left edge of the image in model space:
  T3(-0.01, 0.09, 0, 0){ "file://t4_image.png@0.01x0,0,0,1,0,1,0" };

  // The image can also be drawn in "billboard" mode, i.e. always parallel to
  // the camera, by using the `#' symbol:
  T3(0, 0.12, 0, TextAttributes("Align", "Center")){
    "file://t4_image.png@0.01x0#"
  };

  // The size of 2D annotations is given directly in pixels:
  T2(350, -7, 0){ "file://t4_image.png@20x0" };
};

// This post-processing view is in the "parsed" format, i.e. it is interpreted
// using the same parser as the `.geo' file. For large post-processing datasets,
// that contain actual field values defined on a mesh, you should use the MSH
// file format instead, which allows to efficiently store continuous or
// discontinuous scalar, vector and tensor fields, or arbitrary polynomial
// order.

// Views and geometrical entities can be made to respond to double-click events,
// here to print some messages to the console:

View[0].DoubleClickedCommand = "Printf('View[0] has been double-clicked!');";
Geometry.DoubleClickedCurveCommand = "Printf('Curve %g has been double-clicked!',
  Geometry.DoubleClickedEntityTag);";

// We can also change the color of some entities:

Color Grey50{ Surface{ 22 }; }
Color Purple{ Surface{ 24 }; }
Color Red{ Curve{ 1:14 }; }
Color Yellow{ Curve{ 15:20 }; }

2.5 t5: Mesh sizes, macros, loops, holes in volumes

See t5.geo. Also available in C++ (t5.cpp), Python (t5.py), Julia (t5.jl) and Fortran (t5.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 5
//
//  Mesh sizes, macros, loops, holes in volumes
//
// -----------------------------------------------------------------------------

// We start by defining some target mesh sizes:

lcar1 = .1;
lcar2 = .0005;
lcar3 = .055;

// If we wanted to change these mesh sizes globally (without changing the above
// definitions), we could give a global scaling factor for all mesh sizes on the
// command line with the `-clscale' option (or with `Mesh.MeshSizeFactor' in an
// option file). For example, with:
//
// > gmsh t5.geo -clscale 1
//
// this input file produces a mesh of approximately 3000 nodes and 14,000
// tetrahedra. With
//
// > gmsh t5.geo -clscale 0.2
//
// the mesh counts approximately 231,000 nodes and 1,360,000 tetrahedra. You can
// check mesh statistics in the graphical user interface with the
// `Tools->Statistics' menu.
//
// See `t10.geo' for more information about mesh sizes.

// We proceed by defining some elementary entities describing a truncated cube:

Point(1) = {0.5,0.5,0.5,lcar2}; Point(2) = {0.5,0.5,0,lcar1};
Point(3) = {0,0.5,0.5,lcar1};   Point(4) = {0,0,0.5,lcar1};
Point(5) = {0.5,0,0.5,lcar1};   Point(6) = {0.5,0,0,lcar1};
Point(7) = {0,0.5,0,lcar1};     Point(8) = {0,1,0,lcar1};
Point(9) = {1,1,0,lcar1};       Point(10) = {0,0,1,lcar1};
Point(11) = {0,1,1,lcar1};      Point(12) = {1,1,1,lcar1};
Point(13) = {1,0,1,lcar1};      Point(14) = {1,0,0,lcar1};

Line(1) = {8,9};    Line(2) = {9,12};  Line(3) = {12,11};
Line(4) = {11,8};   Line(5) = {9,14};  Line(6) = {14,13};
Line(7) = {13,12};  Line(8) = {11,10}; Line(9) = {10,13};
Line(10) = {10,4};  Line(11) = {4,5};  Line(12) = {5,6};
Line(13) = {6,2};   Line(14) = {2,1};  Line(15) = {1,3};
Line(16) = {3,7};   Line(17) = {7,2};  Line(18) = {3,4};
Line(19) = {5,1};   Line(20) = {7,8};  Line(21) = {6,14};

Curve Loop(22) = {-11,-19,-15,-18};   Plane Surface(23) = {22};
Curve Loop(24) = {16,17,14,15};       Plane Surface(25) = {24};
Curve Loop(26) = {-17,20,1,5,-21,13}; Plane Surface(27) = {26};
Curve Loop(28) = {-4,-1,-2,-3};       Plane Surface(29) = {28};
Curve Loop(30) = {-7,2,-5,-6};        Plane Surface(31) = {30};
Curve Loop(32) = {6,-9,10,11,12,21};  Plane Surface(33) = {32};
Curve Loop(34) = {7,3,8,9};           Plane Surface(35) = {34};
Curve Loop(36) = {-10,18,-16,-20,4,-8}; Plane Surface(37) = {36};
Curve Loop(38) = {-14,-13,-12,19};    Plane Surface(39) = {38};

// Instead of using included files, we now use a user-defined macro in order
// to carve some holes in the cube:

Macro CheeseHole

  // In the following commands we use the reserved variable name `newp', which
  // automatically selects a new point tag. Analogously to `newp', the special
  // variables `newc', `newcl, `news', `newsl' and `newv' select new curve,
  // curve loop, surface, surface loop and volume tags.
  //
  // If `Geometry.OldNewReg' is set to 0, the new tags are chosen as the highest
  // current tag for each category (points, curves, curve loops, ...), plus
  // one. By default, for backward compatibility, `Geometry.OldNewReg' is set
  // to 1, and only two categories are used: one for points and one for the
  // rest.

  p1 = newp; Point(p1) = {x,  y,  z,  lcar3};
  p2 = newp; Point(p2) = {x+r,y,  z,  lcar3};
  p3 = newp; Point(p3) = {x,  y+r,z,  lcar3};
  p4 = newp; Point(p4) = {x,  y,  z+r,lcar3};
  p5 = newp; Point(p5) = {x-r,y,  z,  lcar3};
  p6 = newp; Point(p6) = {x,  y-r,z,  lcar3};
  p7 = newp; Point(p7) = {x,  y,  z-r,lcar3};

  c1 = newc; Circle(c1) = {p2,p1,p7}; c2 = newc; Circle(c2) = {p7,p1,p5};
  c3 = newc; Circle(c3) = {p5,p1,p4}; c4 = newc; Circle(c4) = {p4,p1,p2};
  c5 = newc; Circle(c5) = {p2,p1,p3}; c6 = newc; Circle(c6) = {p3,p1,p5};
  c7 = newc; Circle(c7) = {p5,p1,p6}; c8 = newc; Circle(c8) = {p6,p1,p2};
  c9 = newc; Circle(c9) = {p7,p1,p3}; c10 = newc; Circle(c10) = {p3,p1,p4};
  c11 = newc; Circle(c11) = {p4,p1,p6}; c12 = newc; Circle(c12) = {p6,p1,p7};

  // We need non-plane surfaces to define the spherical holes. Here we use
  // `Surface', which can be used for surfaces with 3 or 4 curves on their
  // boundary. With the built-in kernel, if all the curves are circle arcs with
  // the same center, a spherical patch is created; otherwise transfinite
  // interpolation is used. With the OpenCASCADE kernel, `Surface' can be used
  // with an arbitrary number of boundary curves, and will fit a BSpline patch
  // through them.

  l1 = newcl; Curve Loop(l1) = {c5,c10,c4};
  l2 = newcl; Curve Loop(l2) = {c9,-c5,c1};
  l3 = newcl; Curve Loop(l3) = {c12,-c8,-c1};
  l4 = newcl; Curve Loop(l4) = {c8,-c4,c11};
  l5 = newcl; Curve Loop(l5) = {-c10,c6,c3};
  l6 = newcl; Curve Loop(l6) = {-c11,-c3,c7};
  l7 = newcl; Curve Loop(l7) = {-c2,-c7,-c12};
  l8 = newcl; Curve Loop(l8) = {-c6,-c9,c2};

  s1 = news; Surface(s1) = {l1};
  s2 = news; Surface(s2) = {l2};
  s3 = news; Surface(s3) = {l3};
  s4 = news; Surface(s4) = {l4};
  s5 = news; Surface(s5) = {l5};
  s6 = news; Surface(s6) = {l6};
  s7 = news; Surface(s7) = {l7};
  s8 = news; Surface(s8) = {l8};

  // We then store the surface loops tags in a list for later reference (we will
  // need these to define the final volume):

  theloops[t] = newsl;
  Surface Loop(theloops[t]) = {s1, s2, s3, s4, s5, s6, s7, s8};

  thehole = newv;
  Volume(thehole) = theloops[t];

Return

// We can use a `For' loop to generate five holes in the cube:

x = 0; y = 0.75; z = 0; r = 0.09;

For t In {1:5}

  x += 0.166;
  z += 0.166;

  // We call the `CheeseHole' macro:

  Call CheeseHole;

  // We define a physical volume for each hole:

  Physical Volume (t) = thehole;

  // We also print some variables on the terminal (note that, since all
  // variables in `.geo' files are treated internally as floating point numbers,
  // the format string should only contain valid floating point format
  // specifiers like `%g', `%f', '%e', etc.):

  Printf("Hole %g (center = {%g,%g,%g}, radius = %g) has number %g!",
	 t, x, y, z, r, thehole);

EndFor

// We can then define the surface loop for the exterior surface of the cube:

theloops[0] = newreg;
Surface Loop(theloops[0]) = {23:39:2};

// The volume of the cube, without the 5 holes, is now defined by 6 surface
// loops: the first surface loop defines the exterior surface; the surface loops
// other than the first one define holes.  (Again, to reference an array of
// variables, its identifier is followed by square brackets):

Volume(186) = {theloops[]};

// Note that using solid modelling with the OpenCASCADE geometry kernel, the
// same geometry could be built quite differently: see `t16.geo'.

// We finally define a physical volume for the elements discretizing the cube,
// without the holes (for which physical groups were already created in the
// `For' loop):

Physical Volume (10) = 186;

// We could make only part of the model visible to only mesh this subset:
//
// Hide {:}
// Recursive Show { Volume{129}; }
// Mesh.MeshOnlyVisible=1;

// Meshing algorithms can changed globally using options:

Mesh.Algorithm = 6; // Frontal-Delaunay for 2D meshes

// They can also be set for individual surfaces, e.g.

MeshAlgorithm Surface {31, 35} = 1; // MeshAdapt on surfaces 31 and 35

// To generate a curvilinear mesh and optimize it to produce provably valid
// curved elements (see A. Johnen, J.-F. Remacle and C. Geuzaine. Geometric
// validity of curvilinear finite elements. Journal of Computational Physics
// 233, pp. 359-372, 2013; and T. Toulorge, C. Geuzaine, J.-F. Remacle,
// J. Lambrechts. Robust untangling of curvilinear meshes. Journal of
// Computational Physics 254, pp. 8-26, 2013), you can uncomment the following
// lines:
//
// Mesh.ElementOrder = 2;
// Mesh.HighOrderOptimize = 2;

2.6 t6: Transfinite meshes, deleting entities

See t6.geo. Also available in C++ (t6.cpp), C (t6.c), Python (t6.py), Julia (t6.jl) and Fortran (t6.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 6
//
//  Transfinite meshes, deleting entities
//
// -----------------------------------------------------------------------------

// Let's use the geometry from the first tutorial as a basis for this one:
lc = 1e-2;
Point(1) = {0, 0, 0, lc};
Point(2) = {.1, 0,  0, lc};
Point(3) = {.1, .3, 0, lc};
Point(4) = {0,  .3, 0, lc};
Line(1) = {1, 2};
Line(2) = {3, 2};
Line(3) = {3, 4};
Line(4) = {4, 1};
Curve Loop(1) = {4, 1, -2, 3};
Plane Surface(1) = {1};

// Delete the surface and the left line, and replace the line with 3 new ones:
Delete{ Surface{1}; Curve{4}; }

p1 = newp; Point(p1) = {-0.05, 0.05, 0, lc};
p2 = newp; Point(p2) = {-0.05, 0.1, 0, lc};

l1 = newc; Line(l1) = {1, p1};
l2 = newc; Line(l2) = {p1, p2};
l3 = newc; Line(l3) = {p2, 4};

// Create a surface:
Curve Loop(2) = {2, -1, l1, l2, l3, -3};
Plane Surface(1) = {-2};

// The `Transfinite Curve' meshing constraints explicitly specifies the location
// of the nodes on the curve. For example, the following command forces 20
// uniformly placed nodes on curve 2 (including the nodes on the two end
// points):
Transfinite Curve{2} = 20;

// Let's put 20 points total on combination of curves `l1', `l2' and `l3'
// (beware that the points `p1' and `p2' are shared by the curves, so we do not
// create 6 + 6 + 10 = 22 nodes, but 20!)
Transfinite Curve{l1} = 6;
Transfinite Curve{l2} = 6;
Transfinite Curve{l3} = 10;

// Finally, we put 30 nodes following a geometric progression on curve 1
// (reversed) and on curve 3:
Transfinite Curve{-1, 3} = 30 Using Progression 1.2;

// The `Transfinite Surface' meshing constraint uses a transfinite interpolation
// algorithm in the parametric plane of the surface to connect the nodes on the
// boundary using a structured grid. If the surface has more than 4 corner
// points, the corners of the transfinite interpolation have to be specified by
// hand:
Transfinite Surface{1} = {1, 2, 3, 4};

// To create quadrangles instead of triangles, one can use the `Recombine'
// command:
Recombine Surface{1};

// When the surface has only 3 or 4 points on its boundary the list of corners
// can be omitted in the `Transfinite Surface' constraint:
Point(7) = {0.2, 0.2, 0, 1.0};
Point(8) = {0.2, 0.1, 0, 1.0};
Point(9) = {0.25, 0.2, 0, 1.0};
Point(10) = {0.3, 0.1, 0, 1.0};
Line(10) = {8, 10};
Line(11) = {10, 9};
Line(12) = {9, 7};
Line(13) = {7, 8};
Curve Loop(14) = {10, 11, 12, 13};
Plane Surface(15) = {14};
Transfinite Curve {10, 11, 12, 13} = 10;
Transfinite Surface{15};

// The way triangles are generated can be controlled by appending "Left",
// "Right" or "Alternate" after the `Transfinite Surface' command. Try e.g.
//
// Transfinite Surface{15} Alternate;

// Finally we apply an elliptic smoother to the grid to have a more regular
// mesh:
Mesh.Smoothing = 100;

2.7 t7: Background meshes

See t7.geo. Also available in C++ (t7.cpp), Python (t7.py), Julia (t7.jl) and Fortran (t7.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 7
//
//  Background meshes
//
// -----------------------------------------------------------------------------

// Mesh sizes can be specified very accurately by providing a background mesh,
// i.e., a post-processing view that contains the target mesh sizes.

// Merge a list-based post-processing view containing the target mesh sizes:
Merge "t7_bgmesh.pos";

// If the post-processing view was model-based instead of list-based (i.e. if it
// was based on an actual mesh), we would need to create a new model to contain
// the geometry so that meshing it does not destroy the background mesh. It's
// not necessary here since the view is list-based, but it does no harm:
NewModel;

// Merge the first tutorial geometry:
Merge "t1.geo";

// Apply the view as the current background mesh size field:
Background Mesh View[0];

// In order to compute the mesh sizes from the background mesh only, and
// disregard any other size constraints, one can set:
Mesh.MeshSizeExtendFromBoundary = 0;
Mesh.MeshSizeFromPoints = 0;
Mesh.MeshSizeFromCurvature = 0;

// See `t10.geo' for additional information: background meshes are actually a
// particular case of general "mesh size fields".

2.8 t8: Post-processing, image export and animations

See t8.geo. Also available in C++ (t8.cpp), Python (t8.py), Julia (t8.jl) and Fortran (t8.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 8
//
//  Post-processing, image export and animations
//
// -----------------------------------------------------------------------------

// In addition to creating geometries and meshes, GEO scripts can also be used
// to manipulate post-processing datasets (called "views" in Gmsh).

// We first include `t1.geo' as well as some post-processing views:

Include "t1.geo";
Include "view1.pos";
Include "view1.pos";
Include "view4.pos";

// Gmsh can read post-processing views in various formats. Here the `view1.pos'
// and `view4.pos' files are in the Gmsh "parsed" format, which is interpreted
// directly by the GEO script parser. The parsed format should only be used for
// relatively small datasets of course: for larger datasets using e.g. MSH files
// is much more efficient.

// We then set some general options:

General.Trackball = 0;
General.RotationX = 0; General.RotationY = 0; General.RotationZ = 0;
General.Color.Background = White; General.Color.Foreground = Black;
General.Color.Text = Black;
General.Orthographic = 0;
General.Axes = 0; General.SmallAxes = 0;

// We also set some options for each post-processing view:

v0 = PostProcessing.NbViews-4;
v1 = v0+1; v2 = v0+2; v3 = v0+3;

View[v0].IntervalsType = 2;
View[v0].OffsetZ = 0.05;
View[v0].RaiseZ = 0;
View[v0].Light = 1;
View[v0].ShowScale = 0;
View[v0].SmoothNormals = 1;

View[v1].IntervalsType = 1;
View[v1].ColorTable = { Green, Blue };
View[v1].NbIso = 10;
View[v1].ShowScale = 0;

View[v2].Name = "Test...";
View[v2].Axes = 1;
View[v2].Color.Axes = Black;
View[v2].IntervalsType = 2;
View[v2].Type = 2;
View[v2].AutoPosition = 0;
View[v2].PositionX = 85;
View[v2].PositionY = 50;
View[v2].Width = 200;
View[v2].Height = 130;

View[v3].Visible = 0;

// You can save an MPEG movie directly by selecting `File->Export' in the
// GUI. Several predefined animations are setup, for looping on all the time
// steps in views, or for looping between views.

// But a script can be used to build much more complex animations, by changing
// options at run-time and re-rendering the graphics. Each frame can then be
// saved to disk as an image, and multiple frames can be encoded to form a
// movie. Below is an example of such a custom animation.

t = 0; // Initial step

// Loop on num from 1 to 3
For num In {1:3}

  View[v0].TimeStep = t; // Set time step
  View[v1].TimeStep = t;
  View[v2].TimeStep = t;
  View[v3].TimeStep = t;

  t = (View[v0].TimeStep < View[v0].NbTimeStep-1) ? t+1 : 0; // Increment

  View[v0].RaiseZ += 0.01/View[v0].Max * t; // Raise view v0

  If (num == 3)
    // Resize the graphics when num == 3, to create 640x480 frames
    General.GraphicsWidth = General.MenuWidth + 640;
    General.GraphicsHeight = 480;
  EndIf

  frames = 50;

  // Loop on num2 from 1 to frames
  For num2 In {1:frames}

    // Incrementally rotate the scene
    General.RotationX += 10;
    General.RotationY = General.RotationX / 3;
    General.RotationZ += 0.1;

    // Sleep for 0.01 second
    Sleep 0.01;

    // Draw the scene (one could use `DrawForceChanged' instead to force the
    // reconstruction of the vertex arrays, e.g. if changing element clipping)
    Draw;

    If (num == 3)
      // Uncomment the following lines to save each frame to an image file (the
      // `Print' command saves the graphical window; the `Sprintf' function
      // permits to create the file names on the fly):

      // Print Sprintf("t8-%g.gif", num2);
      // Print Sprintf("t8-%g.ppm", num2);
      // Print Sprintf("t8-%g.jpg", num2);
    EndIf

  EndFor

  If(num == 3)
    // Here we could make a system call to generate a movie. For example, with
    // ffmpeg:

    // System "ffmpeg -i t8-%d.jpg t8.mpg"
  EndIf

EndFor

2.9 t9: Plugins

See t9.geo. Also available in C++ (t9.cpp), Python (t9.py), Julia (t9.jl) and Fortran (t9.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 9
//
//  Plugins
//
// -----------------------------------------------------------------------------

// Plugins can be added to Gmsh in order to extend its capabilities. For
// example, post-processing plugins can modify views, or create new views based
// on previously loaded views. Several default plugins are statically linked
// with Gmsh, e.g. Isosurface, CutPlane, CutSphere, Skin, Transform or Smooth.
//
// Plugins can be controlled in the same way as other options: either from the
// graphical interface (right click on the view button, then `Plugins'), or from
// the command file.

// Let us for example include a three-dimensional scalar view:

Include "view3.pos" ;

// We then set some options for the `Isosurface' plugin (which extracts an
// isosurface from a 3D scalar view), and run it:

Plugin(Isosurface).Value = 0.67 ; // Iso-value level
Plugin(Isosurface).View = 0 ; // Source view is View[0]
Plugin(Isosurface).Run ; // Run the plugin!

// We also set some options for the `CutPlane' plugin (which computes a section
// of a 3D view using the plane A*x+B*y+C*z+D=0), and then run it:

Plugin(CutPlane).A = 0 ;
Plugin(CutPlane).B = 0.2 ;
Plugin(CutPlane).C = 1 ;
Plugin(CutPlane).D = 0 ;
Plugin(CutPlane).View = 0 ;
Plugin(CutPlane).Run ;

// Add a title (By convention, for window coordinates a value greater than 99999
// represents the center. We could also use `General.GraphicsWidth / 2', but
// that would only center the string for the current window size.):

Plugin(Annotate).Text = "A nice title" ;
Plugin(Annotate).X = 1.e5;
Plugin(Annotate).Y = 50 ;
Plugin(Annotate).Font = "Times-BoldItalic" ;
Plugin(Annotate).FontSize = 28 ;
Plugin(Annotate).Align = "Center" ;
Plugin(Annotate).View = 0 ;
Plugin(Annotate).Run ;

Plugin(Annotate).Text = "(and a small subtitle)" ;
Plugin(Annotate).Y = 70 ;
Plugin(Annotate).Font = "Times-Roman" ;
Plugin(Annotate).FontSize = 12 ;
Plugin(Annotate).Run ;

// We finish by setting some options:

View[0].Light = 1;
View[0].IntervalsType = 1;
View[0].NbIso = 6;
View[0].SmoothNormals = 1;
View[1].IntervalsType = 2;
View[2].IntervalsType = 2;

2.10 t10: Mesh size fields

See t10.geo. Also available in C++ (t10.cpp), Python (t10.py), Julia (t10.jl) and Fortran (t10.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 10
//
//  Mesh size fields
//
// -----------------------------------------------------------------------------

// In addition to specifying target mesh sizes at the points of the geometry
// (see `t1.geo') or using a background mesh (see `t7.geo'), you can use general
// mesh size "Fields".

// Let's create a simple rectangular geometry
lc = .15;
Point(1) = {0.0,0.0,0,lc}; Point(2) = {1,0.0,0,lc};
Point(3) = {1,1,0,lc};     Point(4) = {0,1,0,lc};
Point(5) = {0.2,.5,0,lc};

Line(1) = {1,2}; Line(2) = {2,3}; Line(3) = {3,4}; Line(4) = {4,1};

Curve Loop(5) = {1,2,3,4}; Plane Surface(6) = {5};

// Say we would like to obtain mesh elements with size lc/30 near curve 2 and
// point 5, and size lc elsewhere. To achieve this, we can use two fields:
// "Distance", and "Threshold". We first define a Distance field (`Field[1]') on
// points 5 and on curve 2. This field returns the distance to point 5 and to
// (100 equidistant points on) curve 2.
Field[1] = Distance;
Field[1].PointsList = {5};
Field[1].CurvesList = {2};
Field[1].Sampling = 100;


// We then define a `Threshold' field, which uses the return value of the
// `Distance' field 1 in order to define a simple change in element size
// depending on the computed distances
//
// SizeMax -                     /------------------
//                              /
//                             /
//                            /
// SizeMin -o----------------/
//          |                |    |
//        Point         DistMin  DistMax
Field[2] = Threshold;
Field[2].InField = 1;
Field[2].SizeMin = lc / 30;
Field[2].SizeMax = lc;
Field[2].DistMin = 0.15;
Field[2].DistMax = 0.5;

// Say we want to modulate the mesh element sizes using a mathematical function
// of the spatial coordinates. We can do this with the MathEval field:
Field[3] = MathEval;
Field[3].F = "cos(4*3.14*x) * sin(4*3.14*y) / 10 + 0.101";

// We could also combine MathEval with values coming from other fields. For
// example, let's define a `Distance' field around point 1
Field[4] = Distance;
Field[4].PointsList = {1};

// We can then create a `MathEval' field with a function that depends on the
// return value of the `Distance' field 4, i.e., depending on the distance to
// point 1 (here using a cubic law, with minimum element size = lc / 100)
Field[5] = MathEval;
Field[5].F = Sprintf("F4^3 + %g", lc / 100);

// We could also use a `Box' field to impose a step change in element sizes
// inside a box
Field[6] = Box;
Field[6].VIn = lc / 15;
Field[6].VOut = lc;
Field[6].XMin = 0.3;
Field[6].XMax = 0.6;
Field[6].YMin = 0.3;
Field[6].YMax = 0.6;
Field[6].Thickness = 0.3;

// Many other types of fields are available: see the reference manual for a
// complete list. You can also create fields directly in the graphical user
// interface by selecting `Define->Size fields' in the `Mesh' module.

// Let's use the minimum of all the fields as the background mesh size field
Field[7] = Min;
Field[7].FieldsList = {2, 3, 5, 6};
Background Field = 7;

// To determine the size of mesh elements, Gmsh locally computes the minimum of
//
// 1) the size of the model bounding box;
// 2) if `Mesh.MeshSizeFromPoints' is set, the mesh size specified at
//    geometrical points;
// 3) if `Mesh.MeshSizeFromCurvature' is positive, the mesh size based on
//    curvature (the value specifying the number of elements per 2 * pi rad);
// 4) the background mesh size field;
// 5) any per-entity mesh size constraint.
//
// This value is then constrained in the interval [`Mesh.MeshSizeMin',
// `Mesh.MeshSizeMax'] and multiplied by `Mesh.MeshSizeFactor'. In addition,
// boundary mesh sizes are interpolated inside surfaces and/or volumes depending
// on the value of `Mesh.MeshSizeExtendFromBoundary' (which is set by default).
//
// When the element size is fully specified by a mesh size field (as it is in
// this example), it is thus often desirable to set

Mesh.MeshSizeExtendFromBoundary = 0;
Mesh.MeshSizeFromPoints = 0;
Mesh.MeshSizeFromCurvature = 0;

// This will prevent over-refinement due to small mesh sizes on the boundary.

// Finally, while the default "Frontal-Delaunay" 2D meshing algorithm
// (Mesh.Algorithm = 6) usually leads to the highest quality meshes, the
// "Delaunay" algorithm (Mesh.Algorithm = 5) will handle complex mesh size
// fields better - in particular size fields with large element size gradients:

Mesh.Algorithm = 5;

2.11 t11: Unstructured quadrangular meshes

See t11.geo. Also available in C++ (t11.cpp), Python (t11.py), Julia (t11.jl) and Fortran (t11.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 11
//
//  Unstructured quadrangular meshes
//
// -----------------------------------------------------------------------------

// We have seen in tutorials `t3.geo' and `t6.geo' that extruded and transfinite
// meshes can be "recombined" into quads, prisms or hexahedra by using the
// "Recombine" keyword. Unstructured meshes can be recombined in the same
// way. Let's define a simple geometry with an analytical mesh size field:

Point(1) = {-1.25, -.5, 0}; Point(2) = {1.25, -.5, 0};
Point(3) = {1.25, 1.25, 0};  Point(4) = {-1.25, 1.25, 0};

Line(1) = {1, 2}; Line(2) = {2, 3};
Line(3) = {3, 4}; Line(4) = {4, 1};

Curve Loop(4) = {1, 2, 3, 4}; Plane Surface(100) = {4};

Field[1] = MathEval;
Field[1].F = "0.01*(1.0+30.*(y-x*x)*(y-x*x) + (1-x)*(1-x))";
Background Field = 1;

// To generate quadrangles instead of triangles, we can simply add

Recombine Surface{100};

// If we'd had several surfaces, we could have used `Recombine Surface {:};'.
// Yet another way would be to specify the global option "Mesh.RecombineAll =
// 1;".

// The default recombination algorithm is called "Blossom": it uses a minimum
// cost perfect matching algorithm to generate fully quadrilateral meshes from
// triangulations. More details about the algorithm can be found in the
// following paper: J.-F. Remacle, J. Lambrechts, B. Seny, E. Marchandise,
// A. Johnen and C. Geuzaine, "Blossom-Quad: a non-uniform quadrilateral mesh
// generator using a minimum cost perfect matching algorithm", International
// Journal for Numerical Methods in Engineering 89, pp. 1102-1119, 2012.

// For even better 2D (planar) quadrilateral meshes, you can try the
// experimental "Frontal-Delaunay for quads" meshing algorithm, which is a
// triangulation algorithm that enables to create right triangles almost
// everywhere: J.-F. Remacle, F. Henrotte, T. Carrier-Baudouin, E. Bechet,
// E. Marchandise, C. Geuzaine and T. Mouton. A frontal Delaunay quad mesh
// generator using the L^inf norm. International Journal for Numerical Methods
// in Engineering, 94, pp. 494-512, 2013. Uncomment the following line to try
// the Frontal-Delaunay algorithms for quads:
//
// Mesh.Algorithm = 8;

// The default recombination algorithm might leave some triangles in the mesh,
// if recombining all the triangles leads to badly shaped quads. In such cases,
// to generate full-quad meshes, you can either subdivide the resulting hybrid
// mesh (with Mesh.SubdivisionAlgorithm = 1), or use the full-quad recombination
// algorithm, which will automatically perform a coarser mesh followed by
// recombination, smoothing and subdivision. Uncomment the following line to try
// the full-quad algorithm:
//
// Mesh.RecombinationAlgorithm = 2; // or 3

// Note that you could also apply the recombination algorithm and/or the
// subdivision step explicitly after meshing, as follows:
//
// Mesh 2;
// RecombineMesh;
// Mesh.SubdivisionAlgorithm = 1;
// RefineMesh;

2.12 t12: Cross-patch meshing with compounds

See t12.geo/ Also available in C++ (t12.cpp), Python (t12.py), Julia (t12.jl) and Fortran (t12.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 12
//
//  Cross-patch meshing with compounds
//
// -----------------------------------------------------------------------------

// "Compound" meshing constraints allow to generate meshes across surface
// boundaries, which can be useful e.g. for imported CAD models (e.g. STEP) with
// undesired small features.

// When a `Compound Curve' or `Compound Surface' meshing constraint is given,
// at mesh generation time Gmsh
//  1. meshes the underlying elementary geometrical entities, individually
//  2. creates a discrete entity that combines all the individual meshes
//  3. computes a discrete parametrization (i.e. a piece-wise linear mapping)
//     on this discrete entity
//  4. meshes the discrete entity using this discrete parametrization instead
//     of the underlying geometrical description of the underlying elementary
//     entities making up the compound
//  5. optionally, reclassifies the mesh elements and nodes on the original
//     entities

// Step 3. above can only be performed if the mesh resulting from the
// combination of the individual meshes can be reparametrized, i.e. if the shape
// is "simple enough". If the shape is not amenable to reparametrization, you
// should create a full mesh of the geometry and first re-classify it to
// generate patches amenable to reparametrization (see `t13.geo').

// The mesh of the individual entities performed in Step 1. should usually be
// finer than the desired final mesh; this can be controlled with the
// `Mesh.CompoundMeshSizeFactor' option.

// The optional reclassification on the underlying elementary entities in Step
// 5. is governed by the `Mesh.CompoundClassify' option.

lc = 0.1;

Point(1) = {0, 0, 0, lc};       Point(2) = {1, 0, 0, lc};
Point(3) = {1, 1, 0.5, lc};     Point(4) = {0, 1, 0.4, lc};
Point(5) = {0.3, 0.2, 0, lc};   Point(6) = {0, 0.01, 0.01, lc};
Point(7) = {0, 0.02, 0.02, lc}; Point(8) = {1, 0.05, 0.02, lc};
Point(9) = {1, 0.32, 0.02, lc};

Line(1) = {1, 2}; Line(2) = {2, 8}; Line(3) = {8, 9};
Line(4) = {9, 3}; Line(5) = {3, 4}; Line(6) = {4, 7};
Line(7) = {7, 6}; Line(8) = {6, 1}; Spline(9) = {7, 5, 9};
Line(10) = {6, 8};

Curve Loop(11) = {5, 6, 9, 4};     Surface(1) = {11};
Curve Loop(13) = {-9, 3, 10, 7}; Surface(5) = {13};
Curve Loop(15) = {-10, 2, 1, 8}; Surface(10) = {15};

// Treat curves 2, 3 and 4 as a single curve when meshing (i.e. mesh across
// points 6 and 7)
Compound Curve{2, 3, 4};

// Idem with curves 6, 7 and 8
Compound Curve{6, 7, 8};

// Treat surfaces 1, 5 and 10 as a single surface when meshing (i.e. mesh across
// curves 9 and 10)
Compound Surface{1, 5, 10};

2.13 t13: Remeshing an STL file without an underlying CAD model

See t13.geo. Also available in C++ (t13.cpp), Python (t13.py), Julia (t13.jl) and Fortran (t13.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 13
//
//  Remeshing an STL file without an underlying CAD model
//
// -----------------------------------------------------------------------------

// Let's merge an STL mesh that we would like to remesh.
Merge "t13_data.stl";

// We first classify ("color") the surfaces by splitting the original surface
// along sharp geometrical features. This will create new discrete surfaces,
// curves and points.

DefineConstant[
  // Angle between two triangles above which an edge is considered as sharp
  angle = {40, Min 20, Max 120, Step 1,
    Name "Parameters/Angle for surface detection"},
  // For complex geometries, patches can be too complex, too elongated or too
  // large to be parametrized; setting the following option will force the
  // creation of patches that are amenable to reparametrization:
  forceParametrizablePatches = {0, Choices{0,1},
    Name "Parameters/Create surfaces guaranteed to be parametrizable"},
  // For open surfaces include the boundary edges in the classification process:
  includeBoundary = 1,
  // Force curves to be split on given angle:
  curveAngle = 180
];
ClassifySurfaces{angle * Pi/180, includeBoundary, forceParametrizablePatches,
                 curveAngle * Pi / 180};

// Create a geometry for all the discrete curves and surfaces in the mesh, by
// computing a parametrization for each one
CreateGeometry;

// In batch mode the two steps above can be performed with `gmsh t13.stl
// -reparam 40', which will save `t13.msh' containing the parametrizations, and
// which can thus subsequently be remeshed.

// Note that if a CAD model (e.g. as a STEP file, see `t20.geo') is available
// instead of an STL mesh, it is usually better to use that CAD model instead of
// the geometry created by reparametrizing the mesh. Indeed, CAD geometries will
// in general be more accurate, with smoother parametrizations, and will lead to
// more efficient and higher quality meshing. Discrete surface remeshing in Gmsh
// is optimized to handle dense STL meshes coming from e.g. imaging systems
// where no CAD is available; it is less well suited for the poor quality STL
// triangulations (optimized for size, with e.g. very elongated triangles) that
// are usually generated by CAD tools for e.g. 3D printing.

// Create a volume as usual
Surface Loop(1) = Surface{:};
Volume(1) = {1};

// We specify element sizes imposed by a size field, just because we can :-)
funny = DefineNumber[0, Choices{0,1},
  Name "Parameters/Apply funny mesh size field?" ];

Field[1] = MathEval;
If(funny)
  Field[1].F = "2*Sin((x+y)/5) + 3";
Else
  Field[1].F = "4";
EndIf
Background Field = 1;

2.14 t14: Homology and cohomology computation

See t14.geo. Also available in C++ (t14.cpp), Python (t14.py), Julia (t14.jl) and Fortran (t14.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 14
//
//  Homology and cohomology computation
//
// -----------------------------------------------------------------------------

// Homology computation in Gmsh finds representative chains of (relative)
// (co)homology space bases using a mesh of a model.  The representative basis
// chains are stored in the mesh as physical groups of Gmsh, one for each chain.

// Create an example geometry

m = 0.5; // mesh size
h = 2; // height in the z-direction

Point(1) = {0, 0, 0, m};   Point(2) = {10, 0, 0, m};
Point(3) = {10, 10, 0, m}; Point(4) = {0, 10, 0, m};
Point(5) = {4, 4, 0, m};   Point(6) = {6, 4, 0, m};
Point(7) = {6, 6, 0, m};   Point(8) = {4, 6, 0, m};

Point(9) = {2, 0, 0, m};   Point(10) = {8, 0, 0, m};
Point(11) = {2, 10, 0, m}; Point(12) = {8, 10, 0, m};

Line(1) = {1, 9};  Line(2) = {9, 10}; Line(3) = {10, 2};
Line(4) = {2, 3};  Line(5) = {3, 12}; Line(6) = {12, 11};
Line(7) = {11, 4}; Line(8) = {4, 1};  Line(9) = {5, 6};
Line(10) = {6, 7}; Line(11) = {7, 8}; Line(12) = {8, 5};

Curve Loop(13) = {6, 7, 8, 1, 2, 3, 4, 5};
Curve Loop(14) = {11, 12, 9, 10};
Plane Surface(15) = {13, 14};

e() = Extrude {0, 0, h}{ Surface{15}; };

// Create physical groups, which are used to define the domain of the
// (co)homology computation and the subdomain of the relative (co)homology
// computation.

// Whole domain
Physical Volume(1) = {e(1)};

// Four "terminals" of the model
Physical Surface(70) = {e(3)};
Physical Surface(71) = {e(5)};
Physical Surface(72) = {e(7)};
Physical Surface(73) = {e(9)};

// Whole domain surface
bnd() = Abs(Boundary{ Volume{e(1)}; });
Physical Surface(80) = bnd();

// Complement of the domain surface with respect to the four terminals
bnd() -= {e(3), e(5), e(7), e(9)};
Physical Surface(75) = bnd();

// Find bases for relative homology spaces of the domain modulo the four
// terminals.
Homology {{1}, {70, 71, 72, 73}};

// Find homology space bases isomorphic to the previous bases: homology spaces
// modulo the non-terminal domain surface, a.k.a the thin cuts.
Homology {{1}, {75}};

// Find cohomology space bases isomorphic to the previous bases: cohomology
// spaces of the domain modulo the four terminals, a.k.a the thick cuts.
Cohomology {{1}, {70, 71, 72, 73}};

// More examples:
//  Homology {1};
//  Homology;
//  Homology {{1}, {80}};
//  Homology {{}, {80}};

// For more information, see M. Pellikka, S. Suuriniemi, L. Kettunen and
// C. Geuzaine. Homology and cohomology computation in finite element
// modeling. SIAM Journal on Scientific Computing 35(5), pp. 1195-1214, 2013.

2.15 t15: Embedded points, lines and surfaces

See t15.geo. Also available in C++ (t15.cpp), Python (t15.py), Julia (t15.jl) and Fortran (t15.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 15
//
//  Embedded points, lines and surfaces
//
// -----------------------------------------------------------------------------

// By default, across geometrical dimensions meshes generated by Gmsh are only
// conformal if lower dimensional entities are on the boundary of higher
// dimensional ones (i.e. if points, curves or surfaces are part of the boundary
// of volumes).

// Embedding constraints allow to force a mesh to be conformal to other lower
// dimensional entities.

// We start one again by including the first tutorial:
Include "t1.geo";

// We change the mesh size to generate coarser mesh
lc = lc * 4;
MeshSize {1:4} = lc;

// We define a new point
Point(5) = {0.02, 0.02, 0, lc};

// One can force this point to be included ("embedded") in the 2D mesh, using
// the `Point In Surface' command:
Point{5} In Surface{1};

// In the same way, one can force a curve to be embedded in the 2D mesh using
// the `Curve in Surface' command:
Point(6) = {0.02, 0.12, 0, lc};
Point(7) = {0.04, 0.18, 0, lc};
Line(5) = {6, 7};
Curve{5} In Surface{1};

// One can also embed points and curves in a volume using the `Curve/Point In
// Volume' commands:
Extrude {0, 0, 0.1}{ Surface {1}; }

p = newp;
Point(p) = {0.07, 0.15, 0.025, lc};
Point{p} In Volume {1};

l = newc;
Point(p+1) = {0.025, 0.15, 0.025, lc};
Line(l) = {7, p+1};
Curve{l} In Volume {1};

// Finally, one can also embed a surface in a volume using the `Surface In
// Volume' command:
Point(p+2) = {0.02, 0.12, 0.05, lc};
Point(p+3) = {0.04, 0.12, 0.05, lc};
Point(p+4) = {0.04, 0.18, 0.05, lc};
Point(p+5) = {0.02, 0.18, 0.05, lc};
Line(l+1) = {p+2, p+3};
Line(l+2) = {p+3, p+4};
Line(l+3) = {p+4, p+5};
Line(l+4) = {p+5, p+2};
ll = newcl;
Curve Loop(ll) = {l+1:l+4};
s = news;
Plane Surface(s) = {ll};
Surface{s} In Volume {1};

// Note that with the OpenCASCADE kernel (see `t16.geo'), when the
// `BooleanFragments' command is applied to entities of different dimensions,
// the lower dimensional entities will be autmatically embedded in the higher
// dimensional entities if necessary.

Physical Point("Embedded point") = {p};
Physical Curve("Embdded curve") = {l};
Physical Surface("Embedded surface") = {s};
Physical Volume("Volume") = {1};

2.16 t16: Constructive Solid Geometry, OpenCASCADE geometry kernel

See t16.geo. Also available in C++ (t16.cpp), C (t16.c), Python (t16.py), Julia (t16.jl) and Fortran (t16.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 16
//
//  Constructive Solid Geometry, OpenCASCADE geometry kernel
//
// -----------------------------------------------------------------------------

// Instead of constructing a model in a bottom-up fashion with Gmsh's built-in
// geometry kernel, starting with version 3 Gmsh allows you to directly use
// alternative geometry kernels. Here we use the OpenCASCADE kernel:

SetFactory("OpenCASCADE");

// Let's build the same model as in `t5.geo', but using constructive solid
// geometry.

// We first create two cubes:
Box(1) = {0,0,0, 1,1,1};
Box(2) = {0,0,0, 0.5,0.5,0.5};

// We apply a boolean difference to create the "cube minus one eighth" shape:
BooleanDifference(3) = { Volume{1}; Delete; }{ Volume{2}; Delete; };

// Boolean operations with OpenCASCADE always create new entities. Adding
// `Delete' in the arguments allows to automatically delete the original
// entities.

// We then create the five spheres:
x = 0 ; y = 0.75 ; z = 0 ; r = 0.09 ;
For t In {1:5}
  x += 0.166 ;
  z += 0.166 ;
  Sphere(3 + t) = {x,y,z,r};
  Physical Volume(t) = {3 + t};
EndFor

// If we had wanted five empty holes we would have used `BooleanDifference'
// again. Here we want five spherical inclusions, whose mesh should be conformal
// with the mesh of the cube: we thus use `BooleanFragments', which intersects
// all volumes in a conformal manner (without creating duplicate interfaces):
v() = BooleanFragments{ Volume{3}; Delete; }{ Volume{3 + 1 : 3 + 5}; Delete; };

// When the boolean operation leads to simple modifications of entities, and if
// one deletes the original entities with `Delete', Gmsh tries to assign the
// same tag to the new entities. (This behavior is governed by the
// `Geometry.OCCBooleanPreserveNumbering' option.)

// Here the `Physical Volume' definitions made above will thus still work, as
// the five spheres (volumes 4, 5, 6, 7 and 8), which will be deleted by the
// fragment operations, will be recreated identically (albeit with new surfaces)
// with the same tags.

// The tag of the cube will change though, so we need to access it
// programmatically:
Physical Volume(10) = v(#v()-1);

// Creating entities using constructive solid geometry is very powerful, but can
// lead to practical issues for e.g. setting mesh sizes at points, or
// identifying boundaries.

// To identify points or other bounding entities you can take advantage of the
// `PointfsOf' (a special case of the more general `Boundary' command) and the
// `In BoundingBox' commands.
lcar1 = .1;
lcar2 = .0005;
lcar3 = .055;
eps = 1e-3;

// Assign a mesh size to all the points of all the volumes:
MeshSize{ PointsOf{ Volume{:}; } } = lcar1;

// Override this constraint on the points of the five spheres:
MeshSize{ PointsOf{ Volume{3 + 1 : 3 + 5}; } } = lcar3;

// Select the corner point by searching for it geometrically:
p() = Point In BoundingBox{0.5-eps, 0.5-eps, 0.5-eps,
                           0.5+eps, 0.5+eps, 0.5+eps};
MeshSize{ p() } = lcar2;

// Additional examples created with the OpenCASCADE geometry kernel are
// available in `t18.geo', `t19.geo' and `t20.geo', as well as in the
// `examples/boolean' directory.

2.17 t17: Anisotropic background mesh

See t17.geo. Also available in C++ (t17.cpp), Python (t17.py), Julia (t17.jl) and Fortran (t17.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 17
//
//  Anisotropic background mesh
//
// -----------------------------------------------------------------------------

// As seen in `t7.geo', mesh sizes can be specified very accurately by providing
// a background mesh, i.e., a post-processing view that contains the target mesh
// sizes.

// Here, the background mesh is represented as a metric tensor field defined on
// a square. One should use bamg as 2d mesh generator to enable anisotropic
// meshes in 2D.

SetFactory("OpenCASCADE");

// Create a square
Rectangle(1) = {-2, -2, 0, 4, 4};

// Merge a post-processing view containing the target anisotropic mesh sizes
Merge "t17_bgmesh.pos";

// Apply the view as the current background mesh
Background Mesh View[0];

// Use bamg
Mesh.SmoothRatio = 3;
Mesh.AnisoMax = 1000;
Mesh.Algorithm = 7;

2.18 t18: Periodic meshes

See t18.geo. Also available in C++ (t18.cpp), Python (t18.py), Julia (t18.jl) and Fortran (t18.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 18
//
//  Periodic meshes
//
// -----------------------------------------------------------------------------

// Periodic meshing constraints can be imposed on surfaces and curves.

// Let's use the OpenCASCADE geometry kernel to build two geometries.

SetFactory("OpenCASCADE");

// The first geometry is very simple: a unit cube with a non-uniform mesh size
// constraint (set on purpose to be able to verify visually that the periodicity
// constraint works!):

Box(1) = {0, 0, 0, 1, 1, 1};
MeshSize {:} = 0.1;
MeshSize {1} = 0.02;

// To impose that the mesh on surface 2 (the right side of the cube) should
// match the mesh from surface 1 (the left side), the following periodicity
// constraint is set:
Periodic Surface {2} = {1} Translate {1, 0, 0};

// During mesh generation, the mesh on surface 2 will be created by copying the
// mesh from surface 1.  Periodicity constraints can be specified with a
// `Translation', a `Rotation' or a general `Affine' transform.

// Multiple periodicities can be imposed in the same way:
Periodic Surface {6} = {5} Translate {0, 0, 1};
Periodic Surface {4} = {3} Translate {0, 1, 0};

// For more complicated cases, finding the corresponding surfaces by hand can be
// tedious, especially when geometries are created through solid
// modelling. Let's construct a slightly more complicated geometry.

// We start with a cube and some spheres:
Box(10) = {2, 0, 0, 1, 1, 1};
x = 2-0.3; y = 0; z = 0;
Sphere(11) = {x, y, z, 0.35};
Sphere(12) = {x+1, y, z, 0.35};
Sphere(13) = {x, y+1, z, 0.35};
Sphere(14) = {x, y, z+1, 0.35};
Sphere(15) = {x+1, y+1, z, 0.35};
Sphere(16) = {x, y+1, z+1, 0.35};
Sphere(17) = {x+1, y, z+1, 0.35};
Sphere(18) = {x+1, y+1, z+1, 0.35};

// We first fragment all the volumes, which will leave parts of spheres
// protruding outside the cube:
v() = BooleanFragments { Volume{10}; Delete; }{ Volume{11:18}; Delete; };

// Ask OpenCASCADE to compute more accurate bounding boxes of entities using the
// STL mesh:
Geometry.OCCBoundsUseStl = 1;

// We then retrieve all the volumes in the bounding box of the original cube,
// and delete all the parts outside it:
eps = 1e-3;
vin() = Volume In BoundingBox {2-eps,-eps,-eps, 2+1+eps,1+eps,1+eps};
v() -= vin();
Recursive Delete{ Volume{v()}; }

// We now set a non-uniform mesh size constraint (again to check results
// visually):
MeshSize { PointsOf{ Volume{vin()}; }} = 0.1;
p() = Point In BoundingBox{2-eps, -eps, -eps, 2+eps, eps, eps};
MeshSize {p()} = 0.001;

// We now identify corresponding surfaces on the left and right sides of the
// geometry automatically.

// First we get all surfaces on the left:
Sxmin() = Surface In BoundingBox{2-eps, -eps, -eps, 2+eps, 1+eps, 1+eps};

For i In {0:#Sxmin()-1}
  // Then we get the bounding box of each left surface
  bb() = BoundingBox Surface { Sxmin(i) };
  // We translate the bounding box to the right and look for surfaces inside it:
  Sxmax() = Surface In BoundingBox { bb(0)-eps+1, bb(1)-eps, bb(2)-eps,
                                     bb(3)+eps+1, bb(4)+eps, bb(5)+eps };
  // For all the matches, we compare the corresponding bounding boxes...
  For j In {0:#Sxmax()-1}
    bb2() = BoundingBox Surface { Sxmax(j) };
    bb2(0) -= 1;
    bb2(3) -= 1;
    // ...and if they match, we apply the periodicity constraint
    If(Fabs(bb2(0)-bb(0)) < eps && Fabs(bb2(1)-bb(1)) < eps &&
       Fabs(bb2(2)-bb(2)) < eps && Fabs(bb2(3)-bb(3)) < eps &&
       Fabs(bb2(4)-bb(4)) < eps && Fabs(bb2(5)-bb(5)) < eps)
      Periodic Surface {Sxmax(j)} = {Sxmin(i)} Translate {1,0,0};
    EndIf
  EndFor
EndFor

2.19 t19: Thrusections, fillets, pipes, mesh size from curvature

See t19.geo. Also available in C++ (t19.cpp), Python (t19.py), Julia (t19.jl) and Fortran (t19.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 19
//
//  Thrusections, fillets, pipes, mesh size from curvature
//
// -----------------------------------------------------------------------------

// The OpenCASCADE geometry kernel supports several useful features for solid
// modelling.

SetFactory("OpenCASCADE");

// Volumes can be constructed from (closed) curve loops thanks to the
// `ThruSections' command
Circle(1) = {0,0,0, 0.5};       Curve Loop(1) = 1;
Circle(2) = {0.1,0.05,1, 0.1};  Curve Loop(2) = 2;
Circle(3) = {-0.1,-0.1,2, 0.3}; Curve Loop(3) = 3;
ThruSections(1) = {1:3};

// With `Ruled ThruSections' you can force the use of ruled surfaces:
Circle(11) = {2+0,0,0, 0.5};      Curve Loop(11) = 11;
Circle(12) = {2+0.1,0.05,1, 0.1}; Curve Loop(12) = 12;
Circle(13) = {2-0.1,-0.1,2, 0.3}; Curve Loop(13) = 13;
Ruled ThruSections(11) = {11:13};

// We copy the first volume, and fillet all its edges:
v() = Translate{4, 0, 0} { Duplicata{ Volume{1}; } };
f() = Abs(Boundary{ Volume{v(0)}; });
e() = Unique(Abs(Boundary{ Surface{f()}; }));
Fillet{v(0)}{e()}{0.1}

// OpenCASCADE also allows general extrusions along a smooth path. Let's first
// define a spline curve:
nturns = 1;
npts = 20;
r = 1;
h = 1 * nturns;
For i In {0 : npts - 1}
  theta = i * 2*Pi*nturns/npts;
  Point(1000 + i) = {r * Cos(theta), r * Sin(theta), i * h/npts};
EndFor
Spline(1000) = {1000 : 1000 + npts - 1};

// A wire is like a curve loop, but open:
Wire(1000) = {1000};

// We define the shape we would like to extrude along the spline (a disk):
Disk(1000) = {1,0,0, 0.2};
Rotate {{1, 0, 0}, {0, 0, 0}, Pi/2} { Surface{1000}; }

// We extrude the disk along the spline to create a pipe:
Extrude { Surface{1000}; } Using Wire {1000}

// We delete the source surface, and increase the number of sub-edges for a
// nicer display of the geometry:
Delete{ Surface{1000}; }
Geometry.NumSubEdges = 1000;

// We can activate the calculation of mesh element sizes based on curvature
// (here with a target of 20 elements per 2*Pi radians):
Mesh.MeshSizeFromCurvature = 20;

// We can constraint the min and max element sizes to stay within reasonnable
// values (see `t10.geo' for more details):
Mesh.MeshSizeMin = 0.001;
Mesh.MeshSizeMax = 0.3;

2.20 t20: STEP import and manipulation, geometry partitioning

See t20.geo. Also available in C++ (t20.cpp), Python (t20.py), Julia (t20.jl) and Fortran (t20.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 20
//
//  STEP import and manipulation, geometry partitioning
//
// -----------------------------------------------------------------------------

// The OpenCASCADE geometry kernel allows to import STEP files and to modify
// them. In this tutorial we will load a STEP geometry and partition it into
// slices.

SetFactory("OpenCASCADE");

// Load a STEP file (using `ShapeFromFile' instead of `Merge' allows to directly
// retrieve the tags of the highest dimensional imported entities):
v() = ShapeFromFile("t20_data.step");

// If we had specified
//
// Geometry.OCCTargetUnit = "M";
//
// before merging the STEP file, OpenCASCADE would have converted the units to
// meters (instead of the default, which is millimeters).

// Get the bounding box of the volume:
bbox() = BoundingBox Volume{v()};
xmin = bbox(0);
ymin = bbox(1);
zmin = bbox(2);
xmax = bbox(3);
ymax = bbox(4);
zmax = bbox(5);

// We want to slice the model into N slices, and either keep the volume slices
// or just the surfaces obtained by the cutting:
DefineConstant[
  N = {5, Min 2, Max 100, Step 1, Name "Parameters/0Number of slices"}
  dir = {0, Choices{0="X", 1="Y", 2="Z"}, Name "Parameters/1Direction"}
  surf = {0, Choices{0, 1}, Name "Parameters/2Keep only surfaces?"}
];

dx = (xmax - xmin);
dy = (ymax - ymin);
dz = (zmax - zmin);
L = (dir == 0) ? dz : dx;
H = (dir == 1) ? dz : dy;

// Create the first cutting plane:
s() = {news};
Rectangle(s(0)) = {xmin, ymin, zmin, L, H};
If(dir == 0)
  Rotate{ {0, 1, 0}, {xmin, ymin, zmin}, -Pi/2 } { Surface{s(0)}; }
ElseIf(dir == 1)
  Rotate{ {1, 0, 0}, {xmin, ymin, zmin}, Pi/2 } { Surface{s(0)}; }
EndIf
tx = (dir == 0) ? dx / N : 0;
ty = (dir == 1) ? dy / N : 0;
tz = (dir == 2) ? dz / N : 0;
Translate{tx, ty, tz} { Surface{s(0)}; }

// Create the other cutting planes:
For i In {1:N-2}
  s() += Translate{i * tx, i * ty, i * tz} { Duplicata{ Surface{s(0)}; } };
EndFor

// Fragment (i.e. intersect) the volume with all the cutting planes:
BooleanFragments{ Volume{v()}; Delete; }{ Surface{s()}; Delete; }

// Now remove all the surfaces (and their bounding entities) that are not on the
// boundary of a volume, i.e. the parts of the cutting planes that "stick out"
// of the volume:
Recursive Delete { Surface{:}; }

If(surf)
  // If we want to only keep the surfaces, retrieve the surfaces in bounding
  // boxes around the cutting planes...
  eps = 1e-4;
  s() = {};
  For i In {1:N-1}
    xx = (dir == 0) ? xmin : xmax;
    yy = (dir == 1) ? ymin : ymax;
    zz = (dir == 2) ? zmin : zmax;
    s() += Surface In BoundingBox
      {xmin - eps + i * tx, ymin - eps + i * ty, zmin - eps + i * tz,
       xx + eps + i * tx, yy + eps + i * ty, zz + eps + i * tz};
  EndFor
  // ...and remove all the other entities:
  dels = Surface{:};
  dels -= s();
  Delete { Volume{:}; Surface{dels()}; Curve{:}; Point{:}; }
EndIf

// Finally, let's specify a global mesh size:
Mesh.MeshSizeMin = 3;
Mesh.MeshSizeMax = 3;

// To partition the mesh instead of the geometry, see `t21.geo'.

2.21 t21: Mesh partitioning

See t21.geo. Also available in C++ (t21.cpp), Python (t21.py), Julia (t21.jl) and Fortran (t21.f90).

// -----------------------------------------------------------------------------
//
//  Gmsh GEO tutorial 21
//
//  Mesh partitioning
//
// -----------------------------------------------------------------------------

// Gmsh can partition meshes using different algorithms, e.g. the graph
// partitioner Metis or the `SimplePartition' plugin. For all the partitioning
// algorithms, the relationship between mesh elements and mesh partitions is
// encoded through the creation of new (discrete) elementary entities, called
// "partition entities".
//
// Partition entities behave exactly like other discrete elementary entities;
// the only difference is that they keep track of both a mesh partition index
// and their parent elementary entity.
//
// The major advantage of this approach is that it allows to maintain a full
// boundary representation of the partition entities, which Gmsh creates
// automatically if `Mesh.PartitionCreateTopology' is set.

// Let us start by creating a simple geometry with two adjacent squares sharing
// an edge:
SetFactory("OpenCASCADE");
Rectangle(1) = {0, 0, 0, 1, 1};
Rectangle(2) = {1, 0, 0, 1, 1};
BooleanFragments{ Surface{1}; Delete; }{ Surface{2}; Delete; }
MeshSize {:} = 0.05;

// We create one physical group for each square, and we mesh the resulting
// geometry:
Physical Surface("Left", 100) = 1;
Physical Surface("Right", 200) = 2;
Mesh 2;

// We now define several constants to fine-tune how the mesh will be partitioned
DefineConstant[
  partitioner = {0, Choices{0="Metis", 1="SimplePartition"},
    Name "Parameters/0Mesh partitioner"}
  N = {3, Min 1, Max 256, Step 1,
    Name "Parameters/1Number of partitions"}
  topology = {1, Choices{0, 1},
    Name "Parameters/2Create partition topology (BRep)?"}
  ghosts = {0, Choices{0, 1},
    Name "Parameters/3Create ghost cells?"}
  physicals = {0, Choices{0, 1},
    Name "Parameters/3Create new physical groups?"}
  write = {1, Choices {0, 1},
    Name "Parameters/3Write file to disk?"}
  split = {0, Choices {0, 1},
    Name "Parameters/4Write one file per partition?"}
];

// Should we create the boundary representation of the partition entities?
Mesh.PartitionCreateTopology = topology;

// Should we create ghost cells?
Mesh.PartitionCreateGhostCells = ghosts;

// Should we automatically create new physical groups on the partition entities?
Mesh.PartitionCreatePhysicals = physicals;

// Should we keep backward compatibility with pre-Gmsh 4, e.g. to save the mesh
// in MSH2 format?
Mesh.PartitionOldStyleMsh2 = 0;

// Should we save one mesh file per partition?
Mesh.PartitionSplitMeshFiles = split;

If (partitioner == 0)
  // Use Metis to create N partitions
  PartitionMesh N;
  // Several options can be set to control Metis: `Mesh.MetisAlgorithm' (1:
  // Recursive, 2: K-way), `Mesh.MetisObjective' (1: min. edge-cut, 2:
  // min. communication volume), `Mesh.PartitionTriWeight' (weight of
  // triangles), `Mesh.PartitionQuadWeight' (weight of quads), ...
Else
  // Use the `SimplePartition' plugin to create chessboard-like partitions
  Plugin(SimplePartition).NumSlicesX = N;
  Plugin(SimplePartition).NumSlicesY = 1;
  Plugin(SimplePartition).NumSlicesZ = 1;
  Plugin(SimplePartition).Run;
EndIf

// Save mesh file (or files, if `Mesh.PartitionSplitMeshFiles' is set):
If(write)
  Save "t21.msh";
EndIf

2.22 x1: Geometry and mesh data

See x1.py. Also available in C++ (x1.cpp) and Julia (x1.jl).

# -----------------------------------------------------------------------------
#
#  Gmsh Python extended tutorial 1
#
#  Geometry and mesh data
#
# -----------------------------------------------------------------------------

# The Python API allows to do much more than what can be done in .geo
# files. These additional features are introduced gradually in the extended
# tutorials, starting with `x1.py'.

# In this first extended tutorial, we start by using the API to access basic
# geometrical and mesh data.

import gmsh
import sys

gmsh.initialize()

if len(sys.argv) > 1 and sys.argv[1][0] != '-':
    # If an argument is provided, handle it as a file that Gmsh can read, e.g. a
    # mesh file in the MSH format (`python x1.py file.msh')
    gmsh.open(sys.argv[1])
else:
    # Otherwise, create and mesh a simple geometry
    gmsh.model.occ.addCone(1, 0, 0, 1, 0, 0, 0.5, 0.1)
    gmsh.model.occ.synchronize()
    gmsh.model.mesh.generate()

# Print the model name and dimension:
print('Model ' + gmsh.model.getCurrent() + ' (' +
      str(gmsh.model.getDimension()) + 'D)')

# Geometrical data is made of elementary model `entities', called `points'
# (entities of dimension 0), `curves' (entities of dimension 1), `surfaces'
# (entities of dimension 2) and `volumes' (entities of dimension 3). As we have
# seen in the other Python tutorials, elementary model entities are identified
# by their dimension and by a `tag': a strictly positive identification
# number. Model entities can be either CAD entities (from the built-in `geo'
# kernel or from the OpenCASCADE `occ' kernel) or `discrete' entities (defined
# by a mesh). `Physical groups' are collections of model entities and are also
# identified by their dimension and by a tag.

# Get all the elementary entities in the model, as a vector of (dimension, tag)
# pairs:
entities = gmsh.model.getEntities()

for e in entities:
    # Dimension and tag of the entity:
    dim = e[0]
    tag = e[1]

    # Mesh data is made of `elements' (points, lines, triangles, ...), defined
    # by an ordered list of their `nodes'. Elements and nodes are identified by
    # `tags' as well (strictly positive identification numbers), and are stored
    # ("classified") in the model entity they discretize. Tags for elements and
    # nodes are globally unique (and not only per dimension, like entities).

    # A model entity of dimension 0 (a geometrical point) will contain a mesh
    # element of type point, as well as a mesh node. A model curve will contain
    # line elements as well as its interior nodes, while its boundary nodes will
    # be stored in the bounding model points. A model surface will contain
    # triangular and/or quadrangular elements and all the nodes not classified
    # on its boundary or on its embedded entities. A model volume will contain
    # tetrahedra, hexahedra, etc. and all the nodes not classified on its
    # boundary or on its embedded entities.

    # Get the mesh nodes for the entity (dim, tag):
    nodeTags, nodeCoords, nodeParams = gmsh.model.mesh.getNodes(dim, tag)

    # Get the mesh elements for the entity (dim, tag):
    elemTypes, elemTags, elemNodeTags = gmsh.model.mesh.getElements(dim, tag)

    # Elements can also be obtained by type, by using `getElementTypes()'
    # followed by `getElementsByType()'.

    # Let's print a summary of the information available on the entity and its
    # mesh.

    # * Type and name of the entity:
    type = gmsh.model.getType(dim, tag)
    name = gmsh.model.getEntityName(dim, tag)
    if len(name): name += ' '
    print("Entity " + name + str(e) + " of type " + type)

    # * Number of mesh nodes and elements:
    numElem = sum(len(i) for i in elemTags)
    print(" - Mesh has " + str(len(nodeTags)) + " nodes and " + str(numElem) +
          " elements")

    # * Upward and downward adjacencies:
    up, down = gmsh.model.getAdjacencies(dim, tag)
    if len(up):
        print(" - Upward adjacencies: " + str(up))
    if len(down):
        print(" - Downward adjacencies: " + str(down))

    # * Does the entity belong to physical groups?
    physicalTags = gmsh.model.getPhysicalGroupsForEntity(dim, tag)
    if len(physicalTags):
        s = ''
        for p in physicalTags:
            n = gmsh.model.getPhysicalName(dim, p)
            if n: n += ' '
            s += n + '(' + str(dim) + ', ' + str(p) + ') '
        print(" - Physical groups: " + s)

    # * Is the entity a partition entity? If so, what is its parent entity?
    partitions = gmsh.model.getPartitions(dim, tag)
    if len(partitions):
        print(" - Partition tags: " + str(partitions) + " - parent entity " +
              str(gmsh.model.getParent(dim, tag)))

    # * List all types of elements making up the mesh of the entity:
    for t in elemTypes:
        name, dim, order, numv, parv, _ = gmsh.model.mesh.getElementProperties(
            t)
        print(" - Element type: " + name + ", order " + str(order) + " (" +
              str(numv) + " nodes in param coord: " + str(parv) + ")")

# Launch the GUI to see the model:
if '-nopopup' not in sys.argv:
    gmsh.fltk.run()

# We can use this to clear all the model data:
gmsh.clear()

gmsh.finalize()

2.23 x2: Mesh import, discrete entities, hybrid models, terrain meshing

See x2.py. Also available in C++ (x2.cpp) and Julia (x2.jl).

# -----------------------------------------------------------------------------
#
#  Gmsh Python extended tutorial 2
#
#  Mesh import, discrete entities, hybrid models, terrain meshing
#
# -----------------------------------------------------------------------------

import gmsh
import sys
import math

# The API can be used to import a mesh without reading it from a file, by
# creating nodes and elements on the fly and storing them in model
# entities. These model entities can be existing CAD entities, or can be
# discrete entities, entirely defined by the mesh.
#
# Discrete entities can be reparametrized (see `t13.py') so that they can be
# remeshed later on; and they can also be combined with built-in CAD entities to
# produce hybrid models.
#
# We combine all these features in this tutorial to perform terrain meshing,
# where the terrain is described by a discrete surface (that we then
# reparametrize) combined with a CAD representation of the underground.

gmsh.initialize()

gmsh.model.add("x2")

# We will create the terrain surface mesh from N x N input data points:
N = 100


# Helper function to return a node tag given two indices i and j:
def tag(i, j):
    return (N + 1) * i + j + 1


# The x, y, z coordinates of all the nodes:
coords = []

# The tags of the corresponding nodes:
nodes = []

# The connectivities of the triangle elements (3 node tags per triangle) on the
# terrain surface:
tris = []

# The connectivities of the line elements on the 4 boundaries (2 node tags
# for each line element):
lin = [[], [], [], []]

# The connectivities of the point elements on the 4 corners (1 node tag for each
# point element):
pnt = [tag(0, 0), tag(N, 0), tag(N, N), tag(0, N)]

for i in range(N + 1):
    for j in range(N + 1):
        nodes.append(tag(i, j))
        coords.extend([
            float(i) / N,
            float(j) / N, 0.05 * math.sin(10 * float(i + j) / N)
        ])
        if i > 0 and j > 0:
            tris.extend([tag(i - 1, j - 1), tag(i, j - 1), tag(i - 1, j)])
            tris.extend([tag(i, j - 1), tag(i, j), tag(i - 1, j)])
        if (i == 0 or i == N) and j > 0:
            lin[3 if i == 0 else 1].extend([tag(i, j - 1), tag(i, j)])
        if (j == 0 or j == N) and i > 0:
            lin[0 if j == 0 else 2].extend([tag(i - 1, j), tag(i, j)])

# Create 4 discrete points for the 4 corners of the terrain surface:
for i in range(4):
    gmsh.model.addDiscreteEntity(0, i + 1)
gmsh.model.setCoordinates(1, 0, 0, coords[3 * tag(0, 0) - 1])
gmsh.model.setCoordinates(2, 1, 0, coords[3 * tag(N, 0) - 1])
gmsh.model.setCoordinates(3, 1, 1, coords[3 * tag(N, N) - 1])
gmsh.model.setCoordinates(4, 0, 1, coords[3 * tag(0, N) - 1])

# Create 4 discrete bounding curves, with their boundary points:
for i in range(4):
    gmsh.model.addDiscreteEntity(1, i + 1, [i + 1, i + 2 if i < 3 else 1])

# Create one discrete surface, with its bounding curves:
gmsh.model.addDiscreteEntity(2, 1, [1, 2, -3, -4])

# Add all the nodes on the surface (for simplicity... see below):
gmsh.model.mesh.addNodes(2, 1, nodes, coords)

# Add point elements on the 4 points, line elements on the 4 curves, and
# triangle elements on the surface:
for i in range(4):
    # Type 15 for point elements:
    gmsh.model.mesh.addElementsByType(i + 1, 15, [], [pnt[i]])
    # Type 1 for 2-node line elements:
    gmsh.model.mesh.addElementsByType(i + 1, 1, [], lin[i])
# Type 2 for 3-node triangle elements:
gmsh.model.mesh.addElementsByType(1, 2, [], tris)

# Reclassify the nodes on the curves and the points (since we put them all on
# the surface before with `addNodes' for simplicity)
gmsh.model.mesh.reclassifyNodes()

# Create a geometry for the discrete curves and surfaces, so that we can remesh
# them later on:
gmsh.model.mesh.createGeometry()

# Note that for more complicated meshes, e.g. for on input unstructured STL
# mesh, we could use `classifySurfaces()' to automatically create the discrete
# entities and the topology; but we would then have to extract the boundaries
# afterwards.

# Create other build-in CAD entities to form one volume below the terrain
# surface. Beware that only built-in CAD entities can be hybrid, i.e. have
# discrete entities on their boundary: OpenCASCADE does not support this
# feature.
p1 = gmsh.model.geo.addPoint(0, 0, -0.5)
p2 = gmsh.model.geo.addPoint(1, 0, -0.5)
p3 = gmsh.model.geo.addPoint(1, 1, -0.5)
p4 = gmsh.model.geo.addPoint(0, 1, -0.5)
c1 = gmsh.model.geo.addLine(p1, p2)
c2 = gmsh.model.geo.addLine(p2, p3)
c3 = gmsh.model.geo.addLine(p3, p4)
c4 = gmsh.model.geo.addLine(p4, p1)
c10 = gmsh.model.geo.addLine(p1, 1)
c11 = gmsh.model.geo.addLine(p2, 2)
c12 = gmsh.model.geo.addLine(p3, 3)
c13 = gmsh.model.geo.addLine(p4, 4)
ll1 = gmsh.model.geo.addCurveLoop([c1, c2, c3, c4])
s1 = gmsh.model.geo.addPlaneSurface([ll1])
ll3 = gmsh.model.geo.addCurveLoop([c1, c11, -1, -c10])
s3 = gmsh.model.geo.addPlaneSurface([ll3])
ll4 = gmsh.model.geo.addCurveLoop([c2, c12, -2, -c11])
s4 = gmsh.model.geo.addPlaneSurface([ll4])
ll5 = gmsh.model.geo.addCurveLoop([c3, c13, 3, -c12])
s5 = gmsh.model.geo.addPlaneSurface([ll5])
ll6 = gmsh.model.geo.addCurveLoop([c4, c10, 4, -c13])
s6 = gmsh.model.geo.addPlaneSurface([ll6])
sl1 = gmsh.model.geo.addSurfaceLoop([s1, s3, s4, s5, s6, 1])
v1 = gmsh.model.geo.addVolume([sl1])
gmsh.model.geo.synchronize()

# Set this to True to build a fully hex mesh:
#transfinite = True
transfinite = False
transfiniteAuto = False

if transfinite:
    NN = 30
    for c in gmsh.model.getEntities(1):
        gmsh.model.mesh.setTransfiniteCurve(c[1], NN)
    for s in gmsh.model.getEntities(2):
        gmsh.model.mesh.setTransfiniteSurface(s[1])
        gmsh.model.mesh.setRecombine(s[0], s[1])
        gmsh.model.mesh.setSmoothing(s[0], s[1], 100)
    gmsh.model.mesh.setTransfiniteVolume(v1)
elif transfiniteAuto:
    gmsh.option.setNumber('Mesh.MeshSizeMin', 0.5)
    gmsh.option.setNumber('Mesh.MeshSizeMax', 0.5)
    # setTransfiniteAutomatic() uses the sizing constraints to set the number
    # of points
    gmsh.model.mesh.setTransfiniteAutomatic()
else:
    gmsh.option.setNumber('Mesh.MeshSizeMin', 0.05)
    gmsh.option.setNumber('Mesh.MeshSizeMax', 0.05)

gmsh.model.mesh.generate(3)
gmsh.write('x2.msh')

# Launch the GUI to see the results:
if '-nopopup' not in sys.argv:
    gmsh.fltk.run()

gmsh.finalize()

2.24 x3: Post-processing data import: list-based

See x3.py. Also available in C++ (x3.cpp) and Julia (x3.jl).

# -----------------------------------------------------------------------------
#
#  Gmsh Python extended tutorial 3
#
#  Post-processing data import: list-based
#
# -----------------------------------------------------------------------------

import gmsh
import sys

gmsh.initialize(sys.argv)

# Gmsh supports two types of post-processing data: "list-based" and
# "model-based". Both types of data are handled through the `view' interface.

# List-based views are completely independent from any model and any mesh: they
# are self-contained and simply contain lists of coordinates and values, element
# by element, for 3 types of fields (scalar "S", vector "V" and tensor "T") and
# several types of element shapes (point "P", line "L", triangle "T", quadrangle
# "Q", tetrahedron "S", hexahedron "H", prism "I" and pyramid "Y"). (See `x4.py'
# for a tutorial on model-based views.)

# To create a list-based view one should first create a view:
t1 = gmsh.view.add("A list-based view")

# List-based data is then added by specifying the type as a 2 character string
# that combines a field type and an element shape (e.g. "ST" for a scalar field
# on triangles), the number of elements to be added, and the concatenated list
# of coordinates (e.g. 3 "x" coordinates, 3 "y" coordinates, 3 "z" coordinates
# for first order triangles) and values for each element (e.g. 3 values for
# first order scalar triangles, repeated for each step if there are several time
# steps).

# Let's create two triangles...
triangle1 = [0., 1., 1., # x coordinates of the 3 triangle nodes
             0., 0., 1., # y coordinates of the 3 triangle nodes
             0., 0., 0.] # z coordinates of the 3 triangle nodes
triangle2 = [0., 1., 0., 0., 1., 1., 0., 0., 0.]

# ... and append values for 10 time steps
for step in range(0, 10):
    triangle1.extend([10., 11. - step, 12.])  # 3 node values for each step
    triangle2.extend([11., 12., 13. + step])

# List-based data is just added by concatenating the data for all the triangles:
gmsh.view.addListData(t1, "ST", 2, triangle1 + triangle2)

# Internally, post-processing views parsed by the .geo file parser create such
# list-based data (see e.g. `t7.py', `t8.py' and `t9.py'), independently of any
# mesh.

# Vector or tensor fields can be imported in the same way, the only difference
# beeing the type (starting with "V" for vector fields and "T" for tensor
# fields) and the number of components. For example a vector field on a line
# element can be added as follows:
line = [
    0., 1.,   # x coordinate of the 2 line nodes
    1.2, 1.2, # y coordinate of the 2 line nodes
    0., 0.    # z coordinate of the 2 line nodes
]
for step in range(0, 10):
    # 3 vector components for each node (2 nodes here), for each step
    line.extend([10. + step, 0., 0.,
                 10. + step, 0., 0.])
gmsh.view.addListData(t1, "VL", 1, line)

# List-based data can also hold 2D (in window coordinates) and 3D (in model
# coordinates) strings (see `t4.py'). Here we add a 2D string located on the
# bottom-left of the window (with a 20 pixels offset), as well as a 3D string
# located at model coordinates (0.5, 0.5. 0):
gmsh.view.addListDataString(t1, [20., -20.], ["Created with Gmsh"])
gmsh.view.addListDataString(t1, [0.5, 1.5, 0.],
                            ["A multi-step list-based view"],
                            ["Align", "Center", "Font", "Helvetica"])

# The various attributes of the view can be queried and changed using the option
# interface:
gmsh.view.option.setNumber(t1, "TimeStep", 5)
gmsh.view.option.setNumber(t1, "IntervalsType", 3)
ns = gmsh.view.option.getNumber(t1, "NbTimeStep")
print("View " + str(t1) + " has " + str(ns) + " time steps")

# Views can be queried and modified in various ways using plugins (see `t9.py'),
# or probed directly using `gmsh.view.probe()' - here at point (0.9, 0.1, 0):
print("Value at (0.9, 0.1, 0)", gmsh.view.probe(t1, 0.9, 0.1, 0))

# Views can be saved to disk using `gmsh.view.write()':
gmsh.view.write(t1, "x3.pos")

# High-order datasets can be provided by setting the interpolation matrices
# explicitly. Let's create a second view with second order interpolation on
# a 4-node quadrangle.

# Add a new view:
t2 = gmsh.view.add("Second order quad")

# Set the node coordinates:
quad = [0., 1., 1., 0., # x coordinates of the 4 quadrangle nodes
        -1.2, -1.2, -0.2, -0.2, # y coordinates of the 4 quadrangle nodes
        0., 0., 0., 0.] # z coordinates of the 4 quadrangle nodes

# Add nine values that will be interpolated by second order basis functions
quad.extend([1., 1., 1., 1., 3., 3., 3., 3., -3.])

# Set the two interpolation matrices c[i][j] and e[i][j] defining the d = 9
# basis functions: f[i](u, v, w) = sum_(j = 0, ..., d - 1) c[i][j] u^e[j][0]
# v^e[j][1] w^e[j][2], i = 0, ..., d-1, with u, v, w the coordinates in the
# reference element:
gmsh.view.setInterpolationMatrices(t2, "Quadrangle", 9,
                                   [0, 0, 0.25, 0, 0, -0.25, -0.25, 0, 0.25,
                                    0, 0, 0.25, 0, 0, -0.25, 0.25, 0, -0.25,
                                    0, 0, 0.25, 0, 0, 0.25, 0.25, 0, 0.25,
                                    0, 0, 0.25, 0, 0, 0.25, -0.25, 0, -0.25,
                                    0, 0, -0.5, 0.5, 0, 0.5, 0, -0.5, 0,
                                    0, 0.5, -0.5, 0, 0.5, 0, -0.5, 0, 0,
                                    0, 0, -0.5, 0.5, 0, -0.5, 0, 0.5, 0,
                                    0, 0.5, -0.5, 0, -0.5, 0, 0.5, 0, 0,
                                    1, -1, 1, -1, 0, 0, 0, 0, 0],
                                   [0, 0, 0,
                                    2, 0, 0,
                                    2, 2, 0,
                                    0, 2, 0,
                                    1, 0, 0,
                                    2, 1, 0,
                                    1, 2, 0,
                                    0, 1, 0,
                                    1, 1, 0])

# Note that two additional interpolation matrices could also be provided to
# interpolate the geometry, i.e. to interpolate curved elements.

# Add the data to the view:
gmsh.view.addListData(t2, "SQ", 1, quad)

# In order to visualize the high-order field, one must activate adaptive
# visualization, set a visualization error threshold and a maximum subdivision
# level (Gmsh does automatic mesh refinement to visualize the high-order field
# with the requested accuracy):
gmsh.view.option.setNumber(t2, "AdaptVisualizationGrid", 1)
gmsh.view.option.setNumber(t2, "TargetError", 1e-2)
gmsh.view.option.setNumber(t2, "MaxRecursionLevel", 5)

# Note that the adapted visualization data can be retrived by setting the
# `returnAdaptive' argument to the `gmsh.view.getListData()' function.

# Launch the GUI to see the results:
if '-nopopup' not in sys.argv:
    gmsh.fltk.run()

gmsh.finalize()

2.25 x4: Post-processing data import: model-based

See x4.py. Also available in C++ (x4.cpp) and Julia (x4.jl).

# -----------------------------------------------------------------------------
#
#  Gmsh Python extended tutorial 4
#
#  Post-processing data import: model-based
#
# -----------------------------------------------------------------------------

import gmsh
import sys

gmsh.initialize(sys.argv)

# Contrary to list-based view (see `x3.py'), model-based views are based on one
# or more meshes. Compared to list-based views, they are thus linked to one
# model (per step). Post-processing data stored in MSH files create such
# model-based views.

# Let's create a first model-based view using a simple mesh constructed by
# hand. We create a model with a discrete surface
gmsh.model.add("simple model")
surf = gmsh.model.addDiscreteEntity(2)

# We add 4 nodes and 2 3-node triangles (element type "2")
gmsh.model.mesh.addNodes(2, surf, [1, 2, 3, 4],
                         [0., 0., 0., 1., 0., 0., 1., 1., 0., 0., 1., 0.])
gmsh.model.mesh.addElementsByType(surf, 2, [1, 2], [1, 2, 3, 1, 3, 4])

# We can now create a new model-based view, to which we add 10 steps of
# node-based data:
t1 = gmsh.view.add("Continuous")
for step in range(0, 10):
    gmsh.view.addHomogeneousModelData(
        t1, step, "simple model", "NodeData",
        [1, 2, 3, 4],  # tags of nodes
        [10., 10., 12. + step, 13. + step])  # data, per node

# Besided node-based data, which result in continuous fields, one can also add
# general discontinous fields defined at the nodes of each element, using
# "ElementNodeData":
t2 = gmsh.view.add("Discontinuous")
for step in range(0, 10):
    gmsh.view.addHomogeneousModelData(
        t2, step, "simple model", "ElementNodeData",
        [1, 2],  # tags of elements
        [10., 10., 12. + step, 14., 15., 13. + step])  # data per element nodes

# Constant per element datasets can also be created using "ElementData". Note
# that a more general function `addModelData' to add data for hybrid meshes
# (when data is not homogeneous, i.e. when the number of nodes changes between
# elements) is also available.

# Each step of a model-based view can be defined on a different model, i.e. on a
# different mesh. Let's define a second model and mesh it
gmsh.model.add("another model")
gmsh.model.occ.addBox(0, 0, 0, 1, 1, 1)
gmsh.model.occ.synchronize()
gmsh.model.mesh.generate(3)

# We can add other steps to view "t" based on this new mesh:
nodes, coord, _ = gmsh.model.mesh.getNodes()
for step in range(11, 20):
    gmsh.view.addHomogeneousModelData(
        t1, step, "another model", "NodeData", nodes,
        [step * coord[i] for i in range(0, len(coord), 3)])

# This feature allows to create seamless animations for time-dependent datasets
# on deforming or remeshed models.

# High-order node-based datasets are supported without needing to supply the
# interpolation matrices (iso-parametric Lagrange elements). Arbitrary
# high-order datasets can be specified as "ElementNodeData", with the
# interpolation matrices specified in the same as as for list-based views (see
# `x3.py').

# Model-based views can be saved to disk using `gmsh.view.write()'; note that
# saving a view based on multiple meshes (like the view `t1') will automatically
# create several files. If the `PostProcessing.SaveMesh' option is not set,
# `gmsh.view.write()' will only save the view data, without the mesh (which
# could be saved independently with `gmsh.write()').
gmsh.view.write(t1, "x4_t1.msh")
gmsh.view.write(t2, "x4_t2.msh")

# Launch the GUI to see the results:
if '-nopopup' not in sys.argv:
    gmsh.fltk.run()

gmsh.finalize()

2.26 x5: Additional geometrical data: parametrizations, normals, curvatures

See x5.py. Also available in C++ (x5.cpp) and Julia (x5.jl).

# -----------------------------------------------------------------------------
#
#  Gmsh Python extended tutorial 5
#
#  Additional geometrical data: parametrizations, normals, curvatures
#
# -----------------------------------------------------------------------------

import gmsh
import sys
import math

gmsh.initialize(sys.argv)

# The API provides access to geometrical data in a CAD kernel agnostic manner.

# Let's create a simple CAD model by fusing a sphere and a cube, then mesh the
# surfaces:
gmsh.model.add("x5")
s = gmsh.model.occ.addSphere(0, 0, 0, 1)
b = gmsh.model.occ.addBox(0.5, 0, 0, 1.3, 2, 3)
gmsh.model.occ.fuse([(3, s)], [(3, b)])
gmsh.model.occ.synchronize()
gmsh.model.mesh.generate(2)

# We can for example retrieve the exact normals and the curvature at all the
# mesh nodes (i.e. not normals and curvatures computed from the mesh, but
# directly evaluated on the geometry), by querying the CAD kernels at the
# corresponding parametric coordinates.
normals = []
curvatures = []

# For each surface in the model:
for e in gmsh.model.getEntities(2):
    # Retrieve the surface tag
    s = e[1]

    # Get the mesh nodes on the surface, including those on the boundary
    # (contrary to internal nodes, which store their parametric coordinates,
    # boundary nodes will be reparametrized on the surface in order to compute
    # their parametric coordinates, the result being different when
    # reparametrized on another adjacent surface)
    tags, coord, param = gmsh.model.mesh.getNodes(2, s, True)

    # Get the surface normals on all the points on the surface corresponding to
    # the parametric coordinates of the nodes
    norm = gmsh.model.getNormal(s, param)

    # In the same way, get the curvature
    curv = gmsh.model.getCurvature(2, s, param)

    # Store the normals and the curvatures so that we can display them as
    # list-based post-processing views
    for i in range(0, len(coord), 3):
        normals.append(coord[i])
        normals.append(coord[i + 1])
        normals.append(coord[i + 2])
        normals.append(norm[i])
        normals.append(norm[i + 1])
        normals.append(norm[i + 2])
        curvatures.append(coord[i])
        curvatures.append(coord[i + 1])
        curvatures.append(coord[i + 2])
        curvatures.append(curv[i // 3])

# Create a list-based vector view on points to display the normals, and a scalar
# view on points to display the curvatures
vn = gmsh.view.add("normals")
gmsh.view.addListData(vn, "VP", len(normals) // 6, normals)
gmsh.view.option.setNumber(vn, 'ShowScale', 0)
gmsh.view.option.setNumber(vn, 'ArrowSizeMax', 30)
gmsh.view.option.setNumber(vn, 'ColormapNumber', 19)
vc = gmsh.view.add("curvatures")
gmsh.view.addListData(vc, "SP", len(curvatures) // 4, curvatures)
gmsh.view.option.setNumber(vc, 'ShowScale', 0)

# We can also retrieve the parametrization bounds of model entities, e.g. of
# curve 5, and evaluate the parametrization for several parameter values:
bounds = gmsh.model.getParametrizationBounds(1, 5)
N = 20
t = [bounds[0][0] + i * (bounds[1][0] - bounds[0][0]) / N for i in range(N)]
xyz1 = gmsh.model.getValue(1, 5, t)

# We can also reparametrize curve 5 on surface 1, and evaluate the points in the
# parametric plane of the surface:
uv = gmsh.model.reparametrizeOnSurface(1, 5, t, 1)
xyz2 = gmsh.model.getValue(2, 1, uv)

# Hopefully we get the same x, y, z coordinates!
if max([abs(a - b) for (a, b) in zip(xyz1, xyz2)]) < 1e-12:
    gmsh.logger.write('Evaluation on curve and surface match!')
else:
    gmsh.logger.write('Evaluation on curve and surface do not match!', 'error')

# Launch the GUI to see the results:
if '-nopopup' not in sys.argv:
    gmsh.fltk.run()

gmsh.finalize()

2.27 x6: Additional mesh data: integration points, Jacobians and basis functions

See x6.py. Also available in C++ (x6.cpp) and Julia (x6.jl).

# -----------------------------------------------------------------------------
#
#  Gmsh Python extended tutorial 6
#
#  Additional mesh data: integration points, Jacobians and basis functions
#
# -----------------------------------------------------------------------------

import gmsh
import sys

gmsh.initialize(sys.argv)

gmsh.model.add("x6")

# The API provides access to all the elementary building blocks required to
# implement finite-element-type numerical methods. Let's create a simple 2D
# model and mesh it:
gmsh.model.occ.addRectangle(0, 0, 0, 1, 0.1)
gmsh.model.occ.synchronize()
gmsh.model.mesh.setTransfiniteAutomatic()
gmsh.model.mesh.generate(2)

# Set the element order and the desired interpolation order:
elementOrder = 1
interpolationOrder = 2
gmsh.model.mesh.setOrder(elementOrder)

def pp(label, v, mult):
    print(" * " + str(len(v) / mult) + " " + label + ": " + str(v))

# Iterate over all the element types present in the mesh:
elementTypes = gmsh.model.mesh.getElementTypes()

for t in elementTypes:
    # Retrieve properties for the given element type
    elementName, dim, order, numNodes, localNodeCoord, numPrimNodes =\
    gmsh.model.mesh.getElementProperties(t)
    print("\n** " + elementName + " **\n")

    # Retrieve integration points for that element type, enabling exact
    # integration of polynomials of order "interpolationOrder". The "Gauss"
    # integration family returns the "economical" Gauss points if available, and
    # defaults to the "CompositeGauss" (tensor product) rule if not.
    localCoords, weights =\
    gmsh.model.mesh.getIntegrationPoints(t, "Gauss" + str(interpolationOrder))
    pp("integration points to integrate order " +
       str(interpolationOrder) + " polynomials", localCoords, 3)

    # Return the basis functions evaluated at the integration points. Selecting
    # "Lagrange" and "GradLagrange" returns the isoparamtric basis functions and
    # their gradient (in the reference space of the given element type). A
    # specific interpolation order can be requested using "LagrangeN" and
    # "GradLagrangeN" with N = 1, 2, ... Other supported function spaces include
    # "H1LegendreN", "GradH1LegendreN", "HcurlLegendreN", "CurlHcurlLegendreN".
    numComponents, basisFunctions, numOrientations =\
    gmsh.model.mesh.getBasisFunctions(t, localCoords, "Lagrange")
    pp("basis functions at integration points", basisFunctions, 1)
    numComponents, basisFunctions, numOrientations =\
    gmsh.model.mesh.getBasisFunctions(t, localCoords, "GradLagrange")
    pp("basis function gradients at integration points", basisFunctions, 3)

    # Compute the Jacobians (and their determinants) at the integration points
    # for all the elements of the given type in the mesh. Beware that the
    # Jacobians are returned "by column": see the API documentation for details.
    jacobians, determinants, coords =\
    gmsh.model.mesh.getJacobians(t, localCoords)
    pp("Jacobian determinants at integration points", determinants, 1)

gmsh.finalize()

2.28 x7: Additional mesh data: internal edges and faces

See x7.py. Also available in C++ (x7.cpp) and Julia (x7.jl).

# -----------------------------------------------------------------------------
#
#  Gmsh Python extended tutorial 7
#
#  Additional mesh data: internal edges and faces
#
# -----------------------------------------------------------------------------

import sys
import gmsh

gmsh.initialize(sys.argv)

gmsh.model.add("x7")

# Meshes are fully described in Gmsh by nodes and elements, both associated to
# model entities. The API can be used to generate and handle other mesh
# entities, i.e. mesh edges and faces, which are not stored by default.

# Let's create a simple model and mesh it:
gmsh.model.occ.addBox(0, 0, 0, 1, 1, 1)
gmsh.model.occ.synchronize()
gmsh.option.setNumber("Mesh.MeshSizeMin", 2.)
gmsh.model.mesh.generate(3)

# Like elements, mesh edges and faces are described by (an ordered list of)
# their nodes. Let us retrieve the edges and the (triangular) faces of all the
# first order tetrahedra in the mesh:
elementType = gmsh.model.mesh.getElementType("tetrahedron", 1)
edgeNodes = gmsh.model.mesh.getElementEdgeNodes(elementType)
faceNodes = gmsh.model.mesh.getElementFaceNodes(elementType, 3)

# Edges and faces are returned for each element as a list of nodes corresponding
# to the canonical orientation of the edges and faces for a given element type.

# Gmsh can also identify unique edges and faces (a single edge or face whatever
# the ordering of their nodes) and assign them a unique tag. This identification
# can be done internally by Gmsh (e.g. when generating keys for basis
# functions), or requested explicitly as follows:
gmsh.model.mesh.createEdges()
gmsh.model.mesh.createFaces()

# Edge and face tags can then be retrieved by providing their nodes:
edgeTags, edgeOrientations = gmsh.model.mesh.getEdges(edgeNodes)
faceTags, faceOrientations = gmsh.model.mesh.getFaces(3, faceNodes)

# Since element edge and face nodes are returned in the same order as the
# elements, one can easily keep track of which element(s) each edge or face is
# connected to:
elementTags, elementNodeTags = gmsh.model.mesh.getElementsByType(elementType)
edges2Elements = {}
faces2Elements = {}
for i in range(len(edgeTags)): # 6 edges per tetrahedron
    if not edgeTags[i] in edges2Elements:
        edges2Elements[edgeTags[i]] = [elementTags[i // 6]]
    else:
        edges2Elements[edgeTags[i]].append(elementTags[i // 6])
for i in range(len(faceTags)): # 4 faces per tetrahedron
    if not faceTags[i] in faces2Elements:
        faces2Elements[faceTags[i]] = [elementTags[i // 4]]
    else:
        faces2Elements[faceTags[i]].append(elementTags[i // 4])

# New unique lower dimensional elements can also be easily created given the
# edge or face nodes. This is especially useful for numerical methods that
# require integrating or interpolating on internal edges or faces (like
# e.g. Discontinuous Galerkin techniques), since creating elements for the
# internal entities will make this additional mesh data readily available (see
# `x6.py'). For example, we can create a new discrete surface...
s = gmsh.model.addDiscreteEntity(2)

# ... and fill it with unique triangles corresponding to the faces of the
# tetrahedra:
maxElementTag = gmsh.model.mesh.getMaxElementTag()
uniqueFaceTags = set()
tagsForTriangles = []
faceNodesForTriangles = []
for i in range(len(faceTags)):
    if faceTags[i] not in uniqueFaceTags:
        uniqueFaceTags.add(faceTags[i])
        tagsForTriangles.append(faceTags[i] + maxElementTag)
        faceNodesForTriangles.append(faceNodes[3 * i])
        faceNodesForTriangles.append(faceNodes[3 * i + 1])
        faceNodesForTriangles.append(faceNodes[3 * i + 2])
elementType2D = gmsh.model.mesh.getElementType("triangle", 1)
gmsh.model.mesh.addElementsByType(s, elementType2D, tagsForTriangles,
                                  faceNodesForTriangles)

# Since the tags for the triangles have been created based on the face tags,
# the information about neighboring elements can also be readily created,
# useful e.g. in Finite Volume or Discontinuous Galerkin techniques:
for t in tagsForTriangles:
    print("triangle " + str(int(t)) + " is connected to tetrahedra " +
          str(faces2Elements[t - maxElementTag]))

# If all you need is the list of all edges or faces in terms of their nodes, you
# can also directly call:
edgeTags, edgeNodes = gmsh.model.mesh.getAllEdges()
faceTags, faceNodes = gmsh.model.mesh.getAllFaces(3)

# Launch the GUI to see the results:
if '-nopopup' not in sys.argv:
    gmsh.fltk.run()

gmsh.finalize()

3 Gmsh graphical user interface

Once you have the Gmsh application installed (see Installing and running Gmsh on your computer), to launch the graphical interface just double-click on the Gmsh icon, or type

> gmsh

at the shell prompt in a terminal. This will open the main window of the Gmsh GUI, with a menu bar on top (except on macOS, where by default the menu bar is on the top of the screen – this can be changed with the General.SystemMenuBar option, see General options), a tree menu on the left (which by default contains a ‘Modules’ entry with three children: ‘Geometry’, ‘Mesh’ and ‘Solver’), a graphic area on the right, and a status bar with some shortcut buttons at the bottom. (You can detach the tree menu using ‘Window->Attach/Detach Menu’.)

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

There is no need to save your geometrical model: when the rectangle was added, scripting commands were automatically appended to your model file mymodel.geo:

//+
SetFactory("OpenCASCADE");
Rectangle(1) = {0, 0, 0, 1, 0.5, 0};

You can edit this script with any text editor; clicking on ‘Edit script’ in the tree menu will launch the default text editor specified by the General.Editor option (see General options). If you edit the script, you should click on ‘Reload script’ in the tree menu to reload the modifications in the GUI. The //+ line in the script is a comment that is used as a placemark between commands added by the GUI; see Gmsh scripting language for the scripting language reference.

Combining GUI actions and script file editing is a classical way of working with the Gmsh app. For example, it is often faster to define variables and points directly in the script file, and then use the GUI to define the curves, the surfaces and the volumes interactively.

To load an existing model instead of creating a model from scratch, use the ‘File->Open’ menu. For example, to open the first tutorial (see Gmsh tutorial), choose t1.geo. On the terminal, you can also specify the file name directly on the command line, i.e.:

> gmsh t1.geo

To generate a mesh, open ‘Mesh’ in the tree menu and choose the desired dimension: ‘1D’ will mesh all the curves; ‘2D’ will mesh all the surfaces—as well as all the curves if ‘1D’ was not called before; ‘3D’ will mesh all the volumes—and all the surfaces if ‘2D’ was not called before. To save the resulting mesh in the current mesh format click on ‘Save’ in the tree menu, or select the appropriate format and file name with the ‘File->Export’ menu. The default mesh file name is based on the name of the current active model, with an appended extension depending on the mesh format. Note that most interactive commands have keyboard shortcuts: see Keyboard shortcuts, or select ‘Help->Keyboard and Mouse Usage’ in the menu. For example, to quickly generate the 2D mesh and save a mesh, you can first press 2, then Ctrl+Shift+s.

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

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

> gmsh t1.geo view1.pos view5.msh

When one or more more post-processing views are loaded, a ‘Post-Processing’ entry in the tree menu appears. With the previous command, three views will appear in the tree menu under ‘Post-processing’, respectively labeled ‘A scalar map’, ‘Nodal scalar map’ and ‘Element 1 vector’. In this example the views contain several time steps: you can loop through them with the shortcuts icons on the left of the status bar. A mouse click on the view name will toggle the visibility of the selected view, while a click on the arrow button on the right will provide access to the view’s options.

Note that all the options specified interactively can also be directly specified in the script files. You can save the current options of the current active model with the ‘File->Save Model Options’. This will create a new option file with the same filename as the active model, but with an extra .opt extension added. The next time you open this model, the associated options will be automatically loaded, too. To save the current options as your default preferences for all future Gmsh sessions, use the ‘File->Save Options As Default’ menu instead. You can also save the current options in an arbitrary file by choosing the ‘Gmsh options’ format in ‘File->Export’. For more information about available options (and how to reset them to their default values), see Gmsh options. A full list of options with their current values is also available using the ‘Help->Current Options’ menu.

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

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

3.1 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.2 Keyboard shortcuts

(On macOS, Ctrl is replaced by Cmd 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 or 9

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

e

End/accept selection in geometry creation mode

g

Go to geometry module

m

Go to mesh module

p

Go to post-processing module

q

Abort selection in geometry creation mode

s

Go to solver module

x

Toggle x coordinate freeze in geometry creation mode

y

Toggle y coordinate freeze in geometry creation mode

z

Toggle z coordinate freeze in geometry creation mode

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+x

Move only along x coordinate in geometry creation mode

Shift+y

Move only along y coordinate in geometry creation mode

Shift+z

Move only along z coordinate in geometry creation mode

Shift+Escape

Enable full mouse selection

Ctrl+d

Attach/detach menu

Ctrl+e

Export project

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 mesh in default format

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+r

Open next-to-last opened file

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+1

Set 1:1 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 nodes

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

Alt+Shift+1

Reset bounding box around visible entities

Alt+Ctrl++1

Sync scale between viewports

4 Gmsh command-line interface

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

For example, meshing the first tutorial in batch mode can be done in a terminal by passing the -2 command-line switch:

> gmsh t1.geo -2

The same effect could be achieved by adding the Mesh 2; command at the end of t1.geo and running

> gmsh t1.geo -parse_and_exit

or further adding the Exit; command at the end of the script and simply opening this new file:

> gmsh t1.geo

Note that all numeric and string options (see Gmsh options) can be set from the command line with the -setnumber and -setstring switches

> gmsh t1.geo -setnumber Mesh.Nodes 1 -setnumber Geometry.SurfaceLabels 1

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

(Related option names, if any, are given between parentheses)

Geometry:

-0

Output model, then exit

-tol value

Set geometrical tolerance (Geometry.Tolerance)

-match

Match geometries and meshes

Mesh:

-1, -2, -3

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

-format string

Select output mesh format: auto, msh1, msh2, msh22, msh3, msh4, msh40, msh41, msh, unv, vtk, wrl, mail, stl, p3d, mesh, bdf, cgns, med, diff, ir3, inp, ply2, celum, su2, x3d, dat, neu, m, key, off, rad (Mesh.Format)

-bin

Create binary files when possible (Mesh.Binary)

-refine

Perform uniform mesh refinement, then exit

-barycentric_refine

Perform barycentric mesh refinement, then exit

-reclassify angle

Reclassify surface mesh, then exit

-reparam angle

Reparametrize surface mesh, then exit

-hybrid

generate a hybrid hex-tet mesh with trihedron for transitions

-part int

Partition after batch mesh generation (Mesh.NbPartitions)

-part_weight [tri,quad,tet,hex,pri,pyr,trih] int

Weight of a triangle/quad/etc. during partitioning (Mesh.Partition[Tri,Quad,...]Weight)

-part_split

Save mesh partitions in separate files (Mesh.PartitionSplitMeshFiles)

-part_[no_]topo

Create the partition topology (Mesh.PartitionCreateTopology)

-part_[no_]ghosts

Create ghost cells (Mesh.PartitionCreateGhostCells)

-part_[no_]physicals

Create physical groups for partitions (Mesh.PartitionCreatePhysicals)

-part_topo_pro

Save the partition topology .pro file (Mesh.PartitionTopologyFile)

-preserve_numbering_msh2

Preserve element numbering in MSH2 format (Mesh.PreserveNumberingMsh2)

-save_all

Save all elements (Mesh.SaveAll)

-save_parametric

Save nodes with their parametric coordinates (Mesh.SaveParametric)

-save_topology

Save model topology (Mesh.SaveTopology)

-algo string

Select mesh algorithm: auto, meshadapt, del2d, front2d, delquad, quadqs, initial2d, del3d, front3d, mmg3d, hxt, initial3d (Mesh.Algorithm and Mesh.Algorithm3D)

-smooth int

Set number of mesh smoothing steps (Mesh.Smoothing)

-order int

Set mesh order (Mesh.ElementOrder)

-optimize[_netgen]

Optimize quality of tetrahedral elements (Mesh.Optimize[Netgen])

-optimize_threshold

Optimize tetrahedral elements that have a quality less than a threshold (Mesh.OptimizeThreshold)

-optimize_ho

Optimize high order meshes (Mesh.HighOrderOptimize)

-ho_[min,max,nlayers]

High-order optimization parameters (Mesh.HighOrderThreshold[Min,Max], Mesh.HighOrderNumLayers)

-clscale value

Set mesh element size factor (Mesh.MeshSizeFactor)

-clmin value

Set minimum mesh element size (Mesh.MeshSizeMin)

-clmax value

Set maximum mesh element size (Mesh.MeshSizeMax)

-clextend value

Extend mesh element sizes from boundaries (Mesh.MeshSizeExtendFromBoundary)

-clcurv value

Compute mesh element size from curvature, with value the target number of elements per 2*pi radians (Mesh.MeshSizeFromCurvature)

-aniso_max value

Set maximum anisotropy for bamg (Mesh.AnisoMax)

-smooth_ratio value

Set smoothing ration between mesh sizes at nodes of a same edge for bamg (Mesh.SmoothRatio)

-epslc1d value

Set accuracy of evaluation of mesh size field for 1D mesh (Mesh.LcIntegrationPrecision)

-swapangle value

Set the threshold angle (in degrees) between two adjacent faces below which a swap is allowed (Mesh.AllowSwapAngle)

-rand value

Set random perturbation factor (Mesh.RandomFactor)

-bgm file

Load background mesh from file

-check

Perform various consistency checks on mesh

-ignore_periocity

Ignore periodic boundaries (Mesh.IgnorePeriodicity)

Post-processing:

-link int

Select link mode between views (PostProcessing.Link)

-combine

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

Solver:

-listen string

Always listen to incoming connection requests (Solver.AlwaysListen) on the given socket (uses Solver.SocketName if not specified)

-minterpreter string

Name of Octave interpreter (Solver.OctaveInterpreter)

-pyinterpreter string

Name of Python interpreter (Solver.OctaveInterpreter)

-run

Run ONELAB solver(s)

Display:

-n

Hide all meshes and post-processing views on startup (View.Visible, Mesh.[Points,Lines,SurfaceEdges,...])

-nodb

Disable double buffering (General.DoubleBuffer)

-numsubedges

Set num of subdivisions for high order element display (Mesh.NumSubEdges)

-fontsize int

Specify the font size for the GUI (General.FontSize)

-theme string

Specify FLTK GUI theme (General.FltkTheme)

-display string

Specify display (General.Display)

-camera

Use camera mode view (General.CameraMode)

-stereo

OpenGL quad-buffered stereo rendering (General.Stereo)

-gamepad

Use gamepad controller if available

Other:

-, -parse_and_exit

Parse input files, then exit

-save

Save output file, then exit

-o file

Specify output file name

-new

Create new model before merge next file

-merge

Merge next files

-open

Open next files

-log filename

Log all messages to filename

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

Start in automatic, geometry, mesh, solver or post-processing mode (General.InitialModule)

-pid

Print process id on stdout

-watch pattern

Pattern of files to merge as they become available (General.WatchFilePattern)

-bg file

Load background (image or PDF) file (General.BackgroundImageFileName)

-v int

Set verbosity level (General.Verbosity)

-string "string"

Parse command string at startup

-setnumber name value

Set constant, ONELAB or option number name=value

-setstring name value

Set constant, ONELAB or option string name=value

-nopopup

Don’t popup dialog windows in scripts (General.NoPopup)

-noenv

Don’t modify the environment at startup

-nolocale

Don’t modify the locale at startup

-option file

Parse option file at startup

-convert files

Convert files into latest binary formats, then exit

-nt int

Set number of threads (General.NumThreads)

-cpu

Report CPU times for all operations

-version

Show version number

-info

Show detailed version information

-help

Show command line usage

-help_options

Show all options

5 Gmsh scripting language

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

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

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

The following rules are used when describing the scripting language in the rest of this chapter (note that metasyntactic variable definitions stay valid throughout the chapter, not only in the section where the definitions appear):

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.

5.1 General scripting commands

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

5.1.2 Floating point 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.

Floating point expressions (or, more simply, “expressions”) are denoted by the metasyntactic variable expression, 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 |
  number-option |
  Find(expression-list-item, expression-list-item) |
  StrFind(string-expression, string-expression) |
  StrCmp(string-expression, string-expression) |
  StrLen(string-expression) |
  TextAttributes(string-expression<,string-expression…>) |
  Exists(string) | Exists(string~{ expression }) |
  FileExists(string-expression) |
  StringToName(string-expression) | S2N(string-expression) |
  GetNumber(string-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 number-options are listed in Gmsh options. Find searches for occurrences of the first expression in the second (both of which can be lists). StrFind searches the first string-expression for any occurrence of the second string-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). StrLen 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), 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 the ONELAB tutorial wiki 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 [ ] |  string ( ) |
  List [ string ] |
  List [ expression-list-item ] |
  List [ { expression-list } ] |
  Unique [ expression-list-item ] |
  Abs [ expression-list-item ] |
  ListFromFile [ expression-char ] |
  LinSpace[ expression, expression, expression ] |
  LogSpace[ expression, expression, expression ] |
  string [ { expression-list } ] |
  Point { expression } |
  transform |
  extrude |
  boolean |
  Point|Curve|Surface|Volume In BoundingBox { expression-list } |
  BoundingBox Point|Curve|Surface|Volume { expression-list } |
  Mass Curve|Surface|Volume { expression } |
  CenterOfMass Curve|Surface|Volume { expression } |
  MatrixOfInertia Curve|Surface|Volume { expression } |
  Point { expression } |
  Physical Point|Curve|Surface|Volume { expression-list } |
  <Physical> Point|Curve|Surface|Volume { : } |

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). Unique sorts the entries in the list and removes all duplicates. Abs takes the absolute value of all entries in the list. ListFromFile reads a list of numbers from a file. LinSpace and LogSpace construct lists using linear or logarithmic spacing. The next two cases permit to reference an expression sublist (whose elements are those corresponding to the indices provided by the expression-list). The next cases permit to retrieve the indices of entities created through geometrical transformations, extrusions and boolean operations (see Transformations, Extrusions and Boolean operations).

The next two cases allow to retrieve entities in a given bounding box, or get the bounding box of a given entity, with the bounding box specified as (X min, Y min, Z min, X max, Y max, Z max). Beware that the order of coordinates is different than in the BoundingBox command for the scene: see Other general commands. The last cases permit to retrieve the mass, the center of mass or the matrix of inertia of an entity, the coordinates of a given geometry point (see Points), the elementary entities making up physical groups, and the tags of all (physical or elementary) points, curves, surfaces or volumes in the model. These operations all trigger a synchronization of the CAD model with the internal Gmsh model.

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

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

expression-list-or-all:
  expression-list | :

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

5.1.3 String expressions

String expressions are defined as:

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

DefineString allows to define a ONELAB variable in-line. The string-expression given as the first argument is the default value; this is followed by the various ONELAB options. See the ONELAB tutorial wiki for more information.

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

List of string expressions are defined as:

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

5.1.4 Color expressions

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

color-expression:
  string-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 src/common/Colors.h in the source code for a complete list). The second case permits to define colors by using three expressions to specify their red, green and blue components (with values comprised between 0 and 255). The third case permits to define colors by using their red, green and blue color components as well as their alpha channel. The last case permits to use the value of a color-option as a color-expression. The various color-options are listed in Gmsh options.

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

5.1.5 Operators

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

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. =, +=, -=, *=, /=

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

Max ( expression, expression )

Maximum of the two arguments.

Min ( expression, expression )

Minimum of the two arguments.

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.

5.1.7 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 | string-expression

Begin 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

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

Call string | string-expression ;

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

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

5.1.8 Loops and conditionals

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

For ( expression : expression )

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

Iterate 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 }

Iterate 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 }

Iterate 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

End 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

End a matching If command.

5.1.9 Other general commands

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

string = expression;

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

Pi

Return 3.1415926535897932.

GMSH_MAJOR_VERSION

Return Gmsh’s major version number.

GMSH_MINOR_VERSION

Return Gmsh’s minor version number.

GMSH_PATCH_VERSION

Return Gmsh’s patch version number.

MPI_Size

Return 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

Return the rank of the current processor.

Cpu

Return the current CPU time (in seconds).

Memory

Return the current memory usage (in Mb).

TotalMemory

Return the total memory available (in Mb).

newp

Return the next available point tag. As explained in Geometry module, a unique tag must be associated with every geometrical point: newp permits to know the highest tag 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 tags are already attributed, and which ones are still available.

newc

Return the next available curve tag.

news

Return the next available surface tag.

newv

Return the next available volume tag.

newcl

Return the next available curve loop tag.

newsl

Return the next available surface loop tag.

newreg

Return the next available region tag. That is, newreg returns the maximum of newp, newl, news, newv, newll, newsl and all physical group tags¹³.

string = { };

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

string[] = { expression-list };

Create 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 };

Affect 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;

Add and affect expression to an existing expression identifier.

string -= expression;

Subtract and affect expression to an existing expression identifier.

string *= expression;

Multiply and affect expression to an existing expression identifier.

string /= expression;

Divide and affect expression to an existing expression identifier.

string += { expression-list };

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

string -= { expression-list };

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

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

Add and affect, 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 };

Subtract and affect, 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 };

Multiply and affect, 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 };

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

string = string-expression;

Create a new string expression identifier string with a given string-expression.

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

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

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

Append a string expression list to an existing list. Parentheses can also be used instead of brackets.

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

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

DefineConstant[ string = { expression|string-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 the ONELAB tutorial wiki for more information.

SetNumber( string-expression , expression );

Set the value a numeric ONELAB variable string-expression.

SetString( string-expression , string-expression );

Set the value a string ONELAB variable string-expression.

number-option = expression;

Affect expression to a real option.

string-option = string-expression;

Affect string-expression to a string option.

color-option = color-expression;

Affect color-expression to a color option.

number-option += expression;

Add and affect expression to a real option.

number-option -= expression;

Subtract and affect expression to a real option.

number-option *= expression;

Multiply and affect expression to a real option.

number-option /= expression;

Divide and affect expression to a real option.

Abort;

Abort the current script.

Exit < expression >;

Exit Gmsh (optionally with level expression instead of 0).

CreateDir string-expression;

Create the directory string-expression.

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

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

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

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

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

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

Warning|Error ( string-expression <, expression-list> );

Same as Printf, but raises a warning or an error.

Merge string-expression;

Merge a file named string-expression. This command is equivalent to the ‘File->Merge’ menu in the GUI. If the path in string-expression is not absolute, string-expression is appended to the path of the current file. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

ShapeFromFile( string-expression );

Merge a BREP, STEP or IGES file and returns the tags of the highest-dimensional entities. Only available with the OpenCASCADE geometry kernel.

Draw;

Redraw the scene.

SplitCurrentWindowHorizontal expression;

Split the current window horizontally, with the ratio given by expression.

SplitCurrentWindowVertical expression;

Split the current window vertically, with the ratio given by expression.

SetCurrentWindow expression;

Set the current window by speficying its index (starting at 0) in the list of all windows. When new windows are created by splits, new windows are appended at the end of the list.

UnsplitWindow;

Restore a single window.

SetChanged;

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

BoundingBox;

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

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

This operation triggers a synchronization of the CAD model with the internal Gmsh model.

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

Force the bounding box of the scene to the given expressions (X min, X max, Y min, Y max, Z min, Z max). Beware that order of the coordinates is different than in the BoundingBox commands for model entities: see Floating point expressions.

Delete Model;

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

Delete Meshes;

Delete all the meshes in the current model.

Delete Physicals;

Delete all physical groups.

Delete Variables;

Delete all the expressions.

Delete Options;

Delete the current options and revert to the default values.

Delete string;

Delete the expression string.

Print string-expression;

Print the graphic window in a file named string-expression, using the current Print.Format (see General options). If the path in string-expression is not absolute, string-expression is appended to the path of the current file. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Sleep expression;

Suspend the execution of Gmsh during expression seconds.

SystemCall string-expression;

Executes a (blocking) system call.

NonBlockingSystemCall string-expression;

Execute a (non-blocking) system call.

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

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

SetName string-expression;

Change the name of the current model.

SetFactory(string-expression);

Change the current geometry kernel (i.e. determines the CAD kernel that is used for all subsequent geometrical commands). Currently available kernels: "Built-in" and "OpenCASCADE".

SyncModel;

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

NewModel;

Create a new current model.

Include string-expression;

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

5.2 Geometry scripting commands

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

A bottom-up boundary representation approach can be used by first defining points (using the Point command), then curves (using Line, Circle, Spline, …, commands or by extruding points), then surfaces (using for example the Plane Surface or Surface commands, or by extruding curves), and finally volumes (using the Volume command or by extruding surfaces). 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. With the OpenCASCADE kernel, additional boolean operations are available: BooleanIntersection, BooleanUnion, BooleanDifference and BooleanFragments.

The next subsections describe all the available geometry commands in the scripting language. Note that the following general rule is followed for the definition of model entities: if an 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.2.1 Points

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

Create a point. The expression inside the parentheses is the point’s tag; 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 | string-expression <, expression> ) <+|->= { expression-list };

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

5.2.2 Curves

Line ( expression ) = { expression, expression };

Create a straight line segment. The expression inside the parentheses is the line segment’s tag; the two expressions inside the braces on the right hand side give tags of the start and end points of the segment.

Bezier ( expression ) = { expression-list };

Create a Bezier curve. The expression-list contains the tags of the control points.

BSpline ( expression ) = { expression-list };

Create a cubic BSpline. The expression-list contains the tags of the control points. Creates a periodic curve if the first and last points are identical.

Spline ( expression ) = { expression-list };

Create a spline going through the points in expression-list. With the built-in geometry kernel this constructs a Catmull-Rom spline. With the OpenCASCADE kernel, this constructs a C2 BSpline. Creates a periodic curve if the first and last points are identical.

Circle ( expression ) = { expression, expression, expression <, ...> };

Create a circle arc. If three expressions are provided on the right-hand-side they define the start point, the center and the end point of the arc. With the built-in geometry kernel the arc should be strictly smaller than Pi. With the OpenCASCADE kernel, if between 4 and 6 expressions are provided, the first three define the coordinates of the center, the next one defines the radius, and the optional next two the start and end angle.

Ellipse ( expression ) = { expression, expression, expression <, ...> };

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

Compound Spline | BSpline ( expression ) = { expression-list } Using expression;

Create a spline or a BSpline from control points sampled on the curves in expression-list. Using expression specifies the number of intervals on each curve to compute the sampling points. Compound splines and BSplines are only available with the built-in geometry kernel.

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

Create an oriented loop of curves, i.e. a closed wire. The expression inside the parentheses is the curve loop’s tag; the expression-list on the right hand side should contain the tags of all the curves that constitute the curve loop. A curve loop must be a closed loop. With the built-in geometry kernel, the curves should be ordered and oriented, using negative tags to specify reverse orientation. (If the orientation is correct, but the ordering is wrong, Gmsh will actually reorder the list internally to create a consistent loop; the built-in kernel also supports multiple curve loops (or subloops) in a single Curve Loop command, but this is not recommended). With the OpenCASCADE kernel the curve loop is always oriented according to the orientation of its first curve; negative tags can be specified for compatibility with the built-in kernel, but are simply ignored. Curve loops are used to create surfaces: see Surfaces.

Wire ( expression ) = { expression-list };

Create a path made of curves. Wires are only available with the OpenCASCADE kernel. They are used to create ThruSections and extrusions along paths.

Physical Curve ( expression | string-expression <, expression> ) <+|->= { expression-list };

Create a physical curve. The expression inside the parentheses is the physical curve’s tag; the expression-list on the right hand side should contain the tags of all the elementary curves that need to be grouped inside the physical curve. If a string-expression is given instead instead of expression inside the parentheses, a string label is associated with the physical tag, which can be either provided explicitly (after the comma) or not (in which case a unique tag is automatically created). In some mesh file formats (e.g. MSH2), specifying negative tags in the expression-list will reverse the orientation of the mesh elements belonging to the corresponding elementary curves in the saved mesh file.

5.2.3 Surfaces

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

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

Surface ( expression ) = { expression-list } < In Sphere { expression }, Using Point { expression-list } >;

Create a surface filling. With the built-in kernel, the first curve loop should be composed of either three or four curves, the surface is constructed using transfinite interpolation, and the optional In Sphere argument forces the surface to be a spherical patch (the extra parameter gives the tag of the center of the sphere). With the OpenCASCADE kernel, a BSpline surface is constructucted by optimization to match the bounding curves, as well as the (optional) points provided after Using Point.

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

Create a BSpline surface filling. Only a single curve loop made of 2, 3 or 4 BSpline curves can be provided. BSpline Surface is only available with the OpenCASCADE kernel.

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

Create a Bezier surface filling. Only a single curve loop made of 2, 3 or 4 Bezier curves can be provided. Bezier Surface is only available with the OpenCASCADE kernel.

Disk ( expression ) = { expression-list };

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

Rectangle ( expression ) = { expression-list };

Create a rectangle. The 3 first expressions define the lower-left corner; the next 2 define the width and height. If a 6th expression is provided, it defines a radius to round the rectangle corners. Rectangle is only available with the OpenCASCADE kernel.

Surface Loop ( expression ) = { expression-list } < Using Sewing >;

Create a surface loop (a shell). The expression inside the parentheses is the surface loop’s tag; the expression-list on the right hand side should contain the tags of all the surfaces that constitute the surface loop. A surface loop must always represent a closed shell, and the surfaces should be oriented consistently (using negative tags to specify reverse orientation). (Surface loops are used to create volumes: see Volumes.) With the OpenCASCADE kernel, the optional Using Sewing argument allows to build a shell made of surfaces that share geometrically identical (but topologically different) curves.

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

Create a physical surface. The expression inside the parentheses is the physical surface’s tag; the expression-list on the right hand side should contain the tags of all the elementary surfaces that need to be grouped inside the physical surface. If a string-expression is given instead instead of expression inside the parentheses, a string label is associated with the physical tag, which can be either provided explicitly (after the comma) or not (in which case a unique tag is automatically created). In some mesh file formats (e.g. MSH2), specifying negative tags in the expression-list will reverse the orientation of the mesh elements belonging to the corresponding elementary surfaces in the saved mesh file.

5.2.4 Volumes

Volume ( expression ) = { expression-list };

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

Sphere ( expression ) = { expression-list };

Create a sphere, defined by the 3 coordinates of its center and a radius. Additional expressions define 3 angle limits. The first two optional arguments define the polar angle opening (from -Pi/2 to Pi/2). The optional ‘angle3’ argument defines the azimuthal opening (from 0 to 2*Pi). Sphere is only available with the OpenCASCADE kernel.

Box ( expression ) = { expression-list };

Create a box, defined by the 3 coordinates of a point and the 3 extents. Box is only available with the OpenCASCADE kernel.

Cylinder ( expression ) = { expression-list };

Create a cylinder, defined by the 3 coordinates of the center of the first circular face, the 3 components of the vector defining its axis and its radius. An additional expression defines the angular opening. Cylinder is only available with the OpenCASCADE kernel.

Torus ( expression ) = { expression-list };

Create a torus, defined by the 3 coordinates of its center and 2 radii. An additional expression defines the angular opening. Torus is only available with the OpenCASCADE kernel.

Cone ( expression ) = { expression-list };

Create a cone, defined by the 3 coordinates of the center of the first circular face, the 3 components of the vector defining its axis and the two radii of the faces (these radii can be zero). An additional expression defines the angular opening. Cone is only available with the OpenCASCADE kernel.

Wedge ( expression ) = { expression-list };

Create a right angular wedge, defined by the 3 coordinates of the right-angle point and the 3 extends. An additional parameter defines the top X extent (zero by default). Wedge is only available with the OpenCASCADE kernel.

ThruSections ( expression ) = { expression-list };

Create a volume defined through curve loops. ThruSections is only available with the OpenCASCADE kernel.

Ruled ThruSections ( expression ) = { expression-list };

Same as ThruSections, but the surfaces created on the boundary are forced to be ruled. Ruled ThruSections is only available with the OpenCASCADE kernel.

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

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

5.2.5 Extrusions

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

extrude:

Extrude { expression-list } { extrude-list }

Extrude all elementary entities (points, curves 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 }

Extrude all elementary entities (points, curves 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). With the built-in geometry kernel the angle should be strictly smaller than Pi.

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

Extrude all elementary entities (points, curves or surfaces) in extrude-list using a translation combined with a rotation (to produce a “twist”). 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, which should match the direction of the translation; 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 the built-in geometry kernel the angle should be strictly smaller than Pi.

Extrude { extrude-list }

Extrude entities in extrude-list using a translation along their normal. Only available with the built-in geometry kernel.

Extrude { extrude-list } Using Wire { expression-list }

Extrude entities in extrude-list along the give wire. Only available with the OpenCASCADE geometry kernel.

ThruSections { expression-list }

Create surfaces through the given curve loops or wires. ThruSections is only available with the OpenCASCADE kernel.

Ruled ThruSections { expression-list }

Create ruled surfaces through the given curve loops or wires. Ruled ThruSections is only available with the OpenCASCADE kernel.

Fillet { expression-list } { expression-list } { expression-list }

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

Chamfer { expression-list } { expression-list } { expression-list } { expression-list }

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

with

extrude-list:
  <Physical> Point | Curve | Surface { expression-list-or-all }; …

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

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

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

5.2.6 Boolean operations

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

boolean:

BooleanIntersection { boolean-list } { boolean-list }

Compute the intersection of the object and the tool.

BooleanUnion { boolean-list } { boolean-list }

Compute the union of the object and the tool.

BooleanDifference { boolean-list } { boolean-list }

Subtract the tool from the object.

BooleanFragments { boolean-list } { boolean-list }

Compute all the fragments resulting from the intersection of the entities in the object and in the tool, making all interfaces conformal. When applied to entities of different dimensions, the lower dimensional entities will be automatically embedded in the higher dimensional entities if they are not on their boundary.

with

boolean-list:
  <Physical> Curve | Surface | Volume { expression-list-or-all }; … |
  Delete ;

If Delete is specified in the boolean-list, the tool and/or the object is deleted.

As explained in Floating point expressions, boolean can be used in an expression, in which case it returns the list of tags of the highest dimensional entities created by the boolean operation. See examples/boolean for examples.

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

boolean-explicit:

BooleanIntersection ( expression ) = { boolean-list } { boolean-list };

Compute the intersection of the object and the tool and assign the result the tag expression.

BooleanUnion ( expression ) = { boolean-list } { boolean-list };

Compute the union of the object and the tool and assign the result the tag expression.

BooleanDifference ( expression ) = { boolean-list } { boolean-list };

Subtract the tool from the object and assign the result the tag expression.

Again, see examples/boolean for examples.

Boolean operations are only available with the OpenCASCADE geometry kernel.

5.2.7 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 }

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

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

Scale all elementary entities in transform-list using different factors along X, Y and Z (the three expressions). The expression-list should contain three expressions giving the X, Y, and Z coordinates of the center of the homothetic transformation.

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

Rotate 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 }

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

Affine { expression-list } { transform-list }

Apply a 4 x 4 affine transformation matrix (16 entries given by row; only 12 can be provided for convenience) to all elementary entities. Currently only available with the OpenCASCADE kernel.

Translate { expression-list } { transform-list }

Translate 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.) Return the entities on the boundary of the elementary entities in transform-list, with signs indicating their orientation in the boundary. To get unsigned tags (e.g. to reuse the output in other commands), apply the Abs function on the returned list. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

CombinedBoundary { transform-list }

(Not a transformation per-se.) Return the boundary of the elementary entities, combined as if a single entity, in transform-list. Useful to compute the boundary of a complex part. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

PointsOf { transform-list }

(Not a transformation per-se.) Return all the geometrical points on the boundary of the elementary entities. Useful to compute the boundary of a complex part. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Intersect Curve { expression-list } Surface { expression }

(Not a transformation per-se.) Return the intersections of the curves given in expression-list with the specified surface. Currently only available with the built-in kernel.

Split Curve { expression } Point { expression-list }

(Not a transformation per-se.) Split the curve expression on the specified control points. Only available with the built-in kernel, for splines and BSplines.

with

transform-list:
  <Physical> Point | Curve | Surface | Volume
    { expression-list-or-all }; … |
  Duplicata { <Physical> Point | Curve | Surface | Volume
    { expression-list-or-all }; … } |
  transform

5.2.8 Other geometry commands

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

Coherence;

Remove all duplicate elementary entities (e.g., points having identical coordinates). Note that with the built-in geometry kernel Gmsh executes the Coherence command automatically after each geometrical transformation, unless Geometry.AutoCoherence is set to zero (see Geometry options). With the OpenCASCADE geometry kernel, Coherence is simply a shortcut for a BooleanFragments operation on all entities, with the Delete operator applied to all operands.

HealShapes;

Apply the shape healing procedure(s), according to Geometry.OCCFixDegenerated, Geometry.OCCFixSmallEdges, Geometry.OCCFixSmallFaces, Geometry.OCCSewFaces, Geometry.OCCMakeSolids. Only available with the OpenCASCADE geometry kernel.

< Recursive > Delete { <Physical> Point | Curve | Surface | Volume { expression-list-or-all }; … }

Delete all elementary entities whose tags are given in expression-list-or-all. If an entity is linked to another entity (for example, if a point is used as a control point of a curve), Delete has no effect (the curve will have to be deleted before the point can). The Recursive variant deletes the entities as well as all its sub-entities of lower dimension. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Delete Embedded { <Physical> Point | Curve | Surface | Volume { expression-list-or-all }; … }

Delete all the embedded entities in the elementary entities whose tags are given in expression-list-or-all. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

SetMaxTag Point | Curve | Surface | Volume ( expression )

Force the maximum tag for a category of entities to a given value, so that subsequently created entities in the same category will not have tags smaller than the given value.

< Recursive > Hide { <Physical> Point | Curve | Surface | Volume { expression-list-or-all }; … }

Hide the entities listed in expression-list-or-all.

Hide { : }

Hide all entities.

< Recursive > Show { <Physical> Point | Curve | Surface | Volume { expression-list-or-all }; … }

Show the entities listed in expression-list-or-all.

Show { : }

Show all entities.

Sphere | PolarSphere ( expression ) = {expression, expression};

Change the current (surface) geometry used by the built-in geometry kernel to a (polar) sphere, defined by the two point tags specified on the right hand side. The expression between parentheses on the left hand side specifies a new unique tag for this geometry.

Parametric Surface ( expression ) = "string" "string" "string";

Change the current (surface) geometry used by the built-in geometry kernel to a parametric surface defined by the three strings expression evaluating to the x, y and z coordinates. The expression between parentheses on the left hand side specifies a new unique tag for this geometry.

Coordinates Surface expression;

Change the current (surface) geometry used by the built-in geometry kernel to the geometry identified by the given expression.

Euclidian Coordinates ;

Restore the default planar geometry for the built-in geometry kernel.

5.3 Mesh scripting commands

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

5.3.1 Mesh element sizes

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

MeshSize { expression-list } = expression;

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

Field[expression] = string;

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

Field[expression].string = string-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).

5.3.2 Structured grids

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

Extrude 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, for an example.

For curve 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 tags 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 tag of the new “top” surface in num[0] and the tag 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 nodes. QuadTriAddVerts works in a similar way, but subdivides 3D elements touching the boundary triangles by adding a new node inside each element at the node-based centroid. Either method results in a structured extrusion with an outer layer of subdivided elements that interface the inner, unmodified elements to the triangle-meshed region boundaries.

In some rare cases, due to certain lateral boundary conditions, it may not be possible make a valid element subdivision with QuadTriNoNewVerts without adding additional nodes. In this case, an internal node is created at the node-based centroid of the element. The element is then divided using that node. When an internal node is created with 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 }

Extrude both the geometry and the mesh using a rotation (see Extrusions). The layers option is defined as above. With the built-in geometry kernel the angle should be strictly smaller than Pi. With the OpenCASCADE kernel the angle should be strictly smaller than 2 Pi.

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

Extrude both the geometry and the mesh using a combined translation and rotation (see Extrusions). The layers option is defined as above. With the built-in geometry kernel the angle should be strictly smaller than Pi. With the OpenCASCADE kernel the angle should be strictly smaller than 2 Pi.

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

Extrude a “topological” boundary layer from the specified surfaces. If no view is specified, the mesh of the boundary layer entities is created using a gouraud-shaded (smoothed) normal field. If a scalar view is specified, it locally prescribes the thickness of the layer. If a vector-valued view is specified it locally prescribes both the extrusion direction and the thickness. Specifying a boundary layer index allows to extrude several independent boundary layers (with independent normal smoothing). ScaleLastLayer scales the height of the last (top) layer of each normal’s extrusion by the average length of the edges in all the source elements that contain the source node (actually, the average of the averages for each element–edges actually touching the source node are counted twice). This allows the height of the last layer to vary along with the size of the source elements in order to achieve better element quality. For example, in a boundary layer extruded with the Layers definition ’Layers{ {1,4,2}, {0.5, 0.6, 1.6} },’ a source node adjacent to elements with an overall average edge length of 5.0 will extrude to have a last layer height = (1.6-0.6) * 5.0 = 5.0. Topological boundary layers are only available with the built-in kernel. See sphere_boundary_layer.geo or sphere_boundary_layer_from_view.geo for .geo file examples, and aneurysm.py for an API example.

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

Transfinite Curve { expression-list-or-all } = expression < Using Progression | Bump expression >;

Select the curves 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 curve (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 curve. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

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

Select surfaces to be meshed with the 2D transfinite algorithm. The expression-list on the right-hand-side should contain the tags of three or four points on the boundary of the surface that define the corners of the transfinite interpolation. If no tags are given, the transfinite algorithm will try to find the corners automatically. The optional argument specifies the way the triangles are oriented when the mesh is not recombined. Alternate is a synonym for AlternateRight. For 3-sided surfaces a specific algorithm can be used to generate structured triangular by setting Mesh.TransfiniteTri to 1. Examples can be found in benchmarks/transfinite. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Transfinite Volume { expression-list } < = { expression-list } > ;

Select five- or six-face volumes to be meshed with the 3D transfinite algorithm. The expression-list on the right-hand-side should contain the tags of the six or eight points on the boundary of the volume that define the corners of the transfinite interpolation. If no tags are given, the transfinite algorithm will try to find the corners automatically. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

TransfQuadTri { expression-list } ;

Apply the transfinite QuadTri algorithm on the expression-list list of 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. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

5.3.3 Other mesh commands

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

Mesh expression;

Generate expression-D mesh. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

TransformMesh { expression-list };

Transform all the node coordinates in the current mesh using the 4x4 affine transformation matrix given by row (only 12 entries can be provided for convenience).

TransformMesh { expression-list } { transform-list };

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

RefineMesh;

Refine the current mesh by splitting all elements. If Mesh.SecondOrderLinear is set, the new nodes are inserted by linear interpolation. Otherwise they are snapped on the actual geometry. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

OptimizeMesh string-expression;

Optimize the current mesh with the given algorithm (currently "Gmsh" for default tetrahedral mesh optimizer, "Netgen" for Netgen optimizer, "HighOrder" for direct high-order mesh optimizer, "HighOrderElastic" for high-order elastic smoother, "HighOrderFastCurving" for fast curving algorithm, "UntangleTets'' for untangling tetrahedral meshes, "UntangleTris'' for untangling xy-planar triangular meshes, "Laplace2D" for Laplace smoothing, "Relocate2D" and "Relocate3D" for node relocation).

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

Perform adaptive mesh generation. Documentation not yet available.

RelocateMesh Point | Curve | Surface { expression-list-or-all };

Relocate the mesh nodes on the given entities using the parametric coordinates stored in the nodes. Useful for creating perturbation of meshes e.g. for sensitivity analyzes. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

RecombineMesh;

Recombine the current mesh into quadrangles. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

SetOrder expression;

Change the order of the elements in the current mesh.

PartitionMesh expression;

Partition the mesh into expression, using current partitioning options.

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

Add a meshing constraint to embed the point(s) or curve(s) in the given surface. The surface mesh will conform to the mesh of the point(s) or curves(s). This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Point | Curve | Surface { expression-list } In Volume { expression };

Add a meshing constraint to embed the point(s), curve(s) or surface(s) in the given volume. The volume mesh will conform to the mesh of the corresponding point(s), curve(s) or surface(s). This is only supported with the 3D Delaunay algorithms. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

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

Add a meshing constraint to force the mesh of the curves on the left-hand side to match the mesh of the curves on the right-hand side (masters). If used after meshing, generate the periodic node correspondence information assuming the mesh of the curves on the left-hand side effectively matches the mesh of the curves on the right-hand side. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

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

Add a meshing constraint to force the mesh of the surface on the left-hand side (with boundary edges specified between braces) to match the mesh of the master surface on the right-hand side (with boundary edges specified between braces). If used after meshing, generate the periodic node correspondence information assuming the mesh of the surface on the left-hand side effectively matches the mesh of the master surface on the right-hand side (useful for structured and extruded meshes). This operation triggers a synchronization of the CAD model with the internal Gmsh model.

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

Add a meshing constraint to force mesh of curves or surfaces on the left-hand side to match the mesh of the curves or surfaces on the right-hand side (masters), using prescribed geometrical transformations. If used after meshing, generate the periodic node correspondence information assuming the mesh of the curves or surfaces on the left-hand side effectively matches the mesh of the curves or surfaces on the right-hand side (useful for structured and extruded meshes). Affine takes a 4 x 4 affine transformation matrix given by row (only 12 entries can be provided for convenience); Translate takes the 3 components of the translation as in Transformations. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Periodic Curve | Surface { expression-list } = { expression-list } Rotate { expression-list }, { expression-list }, expression } ;

Add a meshing constraint to force the mesh of curves or surfaces on the left-hand side to match the mesh of the curves on the right-hand side (masters), using a rotation specified as in Transformations. If used after meshing, generate the periodic node correspondence information assuming the mesh of the curves or surfaces on the left-hand side effectively matches the mesh of the curves or surfaces on the right-hand side (useful for structured and extruded meshes). This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Coherence Mesh;

Remove all duplicate mesh nodes in the current mesh.

CreateTopology < { expression , expression } > ;

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

CreateGeometry < { <Physical> Point | Curve | Surface | Volume { expression-list-or-all }; … } > ;

Create a geometry for discrete entities (represented solely by a mesh, without an underlying CAD description) in the current model, i.e. create a parametrization for discrete curves and surfaces, assuming that each can be parametrized with a single map. If no entities are given, create a geometry for all discrete entities.

ClassifySurfaces { expression , expression , expression < , expression > };

Classify (“color”) the current surface mesh based on an angle threshold (the first argument, in radians), and create new discrete surfaces, curves and points accordingly. If the second argument is set, also create discrete curves on the boundary if the surface is open. If the third argument is set, create edges and surfaces that can be reparametrized with CreateGeometry. The last optional argument sets an angle threshold to force splitting of the generated curves.

RenumberMeshNodes;

Renumber the node tags in the current mesh in a continuous sequence.

RenumberMeshElements;

Renumber the elements tags in the current mesh in a continuous sequence.

< Recursive > Color color-expression { <Physical> Point | Curve | Surface | Volume { expression-list-or-all }; … }

Set the mesh color of the entities in expression-list to color-expression. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Recombine Surface { expression-list-or-all } < = expression >;

Recombine 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). This operation triggers a synchronization of the CAD model with the internal Gmsh model.

MeshAlgorithm Surface { expression-list } = expression;

Specify the meshing algorithm for the surfaces expression-list.

MeshSizeFromBoundary Surface { expression-list } = expression;

Force the mesh size to be extended from the boundary (or not, depending on the value of expression) for the surfaces expression-list.

Compound Curve | Surface { expression-list-or-all } ;

Treat the given entities as a single entity when meshing, i.e. perform cross-patch meshing of the entities.

ReverseMesh Curve | Surface { expression-list-or-all } ;

Add a constraint to reverse the orientation of the mesh of the given curve(s) or surface(s) during meshing. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

ReorientMesh Volume { expression-list } ;

Add a constraint to reorient the meshes (during mesh generation) of the bounding surfaces of the given volumes so that the normals point outward to the volumes; and if a mesh already exists, reorient it. Currently only available with the OpenCASCADE kernel, as it relies on the STL triangulation. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Save string-expression;

Save the current mesh in a file named string-expression, using the current Mesh.Format (see Mesh options). If the path in string-expression is not absolute, string-expression is appended to the path of the current file. This operation triggers a synchronization of the CAD model with the internal Gmsh model.

Smoother Surface { expression-list } = expression;

Set the number of elliptic smoothing steps for the surfaces listed in expression-list (smoothing only applies to transfinite meshes at the moment). This operation triggers a synchronization of the CAD model with the internal Gmsh model.

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.

5.4 Post-processing scripting commands

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

Alias View[expression];

Create 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];

Create 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;

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

Combine ElementsFromAllViews | Combine Views;

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

Combine ElementsFromVisibleViews;

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

Combine TimeStepsByViewName | Combine TimeSteps;

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

Combine TimeStepsFromAllViews;

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

Combine TimeStepsFromVisibleViews;

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

Delete View[expression];

Delete (remove) the expression-th post-processing view. Note that post-processing view indices start at 0.

Delete Empty Views;

Delete (remove) all the empty post-processing views.

Background Mesh View[expression];

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

Plugin (string) . Run;

Execute the plugin string. The list of default plugins is given in Gmsh plugins.

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

Set an option for a given plugin. See Gmsh plugins, for a list of default plugins and t9, for some examples.

Save View[expression] string-expression;

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

SendToServer View[expression] string-expression;

Send the expression-th post-processing view to the ONELAB server, with parameter name string-expression.

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

Create 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), 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 Gmsh 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 ( coordinates ) { 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  #coordinates  #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 coordinates give the X-Y position of the string in screen coordinates, measured from the top-left corner of the window. If the first (respectively second) 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 coordinates 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 values can contain an arbitrary number of string-expressions. If the string-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 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 coordinates). 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 geo-coef-matrix denotes the m x m matrix G and geo-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}
};

6 Gmsh application programming interface

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

The different versions of the API are generated automatically from the master API definition file api/gen.py:

• C++ API: gmsh.h
• C API: gmshc.h
• Python API: gmsh.py
• Julia API: gmsh.jl
• Fortran API: gmsh.f90

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

The structure of the API reflects the underlying Gmsh data model (see also Source code structure):

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

All the functions available in the API are given below. See the relevant header/module file for the exact definition in each supported language: in C++ gmsh/model/geo/addPoint will lead to a namespaced function gmsh::model::geo::addPoint, while in Python and Julia it will lead to gmsh.model.geo.addPoint, in C to gmshModelGeoAddPoint and in Fortran to gmsh%model%geo%addPoint. In addition to the default “camelCase” function names, the Python and Julia APIs also define “snake case” aliases, i.e. gmsh.model.geo.add_point, as this is the recommended style in these languages. Output values are passed by reference in C++, as pointers in C and directly returned (after the return value, if any) in Python and Julia.

6.1 Namespace gmsh: top-level functions

gmsh/initialize

Initialize the Gmsh API. This must be called before any call to the other functions in the API. If argc and argv (or just argv in Python or Julia) are provided, they will be handled in the same way as the command line arguments in the Gmsh app. If readConfigFiles is set, read system Gmsh configuration files (gmshrc and gmsh-options). If run is set, run in the same way as the Gmsh app, either interactively or in batch mode depending on the command line arguments. If run is not set, initializing the API sets the options "General.AbortOnError" to 2 and "General.Terminal" to 1.

Input:

(argc = 0), argv = [] (command line arguments), readConfigFiles = True (boolean), run = False (boolean)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t1.cpp, t2.cpp, t3.cpp, t4.cpp, t5.cpp, ...), Python (t1.py, t2.py, t3.py, t4.py, t5.py, ...)

gmsh/isInitialized

Return 1 if the Gmsh API is initialized, and 0 if not.

Input:

-

Output:

-

Return:

integer

Language-specific definition:

C++, C, Python, Julia

gmsh/finalize

Finalize the Gmsh API. This must be called when you are done using the Gmsh API.

Input:

-

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t1.cpp, t2.cpp, t3.cpp, t4.cpp, t5.cpp, ...), Python (t1.py, t2.py, t3.py, t4.py, t5.py, ...)

gmsh/open

Open a file. Equivalent to the File->Open menu in the Gmsh app. Handling of the file depends on its extension and/or its contents: opening a file with model data will create a new model.

Input:

fileName (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x1.cpp), Python (x1.py, explore.py, flatten2.py, flatten.py, heal.py, ...)

gmsh/merge

Merge a file. Equivalent to the File->Merge menu in the Gmsh app. Handling of the file depends on its extension and/or its contents. Merging a file with model data will add the data to the current model.

Input:

fileName (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t7.cpp, t8.cpp, t9.cpp, t13.cpp, t17.cpp), Python (t7.py, t8.py, t9.py, t13.py, t17.py, ...)

gmsh/write

Write a file. The export format is determined by the file extension.

Input:

fileName (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t1.cpp, t2.cpp, t3.cpp, t4.cpp, t5.cpp, ...), Python (t1.py, t2.py, t3.py, t4.py, t5.py, ...)

gmsh/clear

Clear all loaded models and post-processing data, and add a new empty model.

Input:

-

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t3.cpp, x1.cpp), Python (t3.py, t13.py, x1.py, x3d_export.py)

6.2 Namespace gmsh/option: option handling functions

gmsh/option/setNumber

Set a numerical option to value. name is of the form "Category.Option" or "Category[num].Option". Available categories and options are listed in the "Gmsh options" chapter of the Gmsh reference manual.

Input:

name (string), value (double)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t3.cpp, t5.cpp, t6.cpp, t7.cpp, t8.cpp, ...), Python (t3.py, t5.py, t6.py, t7.py, t8.py, ...)

gmsh/option/getNumber

Get the value of a numerical option. name is of the form "Category.Option" or "Category[num].Option". Available categories and options are listed in the "Gmsh options" chapter of the Gmsh reference manual.

Input:

name (string)

Output:

value (double)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t8.cpp), Python (t8.py, test.py)

gmsh/option/setString

Set a string option to value. name is of the form "Category.Option" or "Category[num].Option". Available categories and options are listed in the "Gmsh options" chapter of the Gmsh reference manual.

Input:

name (string), value (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t4.cpp), Python (t4.py, step_header_data.py)

gmsh/option/getString

Get the value of a string option. name is of the form "Category.Option" or "Category[num].Option". Available categories and options are listed in the "Gmsh options" chapter of the Gmsh reference manual.

Input:

name (string)

Output:

value (string)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (test.py)

gmsh/option/setColor

Set a color option to the RGBA value (r, g, b, a), where where r, g, b and a should be integers between 0 and 255. name is of the form "Category.Color.Option" or "Category[num].Color.Option". Available categories and options are listed in the "Gmsh options" chapter of the Gmsh reference manual. For conciseness "Color." can be ommitted in name.

Input:

name (string), r (integer), g (integer), b (integer), a = 255 (integer)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t3.cpp, t8.cpp), Python (t3.py, t8.py)

gmsh/option/getColor

Get the r, g, b, a value of a color option. name is of the form "Category.Color.Option" or "Category[num].Color.Option". Available categories and options are listed in the "Gmsh options" chapter of the Gmsh reference manual. For conciseness "Color." can be ommitted in name.

Input:

name (string)

Output:

r (integer), g (integer), b (integer), a (integer)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t3.cpp), Python (t3.py)

gmsh/option/restoreDefaults

Restore all options to default settings.

Input:

-

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

6.3 Namespace gmsh/model: model functions

gmsh/model/add

Add a new model, with name name, and set it as the current model.

Input:

name (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t1.cpp, t2.cpp, t3.cpp, t4.cpp, t6.cpp, ...), Python (t1.py, t2.py, t3.py, t4.py, t5.py, ...)

gmsh/model/remove

Remove the current model.

Input:

-

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/list

List the names of all models.

Input:

-

Output:

names (vector of strings)

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getCurrent

Get the name of the current model.

Input:

-

Output:

name (string)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x1.cpp), Python (x1.py, explore.py)

gmsh/model/setCurrent

Set the current model to the model with name name. If several models have the same name, select the one that was added first.

Input:

name (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (copy_mesh.py)

gmsh/model/getFileName

Get the file name (if any) associated with the current model. A file name is associated when a model is read from a file on disk.

Input:

-

Output:

fileName (string)

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/setFileName

Set the file name associated with the current model.

Input:

fileName (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getEntities

Get all the entities in the current model. A model entity is represented by two integers: its dimension (dim == 0, 1, 2 or 3) and its tag (its unique, strictly positive identifier). If dim is >= 0, return only the entities of the specified dimension (e.g. points if dim == 0). The entities are returned as a vector of (dim, tag) pairs.

Input:

dim = -1 (integer)

Output:

dimTags (vector of pairs of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t13.cpp, t16.cpp, t18.cpp, t20.cpp, t21.cpp, ...), Python (t13.py, t16.py, t18.py, t20.py, t21.py, ...)

gmsh/model/setEntityName

Set the name of the entity of dimension dim and tag tag.

Input:

dim (integer), tag (integer), name (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getEntityName

Get the name of the entity of dimension dim and tag tag.

Input:

dim (integer), tag (integer)

Output:

name (string)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x1.cpp), Python (x1.py, step_assembly.py)

gmsh/model/removeEntityName

Remove the entity name name from the current model.

Input:

name (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getPhysicalGroups

Get all the physical groups in the current model. If dim is >= 0, return only the entities of the specified dimension (e.g. physical points if dim == 0). The entities are returned as a vector of (dim, tag) pairs.

Input:

dim = -1 (integer)

Output:

dimTags (vector of pairs of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (poisson.py)

gmsh/model/getEntitiesForPhysicalGroup

Get the tags of the model entities making up the physical group of dimension dim and tag tag.

Input:

dim (integer), tag (integer)

Output:

tags (vector of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (poisson.py, test.py)

gmsh/model/getEntitiesForPhysicalName

Get the model entities (as a vector (dim, tag) pairs) making up the physical group with name name.

Input:

name (string)

Output:

dimTags (vector of pairs of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getPhysicalGroupsForEntity

Get the tags of the physical groups (if any) to which the model entity of dimension dim and tag tag belongs.

Input:

dim (integer), tag (integer)

Output:

physicalTags (vector of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x1.cpp), Python (x1.py)

gmsh/model/addPhysicalGroup

Add a physical group of dimension dim, grouping the model entities with tags tags. Return the tag of the physical group, equal to tag if tag is positive, or a new tag if tag < 0. Set the name of the physical group if name is not empty.

Input:

dim (integer), tags (vector of integers), tag = -1 (integer), name = "" (string)

Output:

-

Return:

integer

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t1.cpp, t2.cpp, t3.cpp, t5.cpp, t14.cpp, ...), Python (t1.py, t2.py, t3.py, t5.py, t14.py, ...)

gmsh/model/removePhysicalGroups

Remove the physical groups dimTags (given as a vector of (dim, tag) pairs) from the current model. If dimTags is empty, remove all groups.

Input:

dimTags = [] (vector of pairs of integers)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/setPhysicalName

Set the name of the physical group of dimension dim and tag tag.

Input:

dim (integer), tag (integer), name (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (poisson.py, step_assembly.py)

gmsh/model/getPhysicalName

Get the name of the physical group of dimension dim and tag tag.

Input:

dim (integer), tag (integer)

Output:

name (string)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x1.cpp), Python (x1.py, poisson.py)

gmsh/model/removePhysicalName

Remove the physical name name from the current model.

Input:

name (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/setTag

Set the tag of the entity of dimension dim and tag tag to the new value newTag.

Input:

dim (integer), tag (integer), newTag (integer)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getBoundary

Get the boundary of the model entities dimTags, given as a vector of (dim, tag) pairs. Return in outDimTags the boundary of the individual entities (if combined is false) or the boundary of the combined geometrical shape formed by all input entities (if combined is true). Return tags multiplied by the sign of the boundary entity if oriented is true. Apply the boundary operator recursively down to dimension 0 (i.e. to points) if recursive is true.

Input:

dimTags (vector of pairs of integers), combined = True (boolean), oriented = True (boolean), recursive = False (boolean)

Output:

outDimTags (vector of pairs of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t14.cpp, t16.cpp, t18.cpp, t19.cpp, t21.cpp), Python (t14.py, t16.py, t18.py, t19.py, t21.py, ...)

gmsh/model/getAdjacencies

Get the upward and downward adjacencies of the model entity of dimension dim and tag tag. The upward vector returns the tags of adjacent entities of dimension dim + 1; the downward vector returns the tags of adjacent entities of dimension dim - 1.

Input:

dim (integer), tag (integer)

Output:

upward (vector of integers), downward (vector of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x1.cpp), Python (x1.py)

gmsh/model/getEntitiesInBoundingBox

Get the model entities in the bounding box defined by the two points (xmin, ymin, zmin) and (xmax, ymax, zmax). If dim is >= 0, return only the entities of the specified dimension (e.g. points if dim == 0).

Input:

xmin (double), ymin (double), zmin (double), xmax (double), ymax (double), zmax (double), dim = -1 (integer)

Output:

dimTags (vector of pairs of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t16.cpp, t18.cpp, t20.cpp), Python (t16.py, t18.py, t20.py, naca_boundary_layer_3d.py)

gmsh/model/getBoundingBox

Get the bounding box (xmin, ymin, zmin), (xmax, ymax, zmax) of the model entity of dimension dim and tag tag. If dim and tag are negative, get the bounding box of the whole model.

Input:

dim (integer), tag (integer)

Output:

xmin (double), ymin (double), zmin (double), xmax (double), ymax (double), zmax (double)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t18.cpp), Python (t18.py)

gmsh/model/getDimension

Return the geometrical dimension of the current model.

Input:

-

Output:

-

Return:

integer

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x1.cpp), Python (x1.py)

gmsh/model/addDiscreteEntity

Add a discrete model entity (defined by a mesh) of dimension dim in the current model. Return the tag of the new discrete entity, equal to tag if tag is positive, or a new tag if tag < 0. boundary specifies the tags of the entities on the boundary of the discrete entity, if any. Specifying boundary allows Gmsh to construct the topology of the overall model.

Input:

dim (integer), tag = -1 (integer), boundary = [] (vector of integers)

Output:

-

Return:

integer

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x2.cpp, x4.cpp, x7.cpp), Python (x2.py, x4.py, x7.py, copy_mesh.py, cylinderFFD.py, ...)

gmsh/model/removeEntities

Remove the entities dimTags (given as a vector of (dim, tag) pairs) of the current model, provided that they are not on the boundary of (or embedded in) higher-dimensional entities. If recursive is true, remove all the entities on their boundaries, down to dimension 0.

Input:

dimTags (vector of pairs of integers), recursive = False (boolean)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t18.cpp, t20.cpp), Python (t18.py, t20.py, spherical_surf.py)

gmsh/model/getType

Get the type of the entity of dimension dim and tag tag.

Input:

dim (integer), tag (integer)

Output:

entityType (string)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t21.cpp, x1.cpp), Python (t21.py, x1.py, explore.py, partition.py)

gmsh/model/getParent

In a partitioned model, get the parent of the entity of dimension dim and tag tag, i.e. from which the entity is a part of, if any. parentDim and parentTag are set to -1 if the entity has no parent.

Input:

dim (integer), tag (integer)

Output:

parentDim (integer), parentTag (integer)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t21.cpp, x1.cpp), Python (t21.py, x1.py, explore.py, partition.py)

gmsh/model/getNumberOfPartitions

Return the number of partitions in the model.

Input:

-

Output:

-

Return:

integer

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getPartitions

In a partitioned model, return the tags of the partition(s) to which the entity belongs.

Input:

dim (integer), tag (integer)

Output:

partitions (vector of integers)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t21.cpp, x1.cpp), Python (t21.py, x1.py, explore.py, partition.py)

gmsh/model/getValue

Evaluate the parametrization of the entity of dimension dim and tag tag at the parametric coordinates parametricCoord. Only valid for dim equal to 0 (with empty parametricCoord), 1 (with parametricCoord containing parametric coordinates on the curve) or 2 (with parametricCoord containing u, v parametric coordinates on the surface, concatenated: [p1u, p1v, p2u, ...]). Return x, y, z coordinates in coord, concatenated: [p1x, p1y, p1z, p2x, ...].

Input:

dim (integer), tag (integer), parametricCoord (vector of doubles)

Output:

coord (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t2.cpp, x5.cpp), Python (t2.py, x5.py, reparamOnFace.py, terrain_stl.py)

gmsh/model/getDerivative

Evaluate the derivative of the parametrization of the entity of dimension dim and tag tag at the parametric coordinates parametricCoord. Only valid for dim equal to 1 (with parametricCoord containing parametric coordinates on the curve) or 2 (with parametricCoord containing u, v parametric coordinates on the surface, concatenated: [p1u, p1v, p2u, ...]). For dim equal to 1 return the x, y, z components of the derivative with respect to u [d1ux, d1uy, d1uz, d2ux, ...]; for dim equal to 2 return the x, y, z components of the derivative with respect to u and v: [d1ux, d1uy, d1uz, d1vx, d1vy, d1vz, d2ux, ...].

Input:

dim (integer), tag (integer), parametricCoord (vector of doubles)

Output:

derivatives (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getSecondDerivative

Evaluate the second derivative of the parametrization of the entity of dimension dim and tag tag at the parametric coordinates parametricCoord. Only valid for dim equal to 1 (with parametricCoord containing parametric coordinates on the curve) or 2 (with parametricCoord containing u, v parametric coordinates on the surface, concatenated: [p1u, p1v, p2u, ...]). For dim equal to 1 return the x, y, z components of the second derivative with respect to u [d1uux, d1uuy, d1uuz, d2uux, ...]; for dim equal to 2 return the x, y, z components of the second derivative with respect to u and v, and the mixed derivative with respect to u and v: [d1uux, d1uuy, d1uuz, d1vvx, d1vvy, d1vvz, d1uvx, d1uvy, d1uvz, d2uux, ...].

Input:

dim (integer), tag (integer), parametricCoord (vector of doubles)

Output:

derivatives (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getCurvature

Evaluate the (maximum) curvature of the entity of dimension dim and tag tag at the parametric coordinates parametricCoord. Only valid for dim equal to 1 (with parametricCoord containing parametric coordinates on the curve) or 2 (with parametricCoord containing u, v parametric coordinates on the surface, concatenated: [p1u, p1v, p2u, ...]).

Input:

dim (integer), tag (integer), parametricCoord (vector of doubles)

Output:

curvatures (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x5.cpp), Python (x5.py, normals.py)

gmsh/model/getPrincipalCurvatures

Evaluate the principal curvatures of the surface with tag tag at the parametric coordinates parametricCoord, as well as their respective directions. parametricCoord are given by pair of u and v coordinates, concatenated: [p1u, p1v, p2u, ...].

Input:

tag (integer), parametricCoord (vector of doubles)

Output:

curvatureMax (vector of doubles), curvatureMin (vector of doubles), directionMax (vector of doubles), directionMin (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getNormal

Get the normal to the surface with tag tag at the parametric coordinates parametricCoord. The parametricCoord vector should contain u and v coordinates, concatenated: [p1u, p1v, p2u, ...]. normals are returned as a vector of x, y, z components, concatenated: [n1x, n1y, n1z, n2x, ...].

Input:

tag (integer), parametricCoord (vector of doubles)

Output:

normals (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x5.cpp), Python (x5.py, normals.py)

gmsh/model/getParametrization

Get the parametric coordinates parametricCoord for the points coord on the entity of dimension dim and tag tag. coord are given as x, y, z coordinates, concatenated: [p1x, p1y, p1z, p2x, ...]. parametricCoord returns the parametric coordinates t on the curve (if dim = 1) or u and v coordinates concatenated on the surface (if dim == 2), i.e. [p1t, p2t, ...] or [p1u, p1v, p2u, ...].

Input:

dim (integer), tag (integer), coord (vector of doubles)

Output:

parametricCoord (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getParametrizationBounds

Get the min and max bounds of the parametric coordinates for the entity of dimension dim and tag tag.

Input:

dim (integer), tag (integer)

Output:

min (vector of doubles), max (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x5.cpp), Python (x5.py, reparamOnFace.py)

gmsh/model/isInside

Check if the coordinates (or the parametric coordinates if parametric is set) provided in coord correspond to points inside the entity of dimension dim and tag tag, and return the number of points inside. This feature is only available for a subset of entities, depending on the underlying geometrical representation.

Input:

dim (integer), tag (integer), coord (vector of doubles), parametric = False (boolean)

Output:

-

Return:

integer

Language-specific definition:

C++, C, Python, Julia

gmsh/model/getClosestPoint

Get the points closestCoord on the entity of dimension dim and tag tag to the points coord, by orthogonal projection. coord and closestCoord are given as x, y, z coordinates, concatenated: [p1x, p1y, p1z, p2x, ...]. parametricCoord returns the parametric coordinates t on the curve (if dim == 1) or u and v coordinates concatenated on the surface (if dim = 2), i.e. [p1t, p2t, ...] or [p1u, p1v, p2u, ...].

Input:

dim (integer), tag (integer), coord (vector of doubles)

Output:

closestCoord (vector of doubles), parametricCoord (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (closest_point.py)

gmsh/model/reparametrizeOnSurface

Reparametrize the boundary entity (point or curve, i.e. with dim == 0 or dim == 1) of tag tag on the surface surfaceTag. If dim == 1, reparametrize all the points corresponding to the parametric coordinates parametricCoord. Multiple matches in case of periodic surfaces can be selected with which. This feature is only available for a subset of entities, depending on the underlying geometrical representation.

Input:

dim (integer), tag (integer), parametricCoord (vector of doubles), surfaceTag (integer), which = 0 (integer)

Output:

surfaceParametricCoord (vector of doubles)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x5.cpp), Python (x5.py, reparamOnFace.py)

gmsh/model/setVisibility

Set the visibility of the model entities dimTags (given as a vector of (dim, tag) pairs) to value. Apply the visibility setting recursively if recursive is true.

Input:

dimTags (vector of pairs of integers), value (integer), recursive = False (boolean)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (gui.py, hybrid_order.py)

gmsh/model/getVisibility

Get the visibility of the model entity of dimension dim and tag tag.

Input:

dim (integer), tag (integer)

Output:

value (integer)

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/setVisibilityPerWindow

Set the global visibility of the model per window to value, where windowIndex identifies the window in the window list.

Input:

value (integer), windowIndex = 0 (integer)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

gmsh/model/setColor

Set the color of the model entities dimTags (given as a vector of (dim, tag) pairs) to the RGBA value (r, g, b, a), where r, g, b and a should be integers between 0 and 255. Apply the color setting recursively if recursive is true.

Input:

dimTags (vector of pairs of integers), r (integer), g (integer), b (integer), a = 255 (integer), recursive = False (boolean)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (t4.cpp), Python (t4.py, gui.py)

gmsh/model/getColor

Get the color of the model entity of dimension dim and tag tag. If no color is specified for the entity, return fully transparent blue, i.e. (0, 0, 255, 0).

Input:

dim (integer), tag (integer)

Output:

r (integer), g (integer), b (integer), a (integer)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (step_boundary_colors.py)

gmsh/model/setCoordinates

Set the x, y, z coordinates of a geometrical point.

Input:

tag (integer), x (double), y (double), z (double)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

C++ (x2.cpp), Python (x2.py, reparamOnFace.py)

gmsh/model/setAttribute

Set the values of the attribute with name name.

Input:

name (string), values (vector of strings)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (msh_attributes.py)

gmsh/model/getAttribute

Get the values of the attribute with name name.

Input:

name (string)

Output:

values (vector of strings)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (msh_attributes.py)

gmsh/model/getAttributeNames

Get the names of any optional attributes stored in the model.

Input:

-

Output:

names (vector of strings)

Return:

-

Language-specific definition:

C++, C, Python, Julia

Examples:

Python (msh_attributes.py)

gmsh/model/removeAttribute

Remove the attribute with name name.

Input:

name (string)

Output:

-

Return:

-

Language-specific definition:

C++, C, Python, Julia