[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
Gmsh script files support both C and C++ style comments:
/*
and */
pairs is ignored;
//
is ignored.
These commands won't have the described effects inside double quotes or inside keywords. Also note that `white space' (spaces, tabs, new line characters) is ignored inside all expressions.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
Gmsh's operators are similar to the corresponding operators in C and C++. Here is the list of the unary, binary and ternary operators currently implemented.
operator-unary-left:
-
!
operator-unary-right:
++
--
operator-binary:
^
*
/
%
+
-
==
!=
>
>=
<
<=
&&
||
||
is evaluated even if the first one is true).
operator-ternary-left:
?
:
The evaluation priorities are summarized below(5) (from stronger to
weaker, i.e., *
has a highest evaluation priority than +
).
Parentheses ()
may be used anywhere to change the order of
evaluation:
()
, []
, .
, #
^
!
, ++
, --
, -
(unary)
*
, /
, %
+
, -
<
, >
, <=
, >=
==
, !=
&&
||
?:
=
, +=
, -=
, *=
, /=
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A built-in function is composed of an identifier followed by a pair of parentheses containing an expression-list (the list of its arguments)(6). Here is the list of the built-in functions currently implemented:
build-in-function:
Acos ( expression )
Asin ( expression )
Atan ( expression )
Atan2 ( expression, expression )
Ceil ( expression )
Cos ( expression )
Cosh ( expression )
Exp ( expression )
Fabs ( expression )
Fmod ( expression, expression )
Floor ( expression )
Hypot ( expression, expression )
Log ( expression )
Log10 ( expression )
Modulo ( expression, expression )
Fmod( expression, expression )
.
Rand ( expression )
Sqrt ( expression )
Sin ( expression )
Sinh ( expression )
Tan ( expression )
Tanh ( expression )
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
User-defined functions take no arguments, and are evaluated as if a file
containing the function body was included at the location of the Call
statement.
Function string
Function
string
', and can contain any Gmsh command.
Return
Call string;
See 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] | [ ? ] |
Loops and conditionals are defined as follows, and can be imbricated:
For ( expression : expression )
For ( expression :
expression )
' and the matching EndFor
are executed.
For ( expression : expression : expression )
For ( expression : expression :
expression )
' and the matching EndFor
are executed.
For string In { expression : expression }
For string In {
expression : expression }
' and the matching EndFor
are
executed.
For string In { expression : expression : expression }
For string In { expression :
expression : expression }
' and the matching EndFor
are
executed.
EndFor
For
command.
If ( expression )
If ( expression )
' and the matching
Endif
is evaluated if expression is non-zero.
EndIf
If
command.
See 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] | [ ? ] |
The following commands can be used anywhere in a Gmsh script:
string = expression;
Pi
GMSH_MAJOR_VERSION
GMSH_MINOR_VERSION
GMSH_PATCH_VERSION
MPI_Size
MPI_Rank
newp
newp
permits to know the highest number already attributed (plus
one). This is mostly useful when writing user-defined functions
(see section 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
news
newv
newll
newsl
newreg
newreg
returns
the maximum of newp
, newl
, news
, newv
,
newll
, newsl
and all physical entity numbers(7).
string [ ] = { };
string[]
with an
empty list.
string [ ] = { expression-list };
string[]
with the
list expression-list, or affects expression-list to an
existing expression list identifier. (Remember the remark we made when
we defined expression-lists: the braces enclosing an
expression-list are optional if the list only contains a single
item.)
string [ { expression-list } ] = { expression-list };
real-option = expression;
char-option = char-expression;
color-option = color-expression;
string | real-option += expression;
string | real-option -= expression;
string | real-option *= expression;
string | real-option /= expression;
string [ ] += { expression-list };
string [ { expression-list } ] += { expression-list };
string [ { expression-list } ] -= { expression-list };
string [ { expression-list } ] *= { expression-list };
string [ { expression-list } ] /= { expression-list };
Exit;
Printf ( char-expression , expression-list );
Printf
is equivalent to the printf
C function:
char-expression is a format string that can contain formatting
characters (%f
, %e
, etc.). Note that all expressions
are evaluated as floating point values in Gmsh (see section 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;
Printf
above, but output the expression in a file.
Printf ( char-expression , expression-list ) >> char-expression;
Printf
above, but appends the expression at the end of
the file.
Merge char-expression;
Draw;
BoundingBox;
BoundingBox { expression, expression, expression, expression, expression, expression };
Delete Model;
Delete Physicals;
Delete Variables;
Delete string;
Mesh expression;
Print char-expression;
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;
System char-expression;
Include char-expression;
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |