[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes the general commands and options that can be used in Gmsh's ASCII text input files. By "general", we mean "not specifically related to one of the geometry, mesh, solver or post-processing modules". Commands peculiar to these modules will be introduced in 3. Geometry module, 4. Mesh module, 5. Solver module, and 6. Post-processing module, respectively.
Note that, if you are just beginning to use Gmsh, or just want to see what Gmsh is all about, you really don't need to read this chapter and the four next ones. Just have a quick look at 8. Running Gmsh, and go play with the graphical user interface, running the tutorials and demonstration files bundled in the distribution! Most of the commands and options described in the following chapters are available interactively in the GUI, so you don't need to worry about Gmsh's internals for creating your first geometries, meshes and post-processing plots. Once you master the tutorial (read the source files: they are heavily commented--see 7. Tutorial), you might want to come back here to learn more about the specific syntax of Gmsh's commands and esoteric options.
2.1 Expressions 2.2 Operators 2.3 Built-in functions 2.4 User-defined functions 2.5 Loops and conditionals 2.6 General commands 2.7 General options
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The two constant types used in Gmsh are real and string (there is no integer type). These types have the same meaning and syntax as in the C or C++ programming languages.
2.1.1 Floating point expressions 2.1.2 Character expressions 2.1.3 Color expressions
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Floating point expressions (or, more simply, "expressions") are denoted by the metasyntactic variable expression (remember the definition of the syntactic rules in 1.7 Syntactic rules used in this document), and are evaluated during the parsing of the data file:
expression: real | string | string [ expression ] | # string [ ] | ( expression ) | operator-unary-left expression | expression operator-unary-right | expression operator-binary expression | expression operator-ternary-left expression operator-ternary-right expression | built-in-function | real-option | GetValue("string", expression) |
Such expressions are used in most of Gmsh's commands. The third and fourth cases in this definition permit to extract one item from a list (see below) and get the size of a list, respectively. The operators operator-unary-left, operator-unary-right, operator-binary, operator-ternary-left and operator-ternary-right are defined in 2.2 Operators. For the definition of built-in-functions, see 2.3 Built-in functions. The various real-options are listed in 2.7 General options, 3.2 Geometry options, 4.3 Mesh options, 5.1 Solver options, and 6.3 Post-processing options.
The last case in the definition allows to ask the user for a value
interactively. For example, inserting GetValue("Value of parameter
alpha?", 5.76)
in an input file will query the user for the value of a
certain parameter alpha, assuming the default value is 5.76. If the option
General.NoPopup
is set (see section 2.7 General options), no question is
asked and the default value is automatically used.
List of expressions are also widely used, and are defined as:
expression-list: expression-list-item <, expression-list-item> ... |
with
expression-list-item: expression | expression : expression | expression : expression : expression | string [ ] | string [ { expression-list } ] | Point { expression } | transform | extrude |
The second case in this last definition permits to create a list containing the range of numbers comprised between two expressions, with a unit incrementation step. The third case also permits to create a list containing the range of numbers comprised between two expressions, but with a positive or negative incrementation step equal to the third expression. The fourth case permits to reference an expression list. The fifth case permits to reference an expression sublist (whose elements are those corresponding to the indices provided by the expression-list). The sixth case permits to retrieve the coordinates of a given geometry point (see section 3.1.1 Points). The last two cases permit to retrieve the indices of entities created through geometrical transformations and extrusions (see 3.1.6 Transformations, and 3.1.5 Extrusions).
To see the practical use of such expressions, have a look at the first
couple of examples in 7. Tutorial. Note that, in order to lighten the
syntax, you can always omit the braces {}
enclosing an
expression-list if this expression-list only contains a single
item. Also note that a braced expression-list can be preceded by a
minus sign in order to change the sign of all the
expression-list-items.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Character expressions are defined as:
char-expression: "string" | Today | StrPrefix ( char-expression ) | StrRelative ( char-expression ) | StrCat ( char-expression , char-expression ) | Sprintf ( char-expression , expression-list ) | Sprintf ( char-expression ) Sprintf ( char-option ) |
The third and fourth cases in this definition permit to take the
prefix (e.g. to remove the extension) or the relative path of a string. The
fifth case permits to concatenate two character expressions, and the sixth
and seventh are equivalent to the sprintf
C function (where
char-expression is a format string that can contain floating point
formatting characters: %e
, %g
, etc.). The last case permits to
use the value of a char-option as a char-expression. The
various char-options are listed in 2.7 General options,
3.2 Geometry options, 4.3 Mesh options, 5.1 Solver options, and
6.3 Post-processing options.
Character expressions are mostly used to specify non-numeric options and input/output file names. See 7.8 `t8.geo', for an interesting usage of char-expressions in an animation script.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Colors expressions are hybrids between fixed-length braced expression-lists and strings:
color-expression: string | { expression, expression, expression } | { expression, expression, expression, expression } | color-option |
The first case permits to use the X Windows names to refer to colors,
e.g., Red
, SpringGreen
, LavenderBlush3
, ...
(see `Common/Colors.h' in Gmsh's source tree for a complete list). The
second case permits to define colors by using three expressions to specify
their red, green and blue components (with values comprised between 0 and
255). The third case permits to define colors by using their red, green and
blue color components as well as their alpha channel. The last case permits
to use the value of a color-option as a color-expression. The
various color-options are listed in 2.7 General options,
3.2 Geometry options, 4.3 Mesh options, 5.1 Solver options, and
6.3 Post-processing options.
See 7.3 `t3.geo', for an example of the use of color expressions.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gmsh's operators are similar to the corresponding operators in C and C++. Here is the list of the unary, binary and ternary operators currently implemented.
operator-unary-left:
-
!
operator-unary-right:
++
--
operator-binary:
^
*
/
%
+
-
==
!=
>
>=
<
<=
&&
||
||
is evaluated even if the first one is true).
operator-ternary-left:
?
:
The evaluation priorities are summarized below(3) (from stronger to
weaker, i.e., *
has a highest evaluation priority than +
).
Parentheses ()
may be used anywhere to change the order of
evaluation:
()
, []
, .
, #
^
!
, ++
, --
, -
(unary)
*
, /
, %
+
, -
<
, >
, <=
, >=
==
, !=
&&
||
?:
=
, +=
, -=
, *=
, /=
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A built-in function is composed of an identifier followed by a pair of parentheses containing an expression-list (the list of its arguments)(4). Here is the list of the built-in functions currently implemented:
build-in-function:
Acos ( expression )
Asin ( expression )
Atan ( expression )
Atan2 ( expression, expression )
Ceil ( expression )
Cos ( expression )
Cosh ( expression )
Exp ( expression )
Fabs ( expression )
Fmod ( expression, expression )
Floor ( expression )
Hypot ( expression, expression )
Log ( expression )
Log10 ( expression )
Modulo ( expression, expression )
Fmod( expression, expression )
.
Rand ( expression )
Sqrt ( expression )
Sin ( expression )
Sinh ( expression )
Tan ( expression )
Tanh ( expression )
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
User-defined functions take no arguments, and are evaluated as if a file
containing the function body was included at the location of the Call
statement.
Function string
Function
string
', and can contain any Gmsh command.
Return
Call string;
See 7.5 `t5.geo', for an example of a user-defined function.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Loops and conditionals are defined as follows, and can be imbricated:
For ( expression : expression )
For ( expression :
expression )
' and the matching EndFor
are executed.
For ( expression : expression : expression )
For ( expression : expression :
expression )
' and the matching EndFor
are executed.
For string In { expression : expression }
For string In {
expression : expression }
' and the matching EndFor
are
executed.
For string In { expression : expression : expression }
For string In { expression :
expression : expression }
' and the matching EndFor
are
executed.
EndFor
For
command.
If ( expression )
If ( expression )
' and the matching
Endif
is evaluated if expression is non-zero.
EndIf
If
command.
See 7.5 `t5.geo', for an example of For
and If
commands. Gmsh
does not provide any Else
(or similar) command at the time of this
writing.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following commands can be used anywhere in a Gmsh ASCII text input file:
string = expression;
Pi
GMSH_MAJOR_VERSION
GMSH_MINOR_VERSION
GMSH_PATCH_VERSION
MPI_Size
MPI_Rank
newp
newp
permits to know the highest number already attributed (plus
one). This is mostly useful when writing user-defined functions
(see section 2.4 User-defined functions) or general geometric primitives, when one
does not know a priori which numbers are already attributed, and
which ones are still available.
newl
news
newv
newll
newsl
newreg
newreg
returns the
maximum of newp
, newl
, news
, newv
and all
physical entity numbers(5).
string [ ] = { };
string[]
with an
empty list.
string [ ] = { expression-list };
string[]
with the
list expression-list, or affects expression-list to an
existing expression list identifier. (Remember the remark we made when
we defined expression-lists: the braces enclosing an
expression-list are optional if the list only contains a single
item.)
string [ { expression-list } ] = { expression-list };
real-option = expression;
char-option = char-expression;
color-option = color-expression;
string | real-option += expression;
string | real-option -= expression;
string | real-option *= expression;
string | real-option /= expression;
string [ ] += { expression-list };
string [ { expression-list } ] += { expression-list };
string [ { expression-list } ] -= { expression-list };
string [ { expression-list } ] *= { expression-list };
string [ { expression-list } ] /= { expression-list };
Exit;
Printf ( char-expression , expression-list );
Printf
is equivalent to the printf
C function:
char-expression is a format string that can contain formatting
characters (%f
, %e
, etc.). Note that all expressions
are evaluated as floating point values in Gmsh (see section 2.1 Expressions), so
that only valid floating point formatting characters make sense in
char-expression. See 7.5 `t5.geo', for an example of the use of
Printf
.
Printf ( char-expression , expression-list ) > char-expression;
Printf
above, but output the expression in a file.
Printf ( char-expression , expression-list ) >> char-expression;
Printf
above, but appends the expression at the end of
the file.
Merge char-expression;
Draw;
BoundingBox;
BoundingBox { expression, expression, expression, expression, expression, expression };
Delete All;
Delete Physicals;
Mesh expression;
Print char-expression;
Print.Format
(see section 2.7 General options). 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] | [ ? ] |
Here is the list of the general char-options, real-options and color-options (in that order--check the default values to see the actual types). Most of these options are accessible in the graphical user interface, but not all of them. When running Gmsh interactively, changing an option in the ASCII text input 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.
Gmsh's default behavior is to save some of these options in a per-user
"session resource" file (General.SessionFileName
) every time Gmsh
is shut down. This permits for example to automatically remember the size
and location of the windows or which fonts to use. Other options can be
saved in a per-user "option" file (General.OptionsFileName
),
automatically loaded by Gmsh every time it starts up, by using the
`Tools->Options->Save as defaults' menu.
General.AxesFormatX
"%.3g"
General.OptionsFileName
General.AxesFormatY
"%.3g"
General.OptionsFileName
General.AxesFormatZ
"%.3g"
General.OptionsFileName
General.AxesLabelX
""
General.OptionsFileName
General.AxesLabelY
""
General.OptionsFileName
General.AxesLabelZ
""
General.OptionsFileName
General.DefaultFileName
"untitled.geo"
General.OptionsFileName
General.Display
""
-
General.ErrorFileName
".gmsh-errors"
General.OptionsFileName
General.FileName
""
-
General.FltkTheme
""
General.OptionsFileName
General.GraphicsFont
"Helvetica"
General.OptionsFileName
General.OptionsFileName
".gmsh-options"
General.SessionFileName
General.SessionFileName
".gmshrc"
-
General.TextEditor
"open -t %s"
General.OptionsFileName
General.TmpFileName
".gmsh-tmp"
General.SessionFileName
General.WebBrowser
"open %s"
General.OptionsFileName
General.AlphaBlending
1
General.OptionsFileName
General.Antialiasing
0
General.OptionsFileName
General.ArrowHeadRadius
0.12
General.OptionsFileName
General.ArrowStemLength
0.56
General.OptionsFileName
General.ArrowStemRadius
0.02
General.OptionsFileName
General.Axes
0
General.OptionsFileName
General.AxesMikado
0
General.OptionsFileName
General.AxesAutoPosition
1
General.OptionsFileName
General.AxesMaxX
1
General.OptionsFileName
General.AxesMaxY
1
General.OptionsFileName
General.AxesMaxZ
1
General.OptionsFileName
General.AxesMinX
0
General.OptionsFileName
General.AxesMinY
0
General.OptionsFileName
General.AxesMinZ
0
General.OptionsFileName
General.AxesTicsX
5
General.OptionsFileName
General.AxesTicsY
5
General.OptionsFileName
General.AxesTicsZ
5
General.OptionsFileName
General.BackgroundGradient
1
General.OptionsFileName
General.Clip0
0
-
General.Clip0A
1
-
General.Clip0B
0
-
General.Clip0C
0
-
General.Clip0D
0
-
General.Clip1
0
-
General.Clip1A
1
-
General.Clip1B
0
-
General.Clip1C
0
-
General.Clip1D
0
-
General.Clip2
0
-
General.Clip2A
1
-
General.Clip2B
0
-
General.Clip2C
0
-
General.Clip2D
0
-
General.Clip3
0
-
General.Clip3A
1
-
General.Clip3B
0
-
General.Clip3C
0
-
General.Clip3D
0
-
General.Clip4
0
-
General.Clip4A
1
-
General.Clip4B
0
-
General.Clip4C
0
-
General.Clip4D
0
-
General.Clip5
0
-
General.Clip5A
1
-
General.Clip5B
0
-
General.Clip5C
0
-
General.Clip5D
0
-
General.ClipFactor
5
-
General.ClipOnlyDrawIntersectingVolume
0
General.OptionsFileName
General.ClipOnlyVolume
0
General.OptionsFileName
General.ClipPositionX
650
General.SessionFileName
General.ClipPositionY
150
General.SessionFileName
General.ClipWholeElements
0
General.OptionsFileName
General.ColorScheme
1
General.OptionsFileName
General.ConfirmOverwrite
1
General.OptionsFileName
General.ContextPositionX
650
General.SessionFileName
General.ContextPositionY
150
General.SessionFileName
General.DoubleBuffer
1
General.OptionsFileName
General.DrawBoundingBoxes
0
General.OptionsFileName
General.ExpertMode
0
General.OptionsFileName
General.FastRedraw
0
General.OptionsFileName
General.FieldPositionX
650
General.SessionFileName
General.FieldPositionY
550
General.SessionFileName
General.FieldHeight
300
General.SessionFileName
General.FieldWidth
300
General.SessionFileName
General.FileChooserPositionX
200
General.SessionFileName
General.FileChooserPositionY
200
General.SessionFileName
General.FontSize
-1
General.OptionsFileName
General.GraphicsFontSize
17
General.OptionsFileName
General.GraphicsHeight
600
General.SessionFileName
General.GraphicsPositionX
50
General.SessionFileName
General.GraphicsPositionY
50
General.SessionFileName
General.GraphicsWidth
600
General.SessionFileName
General.InitialModule
0
General.OptionsFileName
General.Light0
1
General.OptionsFileName
General.Light0X
0.65
General.OptionsFileName
General.Light0Y
0.65
General.OptionsFileName
General.Light0Z
1
General.OptionsFileName
General.Light0W
0
General.OptionsFileName
General.Light1
0
General.OptionsFileName
General.Light1X
0.5
General.OptionsFileName
General.Light1Y
0.3
General.OptionsFileName
General.Light1Z
1
General.OptionsFileName
General.Light1W
0
General.OptionsFileName
General.Light2
0
General.OptionsFileName
General.Light2X
0.5
General.OptionsFileName
General.Light2Y
0.3
General.OptionsFileName
General.Light2Z
1
General.OptionsFileName
General.Light2W
0
General.OptionsFileName
General.Light3
0
General.OptionsFileName
General.Light3X
0.5
General.OptionsFileName
General.Light3Y
0.3
General.OptionsFileName
General.Light3Z
1
General.OptionsFileName
General.Light3W
0
General.OptionsFileName
General.Light4
0
General.OptionsFileName
General.Light4X
0.5
General.OptionsFileName
General.Light4Y
0.3
General.OptionsFileName
General.Light4Z
1
General.OptionsFileName
General.Light4W
0
General.OptionsFileName
General.Light5
0
General.OptionsFileName
General.Light5X
0.5
General.OptionsFileName
General.Light5Y
0.3
General.OptionsFileName
General.Light5Z
1
General.OptionsFileName
General.Light5W
0
General.OptionsFileName
General.LineWidth
1
General.OptionsFileName
General.ManipulatorPositionX
650
General.SessionFileName
General.ManipulatorPositionY
150
General.SessionFileName
General.MaxX
1
-
General.MaxY
1
-
General.MaxZ
1
-
General.MenuPositionX
800
General.SessionFileName
General.MenuPositionY
50
General.SessionFileName
General.MessagePositionX
650
General.SessionFileName
General.MessagePositionY
490
General.SessionFileName
General.MessageHeight
300
General.SessionFileName
General.MessageWidth
400
General.SessionFileName
General.MinX
0
-
General.MinY
0
-
General.MinZ
0
-
General.MouseHoverMeshes
0
General.OptionsFileName
General.MouseSelection
1
General.OptionsFileName
General.NonModalWindows
1
General.SessionFileName
General.NoPopup
0
General.OptionsFileName
General.OptionsPositionX
650
General.SessionFileName
General.OptionsPositionY
150
General.SessionFileName
General.Orthographic
1
General.OptionsFileName
General.PluginPositionX
650
General.SessionFileName
General.PluginPositionY
550
General.SessionFileName
General.PluginHeight
300
General.SessionFileName
General.PluginWidth
300
General.SessionFileName
General.PointSize
3
General.OptionsFileName
General.PolygonOffsetAlwaysOn
0
General.OptionsFileName
General.PolygonOffsetFactor
0.5
General.OptionsFileName
General.PolygonOffsetUnits
1
General.OptionsFileName
General.QuadricSubdivisions
8
General.OptionsFileName
General.RotationX
0
-
General.RotationY
0
-
General.RotationZ
0
-
General.RotationCenterGravity
1
General.OptionsFileName
General.RotationCenterX
0
-
General.RotationCenterY
0
-
General.RotationCenterZ
0
-
General.SaveOptions
0
General.SessionFileName
General.SaveSession
1
General.SessionFileName
General.ScaleX
1
-
General.ScaleY
1
-
General.ScaleZ
1
-
General.Shininess
0.4
General.OptionsFileName
General.ShininessExponent
40
General.OptionsFileName
General.SmallAxes
1
General.OptionsFileName
General.SmallAxesPositionX
-60
General.OptionsFileName
General.SmallAxesPositionY
-40
General.OptionsFileName
General.SmallAxesSize
30
General.OptionsFileName
General.SolverPositionX
650
General.SessionFileName
General.SolverPositionY
150
General.SessionFileName
General.StatisticsPositionX
650
General.SessionFileName
General.StatisticsPositionY
150
General.SessionFileName
General.SystemMenuBar
1
General.SessionFileName
General.Terminal
0
General.OptionsFileName
General.Tooltips
1
General.OptionsFileName
General.Trackball
1
General.OptionsFileName
General.TrackballQuaternion0
0
-
General.TrackballQuaternion1
0
-
General.TrackballQuaternion2
0
-
General.TrackballQuaternion3
1
-
General.TranslationX
0
-
General.TranslationY
0
-
General.TranslationZ
0
-
General.VectorType
4
General.OptionsFileName
General.Verbosity
3
General.OptionsFileName
General.VisibilityPositionX
650
General.SessionFileName
General.VisibilityPositionY
150
General.SessionFileName
General.ZoomFactor
4
General.OptionsFileName
General.Color.Background
{255,255,255}
General.OptionsFileName
General.Color.BackgroundGradient
{128,147,255}
General.OptionsFileName
General.Color.Foreground
{85,85,85}
General.OptionsFileName
General.Color.Text
{0,0,0}
General.OptionsFileName
General.Color.Axes
{0,0,0}
General.OptionsFileName
General.Color.SmallAxes
{0,0,0}
General.OptionsFileName
General.Color.AmbientLight
{25,25,25}
General.OptionsFileName
General.Color.DiffuseLight
{255,255,255}
General.OptionsFileName
General.Color.SpecularLight
{255,255,255}
General.OptionsFileName
Print.EpsBackground
1
General.OptionsFileName
Print.EpsBestRoot
1
General.OptionsFileName
Print.EpsCompress
0
General.OptionsFileName
Print.EpsLineWidthFactor
0.5
General.OptionsFileName
Print.EpsOcclusionCulling
1
General.OptionsFileName
Print.EpsPointSizeFactor
1
General.OptionsFileName
Print.EpsPS3Shading
0
General.OptionsFileName
Print.EpsQuality
1
General.OptionsFileName
Print.Format
10
General.OptionsFileName
Print.GeoLabels
1
General.OptionsFileName
Print.GifDither
0
General.OptionsFileName
Print.GifInterlace
0
General.OptionsFileName
Print.GifSort
1
General.OptionsFileName
Print.GifTransparent
0
General.OptionsFileName
Print.JpegQuality
100
General.OptionsFileName
Print.JpegSmoothing
0
General.OptionsFileName
Print.PostElementary
1
General.OptionsFileName
Print.PostElement
0
General.OptionsFileName
Print.PostGamma
0
General.OptionsFileName
Print.PostEta
0
General.OptionsFileName
Print.PostRho
0
General.OptionsFileName
Print.TexAsEquation
0
General.OptionsFileName
Print.Text
1
General.OptionsFileName
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |