[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. General tools

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

4.1 Comments  
4.2 Expressions  
4.3 Operators  
4.4 Built-in functions  
4.5 User-defined functions  
4.6 Loops and conditionals  
4.7 General commands  
4.8 General options  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Comments

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

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

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Expressions

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

4.2.1 Floating point expressions  
4.2.2 Character expressions  
4.2.3 Color expressions  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.1 Floating point expressions

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

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

Such expressions are used in most of Gmsh's scripting commands. The third and fourth cases in this definition permit to extract one item from a list (see below) and get the size of a list, respectively. The operators operator-unary-left, operator-unary-right, operator-binary, operator-ternary-left and operator-ternary-right are defined in 4.3 Operators. For the definition of built-in-functions, see 4.4 Built-in functions. The various real-options are listed in B. Options.

The last case in the definition allows to ask the user for a value interactively. For example, inserting GetValue("Value of parameter alpha?", 5.76) in an input file will query the user for the value of a certain parameter alpha, assuming the default value is 5.76. If the option General.NoPopup is set (see section B.1 General options list), no question is asked and the default value is automatically used.

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

 
expression-list:
  expression-list-item <, expression-list-item> ...

with

 
expression-list-item:
  expression |
  expression : expression |
  expression : expression : expression |
  string [ ] |
  string [ { expression-list } ] |
  Point { expression } |
  transform |
  extrude

The second case in this last definition permits to create a list containing the range of numbers comprised between two expressions, with a unit incrementation step. The third case also permits to create a list containing the range of numbers comprised between two expressions, but with a positive or negative incrementation step equal to the third expression. The fourth case permits to reference an expression list. The fifth case permits to reference an expression sublist (whose elements are those corresponding to the indices provided by the expression-list). The sixth case permits to retrieve the coordinates of a given geometry point (see section 5.1.1 Points). The last two cases permit to retrieve the indices of entities created through geometrical transformations and extrusions (see 5.1.6 Transformations, and 5.1.5 Extrusions).

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.2 Character expressions

Character expressions are defined as:

 
char-expression:
  "string" |
  Today |
  StrPrefix ( char-expression ) |
  StrRelative ( char-expression ) |
  StrCat ( char-expression , char-expression ) |
  Sprintf ( char-expression , expression-list ) |
  Sprintf ( char-expression )
  Sprintf ( char-option )

The third and fourth cases in this definition permit to take the prefix (e.g. to remove the extension) or the relative path of a string. The fifth case permits to concatenate two character expressions, and the sixth and seventh are equivalent to the sprintf C function (where char-expression is a format string that can contain floating point formatting characters: %e, %g, etc.). The last case permits to use the value of a char-option as a char-expression. The various char-options are listed in B. Options.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.3 Color expressions

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

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

The first case permits to use the X Windows names to refer to colors, e.g., Red, SpringGreen, LavenderBlush3, ... (see `Common/Colors.h' in 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 B. Options.

See A.3 `t3.geo', for an example of the use of color expressions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Operators

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

operator-unary-left:

-
Unary minus.
!
Logical not.

operator-unary-right:

++
Post-incrementation.
--
Post-decrementation.

operator-binary:

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

operator-ternary-left:

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

The evaluation priorities are summarized below(5) (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. =, +=, -=, *=, /=


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 Built-in functions

A built-in function is composed of an identifier followed by a pair of parentheses containing an expression-list (the list of its arguments)(6). Here is the list of the built-in functions currently implemented:

build-in-function:

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

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

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

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

Ceil ( expression )
Rounds expression up to the nearest integer.

Cos ( expression )
Cosine of expression.

Cosh ( expression )
Hyperbolic cosine of expression.

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

Fabs ( expression )
Absolute value of expression.

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

Floor ( expression )
Rounds expression down to the nearest integer.

Hypot ( expression, expression )
Returns the square root of the sum of the square of its two arguments.

Log ( expression )
Natural logarithm of expression (expression > 0).

Log10 ( expression )
Base 10 logarithm of expression (expression > 0).

Modulo ( expression, expression )
see Fmod( expression, expression ).

Rand ( expression )
Random number between zero and expression.

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5 User-defined functions

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

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

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

Call string;
Executes the body of a (previously defined) function named string.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6 Loops and conditionals

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

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

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

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

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

EndFor
Ends a matching For command.

If ( expression )
The body enclosed between `If ( expression )' and the matching Endif is evaluated if expression is non-zero.

EndIf
Ends a matching If command.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7 General commands

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

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

Pi
Returns 3.1415926535897932.

GMSH_MAJOR_VERSION
Returns Gmsh's major version number.

GMSH_MINOR_VERSION
Returns Gmsh's minor version number.

GMSH_PATCH_VERSION
Returns Gmsh's patch version number.

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

MPI_Rank
Returns the rank of the current processor.

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

newl
Returns the next available line number.

news
Returns the next available surface number.

newv
Returns the next available volume number.

newll
Returns the next available line loop number.

newsl
Returns the next available surface loop number.

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

string [ ] = { };
Creates a new expression list identifier string[] with an empty list.

string [ ] = { expression-list };
Creates a new expression list identifier string[] with the list expression-list, or affects expression-list to an existing expression list identifier. (Remember the remark we made when we defined expression-lists: the braces enclosing an expression-list are optional if the list only contains a single item.)

string [ { expression-list } ] = { expression-list };
Affects each item in the right hand side expression-list to the elements (indexed by the left hand side expression-list) of an existing expression list identifier. The two expression-lists must contain the same number of items.

real-option = expression;
Affects expression to a real option.

char-option = char-expression;
Affects char-expression to a character option.

color-option = color-expression;
Affects color-expression to a color option.

string | real-option += expression;
Adds and affects expression to an existing expression identifier or to a real option.

string | real-option -= expression;
Subtracts and affects expression to an existing expression identifier or to a real option.

string | real-option *= expression;
Multiplies and affects expression to an existing expression identifier or to a real option.

string | real-option /= expression;
Divides and affects expression to an existing expression identifier or to a real option.

string [ ] += { expression-list };
Appends expression-list to an existing expression list or creates a new expression list with expression-list).

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

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

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

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

Exit;
Aborts the current script.

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

Printf ( char-expression , expression-list ) > char-expression;
Same as Printf above, but output the expression in a file.

Printf ( char-expression , expression-list ) >> char-expression;
Same as Printf above, but appends the expression at the end of the file.

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

Draw;
Redraws the scene.

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

BoundingBox { expression, expression, expression, expression, expression, expression };
Forces the bounding box of the scene to the given expressions (X min, X max, Y min, Y max, Z min, Z max).

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

Delete Physicals;
Deletes all physical groups.

Delete Variables;
Deletes all the expressions.

Delete string;
Deletes the expression string.

Mesh expression;
Generate expression-D mesh.

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

Sleep expression;
Suspends the execution of Gmsh during expression seconds.

System char-expression;
Executes a system call.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.8 General options

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


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

Back to geuz.org/gmsh