GetDP 1.2

Patrick Dular and Christophe Geuzaine

GetDP is a scientific computation software for the numerical solution of integro-differential equations, using finite element and integral type methods. This is the GetDP Reference Manual for GetDP 1.2 (March, 18 2006).

Copying conditions		Terms and conditions of use.
Introduction		What is GetDP?
1. Overview		Quick overview of the general philosophy of GetDP.
2. Expressions		Definition of basic expressions in GetDP.
3. Objects		Definition of the 10 GetDP objects.
4. Types for objects		Definition of all available types for the 10 objects.
5. Short examples		Simple object examples.
6. Complete examples		Some simple complete examples.
7. Running GetDP		How to run GetDP on your operating system.
8. File formats		Input and output file formats.
9. Bugs, versions and credits		Contact information and ChangeLog
A. Tips and tricks		Some tips to make your life easier with GetDP.
B. Frequently asked questions		The GetDP FAQ
C. Gmsh examples		Sample Gmsh input files.
D. License		Complete copy of the license.
Concept index		Index of concepts.
Metasyntactic variable index		Index of metasyntactic variables used in this manual.
Syntax index		Index of reserved keywords in the GetDP language.

 -- The Detailed Node Listing ---

Introduction

Research and collaboration activities
Education and training activities
Industrial studies
How to read this manual

Overview

1.1 Numerical tools as objects
1.2 Syntactic rules used in this document
1.3 Comments
1.4 Includes
1.5 Which problems can GetDP actually solve?

Expressions 

2.1 Definition
2.2 Constants
2.3 Operators
2.4 Functions
2.5 Current values
2.6 Arguments
2.7 Registers
2.8 Fields
2.9 Loops and conditionals

Definition

2.3 Operators
2.2 Constants
2.4 Functions
2.5 Current values
2.8 Fields

Operators

2.3.1 Operator types
2.3.2 Evaluation order

Objects

3.1 Group: defining topological entities
3.2 Function: defining global and piecewise expressions
3.3 Constraint: specifying constraints on function spaces and formulations
3.4 FunctionSpace: building function spaces
3.5 Jacobian: defining jacobian methods
3.6 Integration: defining integration methods
3.7 Formulation: building equations
3.8 Resolution: solving systems of equations
3.9 PostProcessing: exploiting computational results
3.10 PostOperation: exporting results

Types for objects

4.1 Types for Group
4.2 Types for Function
4.3 Types for Constraint
4.4 Types for FunctionSpace
4.5 Types for Jacobian
4.6 Types for Integration
4.7 Types for Formulation
4.8 Types for Resolution
4.9 Types for PostProcessing
4.10 Types for PostOperation

Types for Function

4.2.1 Math functions
4.2.2 Extended math functions
4.2.3 Green functions
4.2.4 Type manipulation functions
4.2.5 Coordinate functions
4.2.6 Miscellaneous functions

Short examples

5.1 Constant expression examples
5.2 Group examples
5.3 Function examples
5.4 Constraint examples
5.5 FunctionSpace examples
5.6 Jacobian examples
5.7 Integration examples
5.8 Formulation examples
5.9 Resolution examples
5.10 PostProcessing examples
5.11 PostOperation examples

FunctionSpace examples

5.5.1 Nodal finite element spaces
5.5.2 High order nodal finite element space
5.5.3 Nodal finite element space with floating potentials
5.5.4 Edge finite element space
5.5.5 Edge finite element space with gauge condition
5.5.6 Coupled edge and nodal finite element spaces
5.5.7 Coupled edge and nodal finite element spaces for multiply connected domains

Formulation examples

5.8.1 Electrostatic scalar potential formulation
5.8.2 Electrostatic scalar potential formulation with floating potentials and electric charges
5.8.3 Magnetostatic 3D vector potential formulation
5.8.4 Magnetodynamic 3D or 2D magnetic field and magnetic scalar potential formulation
5.8.5 Nonlinearities, Mixed formulations, ...

Resolution examples

5.9.1 Static resolution (electrostatic problem)
5.9.2 Frequency domain resolution (magnetodynamic problem)
5.9.3 Time domain resolution (magnetodynamic problem)
5.9.4 Nonlinear time domain resolution (magnetodynamic problem)
5.9.5 Coupled formulations

Complete examples

6.1 Electrostatic problem
6.2 Magnetostatic problem
6.3 Magnetodynamic problem

File formats

8.1 Input file format
8.2 Output file format

Output file format

8.2.1 File `.pre'
8.2.2 File `.res'

Bugs, versions and credits

9.1 Bugs
9.2 Versions
9.3 Credits

Copying conditions

GetDP is "free software"; this means that everyone is free to use it and to redistribute it on a free basis. GetDP 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 GetDP that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of GetDP, that you receive source code or else can get it if you want it, that you can change GetDP or use pieces of GetDP 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 GetDP, 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 GetDP. If GetDP 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 GetDP are found in the General Public License that accompanies the source code (see section D. License). Further information about this license is available from the GNU Project webpage http://www.gnu.org/copyleft/gpl-faq.html. Detailed copyright information can be found in 9.3 Credits.

The source code and various pre-compiled versions of GetDP (for Unix, Windows and Mac OS) can be downloaded from the web site http://www.geuz.org/getdp/.

If you use GetDP, we would appreciate that you mention it in your work. References and the latest news about GetDP are always available on http://www.geuz.org/getdp/. Please send all GetDP-related questions to the public GetDP mailing list at getdp@geuz.org.

If you want to integrate GetDP into a closed-source software, or want to sell a modified closed-source version of GetDP, please contact one of the authors. You can purchase a version of GetDP under a different license, with "no strings attached" (for example allowing you to take parts of GetDP and integrate them into your own proprietary code).

Introduction

GetDP (a "General environment for the treatment of Discrete Problems") is a scientific software environment for the numerical solution of integro-differential equations, open to the coupling of physical problems (electromagnetic, thermal, etc.) as well as of numerical methods (finite element method, integral methods, etc.). It can deal with such problems of various dimensions (1D, 2D or 3D) and time states (static, transient or harmonic).

The main feature of GetDP is the closeness between its internal structure (written in C), the organization of data defining discrete problems (written by the user in ASCII data files) and the symbolic mathematical expressions of these problems. Its aim is to be welcoming and of easy use for both development and application levels: it consists of a working environment in which the definition of any problem makes use of a limited number of objects, which makes the environment structured and concise. It therefore gives researchers advanced developing tools and a large freedom in adding new functionalities.

The modeling tools provided by GetDP can be tackled at various levels of complexity: this opens the software to a wide range of activities, such as research, collaboration, education, training and industrial studies.

Research and collaboration activities
Education and training activities
Industrial studies
How to read this manual

Research and collaboration activities

The internal structure of the software is very close to the structure used to define discrete problems in the input data files. As a result, a unicity and conciseness of both development and application levels is obtained without any interface between them, which facilitates work of any kind--particularly validations. GetDP permits to rapidly develop tools for the comparison of methods and the exchange of solutions between research teams, which is one of the main aims of collaboration. Moreover, after a short training, GetDP could be used by teams as a basis for their own developments, while allowing a large freedom in the latter.

Education and training activities

The software environment consists of modeling tools applicable to various physical problems. Education and training can therefore be offered in various domains and at different levels. The closeness between the definition of discrete problems and their symbolic mathematical expressions entails that the theory and mathematical bases of numerical methods, which are essential to anyone who wants to tackle the solving of discrete problems, can be directly followed by their practical applications. These applications can be evolutionary, in the sense that the offered tools are of various levels of complexity. Everyone can tackle, step by step, according to his apprenticeship level, the tools adapted to the solving of more and more complex problems, as well as various methods for the solving of the same problem.

Industrial studies

The treatment of industrial problems can also be facilitated because GetDP is adapted to the study of a wide range of physical problems using various numerical methods. In particular, adapted made to measure and ready-to-use software could be rapidly developed for given problems.

How to read this manual

After reading 1. Overview, which depicts the general philosophy of GetDP, you might want to skip 2. Expressions, 3. Objects and 4. Types for objects and directly run the demo files bundled in the distribution on your computer (see section 7. Running GetDP). You should then open these examples with a text editor and compare their structure with the examples given in 5. Short examples and 6. Complete examples. For each new syntax element that you fall onto, you can then go back to 2. Expressions, 3. Objects, and 4. Types for objects, and find in these chapters the detailed description of the syntactic rules as well as all the available options.

Indexes for many concepts (see section Concept index) and for all the syntax elements (see section Syntax index) are available at the end of this manual.

1. Overview

1.1 Numerical tools as objects
1.2 Syntactic rules used in this document
1.3 Comments
1.4 Includes
1.5 Which problems can GetDP actually solve?

1.1 Numerical tools as objects

An assembly of computational tools (or objects) in GetDP leads to a problem definition structure, which is a transcription of the mathematical expression of the problem, and forms a text data file: the equations describing a phenomenon, written in a mathematical form adapted to a chosen numerical method, directly constitute data for GetDP.

The resolution of a discrete problem with GetDP requires the definition, in a text data file, of the GetDP objects listed (together with their dependencies) in the following figure and table.

Group --- Function Group Constraint Group, Function, (Resolution) FunctionSpace Group, Constraint, (Formulation), (Resolution) Jacobian Group Integration --- Formulation Group, Function, (Constraint), FunctionSpace, Jacobian, Integration Resolution Function, Formulation PostProcessing Group, Function, Jacobian, Integration, Formulation, Resolution PostOperation Group, PostProcessing

The gathering of all these objects constitutes the problem definition structure, which is a copy of the formal mathematical formulation of the problem. Reading the first column of the table from top to bottom pictures the working philosophy and the linking of operations peculiar to GetDP, from group definition to results visualization. The decomposition highlighted in the figure points out the separation between the objects defining the method of resolution, which may be isolated in a "black box" (bottom) and those defining the data peculiar to a given problem (top).

The computational tools which are in the center of a problem definition structure are formulations (Formulation) and function spaces (FunctionSpace). Formulations define systems of equations that have to be built and solved, while function spaces contain all the quantities, i.e., functions, fields of vectors or covectors, known or not, involved in formulations.

Each object of a problem definition structure must be defined before being referred to by others. A linking which always respects this property is the following: it first contains the objects defining particular data of a problem, such as geometry, physical characteristics and boundary conditions (i.e., Group, Function and Constraint) followed by those defining a resolution method, such as unknowns, equations and related objects (i.e., Jacobian, Integration, FunctionSpace, Formulation, Resolution and PostProcessing). The processing cycle ends with the presentation of the results (i.e., lists of numbers in various formats), defined in PostOperation fields. This decomposition points out the possibility of building black boxes, containing objects of the second group, adapted to treatment of general classes of problems that share the same resolution methods.

1.2 Syntactic rules used in this document

Here are the rules we tried to follow when writing this user's guide. Note that metasyntactic variable definitions stay valid throughout all the manual (and not only in the sections where the definitions appear). See Metasyntactic variable index, for an index of all metasyntactic variables.

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 repetition of the preceding rule.
7. For conciseness, the notation rule <, rule > ... is replaced by rule <,...>.
8. The etc symbol replaces nonlisted rules.

1.3 Comments

Both C and C++ style comments are supported and can be used in the input data files to comment selected text regions:

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

Comments cannot be used inside double quotes or inside GetDP keywords.

1.4 Includes

An input data file can be included in another input data file by placing one of the following commands (expression-char represents a file name) on a separate line, outside the GetDP objects. Any text placed after an include command on the same line is ignored.

Include expression-char #include expression-char

See 2.2 Constants, for the definition of the character expression expression-char.

1.5 Which problems can GetDP actually solve?

The preceding explanations may seem very (too) general. Which are the problems that GetDP can actually solve? To answer this question, here is a list of methods that we have considered and coupled until now:

Numerical methods

finite element method
boundary element method (experimental, undocumented)
volume integral methods (experimental, undocumented)

Geometrical models

one-dimensional models (1D)
two-dimensional models (2D), plane and axisymmetric
three-dimensional models (3D)

Time states

static states
sinusoidal and harmonic states
transient states
eigenvalue problems

These methods have been successfully applied to build coupled physical models involving electromagnetic phenomena (magnetostatics, magnetodynamics, electrostatics, electrokinetics, electrodynamics, wave propagation, lumped electric circuits), acoustic phenomena, thermal phenomena and mechanical phenomena (elasticity, rigid body movement).

As can be guessed from the preceding list, GetDP has been initially developed in the field of computational electromagnetics, which fully uses all the offered coupling features. We believe that this does not interfere with the expected generality of the software because a particular modeling forms a problem definition structure which is totally external to the software: GetDP offers computational tools; the user freely applies them to define and solve his problem.

Nevertheless, specific numerical tools will always need to be implemented to solve specific problems in areas other than those mentionned above. If you think the general phisosophy of GetDP is right for you and your problem, but you discover that GetDP lacks the tools necessary to handle it, let us know: we would love to discuss it with you. For example, at the time of this writing, many areas of GetDP would need to be improved to make GetDP as useful for computational mechanics or computational fluid dynamics as it is for computational electromagnetics... So if you have the skills and some free time, feel free to join the project: we gladly accept all code contributions!

2. Expressions

This chapter and the next two describe in a rather formal way all the commands that can be used in the ASCII text input files. If you are just beginning to use GetDP, or just want to see what GetDP is all about, you should skip this chapter and the next two for now, have a quick look at 7. Running GetDP, and run the demo problems bundled in the distribution on your computer. You should then open the `.pro' files in a text editor and compare their structure with the examples given in 5. Short examples and 6. Complete examples. Once you have a general idea of how the files are organized, you might want to come back here to learn more about the specific syntax of all the objects, and all the available options.

2.1 Definition
2.2 Constants
2.3 Operators
2.4 Functions
2.5 Current values
2.6 Arguments
2.7 Registers
2.8 Fields
2.9 Loops and conditionals

2.1 Definition

Expressions are the basic tool of GetDP. They cover a wide range of functional expressions, from constants to formal expressions containing functions (built-in or user-defined, depending on space and time, etc.), arguments, discrete quantities and their associated differential operators, etc. Note that `white space' (spaces, tabs, new line characters) is ignored inside expressions (as well as inside all GetDP objects).

Expressions are denoted by the metasyntactic variable expression (remember the definition of the syntactic rules in 1.2 Syntactic rules used in this document):

expression: ( expression ) | integer | real | constant-id | quantity | argument | current-value | register-value-set | register-value-get | operator-unary expression | expression operator-binary expression | expression operator-ternary-left expression operator-ternary-right expression | built-in-function-id [ < expression-list > ] < { expression-cst-list } > | function-id [ < expression-list > ] | < Real | Complex > [ expression ] | Dt [ expression ] | AtAnteriorTimeStep [ expression, integer ] | Order [ quantity ] | Trace [ expression, group-id ] | expression ##integer

The following sections introduce the quantities that can appear in expressions, i.e., constant terminals (integer, real) and constant expression identifiers (constant-id, expression-cst-list), discretized fields (quantity), arguments (argument), current values (current-value), register values (register-value-set, register-value-get), operators (operator-unary, operator-binary, operator-ternary-left, operator-ternary-right) and built-in or user-defined functions (built-in-function-id, function-id). The last seven cases in this definition permit to cast an expression as real or complex, get the time derivative or evaluate an expression at an anterior time step, retrieve the interpolation order of a discretized quantity, evaluate the trace of an expression, and print the value of an expression for debugging purposes.

List of expressions are defined as:

expression-list: expression <,...>

2.3 Operators
2.2 Constants
2.4 Functions
2.5 Current values
2.8 Fields

2.2 Constants

The three constant types used in GetDP are integer, real and string. These types have the same meaning and syntax as in the C or C++ programming languages. Besides general expressions (expression), purely constant expressions, denoted by the metasyntactic variable expression-cst, are also used:

expression-cst: ( expression-cst ) | integer | real | constant-id | operator-unary expression-cst | expression-cst operator-binary expression-cst | expression-cst operator-ternary-left expression-cst operator-ternary-right expression-cst | math-function-id [ < expression-cst-list > ]

List of constant expressions are defined as:

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

with

expression-cst-list-item: expression-cst | expression-cst : expression-cst | expression-cst : expression-cst : expression-cst | constant-id {} | constant-id { expression-cst-list } | List[ constant-id ] | ListAlt[ constant-id, constant-id ] | LinSpace[ expression-cst, expression-cst, expression-cst ] | LogSpace[ expression-cst, expression-cst, expression-cst ]

The second case in this last definition permits to create a list containing the range of numbers comprised between the two expression-cst, with a unit incrementation step. The third case also permits to create a list containing the range of numbers comprised between the two expression-cst, but with a positive or negative incrementation step equal to the third expression-cst. The fourth and fifth cases permit to reference constant identifiers (constant-ids) of lists of constants and constant identifiers of sublists of constants (see below for the definition of constant identifiers) . The sixth case is a synonym for the fourth. The seventh case permits to create alternate lists: the arguments of ListAlt must be constant-ids of lists of constants of the same dimension. The result is an alternate list of these constants: first constant of argument 1, first constant of argument 2, second constant of argument 1, etc. These kinds of lists of constants are for example often used for function parameters (see section 2.4 Functions). The last two cases permit to create linear and logarithmic lists of numbers, respectively.

Contrary to a general expression which is evaluated at runtime (thanks to an internal stack mechanism), an expression-cst is completely evaluated during the syntactic analysis of the problem (when GetDP reads the `.pro' file). The definition of such constants or lists of constants with identifiers can be made outside or inside any GetDP object. The syntax for the definition of constants is:

affectation: DefineConstant [ constant-id < = expression-cst > string-id < = "string" > <,...> ]; | constant-id = constant-def; | string-id = string-def; | Printf("string"); | Printf("string", expression-cst-list); | Read(constant-id); | Read(constant-id)[expression-cst];

with

constant-id: string | string ~ { expression-cst } constant-def: expression-cst-list-item | { expression-cst-list } | ListFromFile [ expression-char ] string-id: string | string ~ { expression-cst } string-def: "string" | Str[ expression-char ] | StrCat[ expression-char, expression-char ]

Notes:

1. Five constants are predefined in GetDP: Pi (3.1415926535897932), 0D (0), 1D (1), 2D (2) and 3D (3).
2. When ~{expression-cst} 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-cst. This is most useful in loops (see section 2.9 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;

3. The assignment in DefineConstant (zero if no expression-cst is given) is performed only if constant-id has not yet been defined. This kind of explicit default definition mechanism is most useful in general problem definition structures making use of a large number of generic constants, functions or groups. When exploiting only a part of a complex problem definition structure, the default definition mechanism allows to define the quantities of interest only, the others being assigned a default value (that will not be used during the processing but that avoids the error messages produced when references to undefined quantities are made).

See 5.1 Constant expression examples, as well as 5.3 Function examples, for some examples.

Character expressions are defined as follows:

expression-char: "string" | string-id | StrCat[ expression-char , expression-char ] | Sprintf( expression-char ) | Sprintf( expression-char, expression-cst-list ) | Date

The third case in this definition permits to concatenate two character expressions; the next two cases permit to print the value of variables using standard C formatting; the last case permits to access the current date.

2.3 Operators

2.3.1 Operator types
2.3.2 Evaluation order

2.3.1 Operator types

The operators in GetDP are similar to the corresponding operators in the C or C++ programming languages.

operator-unary:

-

Unary minus.

!

Logical not.

operator-binary:

^

Exponentiation. The evaluation of the both arguments must result in a scalar value.

*

Multiplication or scalar product, depending on the type of the arguments.

/\

Cross product. The evaluation of both arguments must result in vectors.

/

Division.

%

Modulo. The evaluation of the second argument must result in a scalar value.

+

Addition.

-

Subtraction.

==

Equality.

!=

Inequality.

>

Greater. The evaluation of both arguments must result in scalar values.

>=

Greater or equality. The evaluation of both arguments must result in scalar values.

<

Less. The evaluation of both arguments must result in scalar values.

<=

Less or equality. The evaluation of both arguments must result in scalar values.

&&

Logical `and'. The evaluation of both arguments must result in scalar values.

||

Logical `or'. The evaluation of both arguments must result in floating point values. Warning: the logical `or' always (unlike in C or C++) implies the evaluation of both arguments. That is, the second operand of || is evaluated even if the first one is true.

operator-ternary-left:

?

:

The only ternary operator, formed by operator-ternary-left and operator-ternary-right is defined as in the C or C++ programming languages. The ternary operator first evaluates its first argument (the expression-cst located before the ?), which must result in a scalar value. If it is true (non-zero) the second argument (located between ? and :) is evaluated and returned; otherwise the third argument (located after :) is evaluated and returned.

2.3.2 Evaluation order

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

^

- (unary), !

/\

*, /, %

+, -

<, >, <=, >=

!=, ==

&&, ||

?:

2.4 Functions

Two types of functions coexist in GetDP: user-defined functions (function-id, see 3.2 Function: defining global and piecewise expressions) and built-in functions (built-in-function-id, defined in this section).

Both types of functions are always followed by a pair of brackets [] that can possibly contain arguments (see section 2.6 Arguments). This makes it simple to distinguish a function-id or a built-in-function-id from a constant-id. As shown below, built-in functions might also have parameters, given between braces {}, and which are completely evaluated during the analysis of the syntax (since they are of expression-cst-list type):

built-in-function-id [ < expression-list > ] < { expression-cst-list } >

with

built-in-function-id: math-function-id | extended-math-function-id | green-function-id | type-function-id | coord-function-id | misc-function-id

Notes:

1. All possible values for built-in-function-id are listed in 4.2 Types for Function.
2. Classical mathematical functions (see section 4.2.1 Math functions) are the only functions allowed in a constant definition (see the definition of expression-cst in 2.2 Constants).

2.5 Current values

Current values are a special kind of arguments (see section 2.6 Arguments) which return the current integer or floating point value of an internal GetDP variable:

$Time

Value of the current time. This value is set to zero for non time dependent analyses.

$DTime

Value of the current time increment used in a time stepping algorithm.

$Theta

Current theta value in a theta time stepping algorithm.

$TimeStep

Number of the current time step in a time stepping algorithm.

$Iteration

Number of the current iteration in a nonlinear loop.

$EigenvalueReal

Real part of the current eigenvalue.

$EigenvalueImag

Imaginary part of the current eigenvalue.

$X, $XS

Value of the current (destination or source) X-coordinate.

$Y, $YS

Value of the current (destination or source) Y-coordinate.

$Z, $ZS

Value of the current (destination or source) Z-coordinate.

$A, $B, $C

Value of the current parametric coordinates used in the parametric OnGrid PostOperation (see section 4.10 Types for PostOperation).

Note:

1. The current X, Y and Z coordinates refer to the `physical world' coordinates, i.e., coordinates in which the mesh is expressed.

2.6 Arguments

Function arguments can be used in expressions and have the following syntax (integer indicates the position of the argument in the expression-list of the function, starting from 1):

argument: $integer

See 3.2 Function: defining global and piecewise expressions, and 5.3 Function examples, for more details.

2.7 Registers

In many situations, identical parts of expressions are used more than once. If this is not a problem with constant expressions (since expression-csts are evaluated only once during the analysis of the problem definition structure, cf. 2.2 Constants), it may introduce some important overhead while evaluating complex expressions (which are evaluated at runtime, thanks to an internal stack mechanism). In order to circumvent this problem, the evaluation result of any part of an expression can be saved in a register: a memory location where this partial result will be accessible without any costly reevaluation of the partial expression.

Registers have the following syntax:

register-value-set: expression#integer register-value-get: #integer

Thus, to store any part of an expression in the register 5, one should add #5 directly after the expression. To reuse the value stored in this register, one simply uses #5 instead of the expression it should replace.

See 5.3 Function examples, for an example.

2.8 Fields

A discretized quantity (defined in a function space, cf. 3.4 FunctionSpace: building function spaces) is represented between braces {}, and can only appear in well-defined expressions in Formulation (see section 3.7 Formulation: building equations) and PostProcessing (see section 3.9 PostProcessing: exploiting computational results) objects:

quantity: < quantity-dof > { < quantity-operator > quantity-id } | { < quantity-operator > quantity-id } [ expression-cst-list ]

with

quantity-id: string | string ~ { expression-cst }

and

quantity-dof:

Dof

Defines a vector of discrete quantities (vector of Degrees of freedom), to be used only in Equation terms of formulations to define (elementary) matrices. Roughly said, the Dof symbol in front of a discrete quantity indicates that this quantity is an unknown quantity, and should therefore not be considered as already computed.

BF

Indicates that only a basis function will be used (only valid with basis functions associated with regions).

quantity-operator:

d

Exterior derivative (d): applied to a p-form, gives a (p+1)-form.

Grad

Gradient: applied to a scalar field, gives a vector.

Curl

Rot

Curl: applied to a vector field, gives a vector.

Div

Divergence (div): applied to a vector field, gives a scalar.

dInv

d^(-1): applied to a p-form, gives a (p-1)-form.

GradInv

Inverse grad: applied to a gradient field, gives a scalar.

CurlInv

RotInv

Inverse curl: applied to a curl field, gives a vector.

DivInv

Inverse div: applied to a divergence field.

Notes:

1. While the operators Grad, Curl and Div can be applied to 0, 1 and 2-forms respectively, the exterior derivative operator d is usually preferred with such fields.
2. The second case permits to evaluate a discretized quantity at a certain position X, Y, Z (when expression-cst-list contains three items) or at a specific time, N time steps ago (when expression-cst-list contains a single item).

2.9 Loops and conditionals

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

loop:

For ( expression-cst : expression-cst )

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

For ( expression-cst : expression-cst : expression-cst )

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

For string In { expression-cst : expression-cst }

Iterates from the value of the first expression-cst to the value of the second expression-cst, 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-cst : expression-cst }' and the matching EndFor are executed.

For string In { expression-cst : expression-cst : expression-cst }

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

EndFor

Ends a matching For command.

If ( expression-cst )

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

EndIf

Ends a matching If command.

Loops and conditionals can be used in any of the following objects: Group, Function, Constraint (as well as in a contraint-case), FunctionSpace, Formulation (as well as in the quantity and equation defintions), Resolution (as well as resolution-term, system defintion and operations), PostProcessing (in the definition of the PostQuantities) and PostOperation (as well as in the operation list).

3. Objects

This chapter presents the formal definition of the ten GetDP objects mentioned in 1. Overview. To be concise, all the possible parameters for these objects are not given here (cf. the etc syntactic rule defined in 1.2 Syntactic rules used in this document). Please refer to 4. Types for objects, for the list of all available options.

3.1 Group: defining topological entities
3.2 Function: defining global and piecewise expressions
3.3 Constraint: specifying constraints on function spaces and formulations
3.4 FunctionSpace: building function spaces
3.5 Jacobian: defining jacobian methods
3.6 Integration: defining integration methods
3.7 Formulation: building equations
3.8 Resolution: solving systems of equations
3.9 PostProcessing: exploiting computational results
3.10 PostOperation: exporting results

3.1 Group: defining topological entities

Meshes (grids) constitute the input data of GetDP. All that is needed by GetDP as a mesh is a file containing a list of nodes (with their coordinates) and a list of geometrical elements with, for each one, a number characterizing its geometrical type (i.e., line, triangle, quadrangle, tetrahedron, hexahedron, prism, etc.), a number characterizing the physical region to which it belongs and the list of its nodes. This minimal input set should be easy to extract from most of the classical mesh file formats (see section 8.1 Input file format, for a complete description of the mesh file format read by GetDP).

Groups of geometrical entities of various types can be considered and are used in many objects. There are region groups, of which the entities are regions, and function groups, with nodes, edges, facets, volumes, groups of nodes, edges of tree, facets of tree, ... of regions.

Amongst region groups, elementary and global groups can be distinguished: elementary groups are relative to single regions (e.g., physical regions in which piecewise defined functions or constraints can be defined) while global groups are relative to sets of regions for which given treatments have to be performed (e.g., domain of integration, support of a function space, etc.).

Groups of function type contain lists of entities built on some region groups (e.g., nodes for nodal elements, edges for edge elements, edges of tree for gauge conditions, groups of nodes for floating potentials, elements on one side of a surface for cuts, etc.).

A definition of initially empty groups can be obtained thanks to a DefineGroup command, so that their identifiers exist and can be referred to in other objects, even if these groups are not explicitly defined. This procedure is similar to the DefineConstant procedure introduced for constants in 2.2 Constants.

The syntax for the definition of groups is:

Group { < DefineGroup [ group-id <{integer}> <,...> ]; > ... < group-id = group-def; > ... < group-id += group-def; > ... < affectation > ... < loop > ... }

with

group-id: string | string ~ { expression-cst } group-def: group-type [ group-list <, group-sub-type group-list > ] | group-id <{<integer>}> | #group-list group-type: Region | Global | NodesOf | EdgesOf | etc group-list: All | group-list-item | { group-list-item <,...> } group-list-item: integer | integer : integer | integer : integer : integer | group-id <{<integer>}> group-sub-type: Not | StartingOn | OnOneSideOf | etc

Notes:

1. integer as a group-list-item is the only interface with the mesh; with each element is associated a region number, being this integer, and a geometrical type (see section 8.1 Input file format). Ranges of integers can be specified in the same way as ranges of constant expressions in an expression-cst-list-item (see section 2.2 Constants). For example, i:j replaces the list of consecutive integers i, i+1, ..., j-1, j.
2. Array of groups: DefineGroup[group-id{n}] defines the empty groups group-id{i}, i=1, ..., n. Such a definition is optional, i.e., each group-id{i} can be separately defined, in any order.
3. #group-list is an abbreviation of Region[group-list].

See 4.1 Types for Group, for the complete list of options and 5.2 Group examples, for some examples.

3.2 Function: defining global and piecewise expressions

A user-defined function can be global in space or piecewise defined in region groups. A physical characteristic is an example of a piecewise defined function (e.g., magnetic permeability, electric conductivity, etc.) and can be simply a constant, for linear materials, or a function of one or several arguments for nonlinear materials. Such functions can of course depend on space coordinates or time, which can be needed to express complex constraints.

A definition of initially empty functions can be made thanks to the DefineFunction command so that their identifiers exist and can be referred to (but cannot be used) in other objects. The syntax for the definition of functions is:

Function { < DefineFunction [ function-id <,...> ]; > ... < function-id [ < group-def > ] = expression; > ... < affectation > ... < loop > ... }

with

function-id: string

Note:

1. The optional group-def in brackets must be of Region type, and indicates on which region the (piecewise) function is defined. Warning: it is incorrect to write f[reg1]=1; g[reg2]=f[]+1; since the domains of definition of f[] and g[] don't match.

See 4.2 Types for Function, for the complete list of built-in functions and 5.3 Function examples, for some examples.

3.3 Constraint: specifying constraints on function spaces and formulations

Constraints can be referred to in FunctionSpace objects to be used for boundary conditions, to impose global quantities or to initialize quantities. These constraints can be expressed with functions or be imposed by the pre-resolution of another discrete problem. Other constraints can also be defined, e.g., constraints of network type for the definition of circuit connections, to be used in Formulation objects.

The syntax for the definition of constraints is:

Constraint { { Name constraint-id; Type constraint-type; Case { { Region group-def; < Type constraint-type; > < SubRegion group-def; > < TimeFunction expression; > < RegionRef group-def; > < SubRegionRef group-def; > < Coefficient expression; > < Function expression; > < Filter expression; > constraint-val; } ... < loop > ... } | Case constraint-case-id { { Region group-def; < Type constraint-type; > constraint-case-val; } ... < loop > ... } ... } ... < affectation > ... < loop > ... }

with

constraint-id: constraint-case-id: string | string ~ { expression-cst } constraint-type: Assign | Init | Network | Link | etc constraint-val: Value expression | NameOfResolution resolution-id | etc constraint-case-val: Branch { integer, integer } | etc

Notes:

1. The constraint type constraint-type defined outside the Case fields is applied to all the cases of the constraint, unless other types are explicitly given in these cases. The default type is Assign.
2. The region type Region group-def will be the main group-list argument of the group-def to be built for the constraints of FunctionSpaces. The optional region type SubRegion group-def will be the argument of the associated group-sub-type.
3. expression in Value of constraint-val cannot be time dependent ($Time) because it is evaluated only once during the pre-processing (for efficiency reasons). Time dependences must be defined in TimeFunction expression.

See 4.3 Types for Constraint, for the complete list of options and 5.4 Constraint examples, for some examples.

3.4 FunctionSpace: building function spaces

A FunctionSpace is characterized by the type of its interpolated fields, one or several basis functions and optional constraints (in space and time). Subspaces of a function space can be defined (e.g., for the use with hierarchical elements), as well as direct associations of global quantities (e.g., floating potential, electric charge, current, voltage, magnetomotive force, etc.).

A key point is that basis functions are defined by any number of subsets of functions, being added. Each subset is characterized by associated built-in functions for evaluation, a support of definition and a set of associated supporting geometrical entities (e.g., nodes, edges, facets, volumes, groups of nodes, edges incident to a node, etc.). The freedom in defining various kinds of basis functions associated with different geometrical entities to interpolate a field permits to build made-to-measure function spaces adapted to a wide variety of field approximations (see section 5.5 FunctionSpace examples).

The syntax for the definition of function spaces is:

FunctionSpace { { Name function-space-id; Type function-space-type; BasisFunction { { Name basis-function-id; NameOfCoef coef-id; Function basis-function-type < { Quantity quantity-id; Formulation formulation-id {#integer}; Group group-def; Resolution resolution-id {} } >; Support group-def; Entity group-def; } ... } < SubSpace { { Name sub-space-id; NameOfBasisFunction basis-function-list; } ... } > < GlobalQuantity { { Name global-quantity-id; Type global-quantity-type; NameOfCoef coef-id; } ... } > < Constraint { { NameOfCoef coef-id; EntityType group-type; < EntitySubType group-sub-type; > NameOfConstraint constraint-id <{}>; } ... } > } ... < affectation > ... < loop > ... }

with

function-space-id: formulation-id: resolution-id: string | string ~ { expression-cst } basis-function-id: coef-id: sub-space-id: global-quantity-id: string function-space-type: Scalar | Vector | Form0 | Form1 | etc basis-function-type: BF_Node | BF_Edge | etc basis-function-list: basis-function-id | { basis-function-id <,...> } global-quantity-type: AliasOf | AssociatedWith

Notes:

1. When the definition region of a function type group used as an Entity of a BasisFunction is the same as that of the associated Support, it is replaced by All for more efficient treatments during the computation process (this prevents the construction and the analysis of a list of geometrical entities).
2. Piecewise defined basis functions: the same Name for several BasisFunction fields permits to define piecewise basis functions; separate NameOfCoefs must be defined for those fields.
3. Constraint: a constraint is associated with geometrical entities defined by an automatically created Group of type group-type, using the Region defined in a Constraint object as its main argument, and the optional SubRegion in the same object as a group-sub-type argument.
4. Function: a global basis function (BF_Global or BF_dGlobal) needs parameters, i.e., it is given by the quantity (quantity-id) pre-computed from multiresolutions performed on multiformulations.

See 4.4 Types for FunctionSpace, for the complete list of options and 5.5 FunctionSpace examples, for some examples.

3.5 Jacobian: defining jacobian methods

Jacobian methods can be referred to in Formulation and PostProcessing objects to be used in the computation of integral terms and for changes of coordinates. They are based on Group objects and define the geometrical transformations applied to the reference elements (i.e., lines, triangles, quadrangles, tetrahedra, prisms, hexahedra, etc.). Besides the classical lineic, surfacic and volume Jacobians, the Jacobian object allows the construction of various transformation methods (e.g., infinite transformations for unbounded domains) thanks to dedicated jacobian methods.

The syntax for the definition of Jacobian methods is:

Jacobian { { Name jacobian-id; Case { { Region group-def | All; Jacobian jacobian-type < { expression-cst-list } >; } ... } } ... }

with

jacobian-id: string jacobian-type: Vol | Sur | VolAxi | etc

Note:

1. The default case of a Jacobian object is defined by Region All and must follow all the other cases.

See 4.5 Types for Jacobian, for the complete list of options and 5.6 Jacobian examples, for some examples.

3.6 Integration: defining integration methods

Various numerical or analytical integration methods can be referred to in Formulation and PostProcessing objects to be used in the computation of integral terms, each with a set of particular options (number of integration points for quadrature methods--which can be linked to an error criterion for adaptative methods, definition of transformations for singular integrations, etc.). Moreover, a choice can be made between several integration methods according to a criterion (e.g., on the proximity between the source and computation points in integral formulations).

The syntax for the definition of integration methods is:

Integration { { Name integration-id; < Criterion expression; > Case { < { Type integration-type; Case { { GeoElement element-type; NumberOfPoints expression-cst } ... } } ... > < { Type Analytic; } ... > } } ... }

with

integration-id: string integration-type: Gauss | etc element-type: Line | Triangle | Tetrahedron etc

See 4.6 Types for Integration, for the complete list of options and 5.7 Integration examples, for some examples.

3.7 Formulation: building equations

The Formulation tool permits to deal with volume, surface and line integrals with many kinds of densities to integrate, written in a form that is similar to their symbolic expressions (it uses the same expression syntax as elsewhere in GetDP), which therefore permits to directly take into account various kinds of elementary matrices (e.g., with scalar or cross products, anisotropies, nonlinearities, time derivatives, various test functions, etc.). In case nonlinear physical characteristics are considered, arguments are used for associated functions. In that way, many formulations can be directly written in the data file, as they are written symbolically. Fields involved in each formulation are declared as belonging to beforehand defined function spaces. The uncoupling between formulations and function spaces allows to maintain a generality in both their definitions.

A Formulation is characterized by its type, the involved quantities (of local, global or integral type) and a list of equation terms. Global equations can also be considered, e.g., for the coupling with network relations.

The syntax for the definition of formulations is:

Formulation { { Name formulation-id; Type formulation-type; Quantity { { Name quantity-id; Type quantity-type; NameOfSpace function-space-id <{}> < [ sub-space-id | global-quantity-id ] >; < Symmetry expression-cst; > < [ expression ]; In group-def; Jacobian jacobian-id; Integration integration-id; > < IndexOfSystem integer; > } ... } Equation { < local-term-type { < term-op-type > [ expression, expression ]; In group-def; Jacobian jacobian-id; Integration integration-id; } > ... < GlobalTerm { < term-op-type > [ expression, expression ]; In group-def; } > ... < GlobalEquation { Type Network; NameOfConstraint constraint-id; { Node expression; Loop expression; Equation expression; In group-def; } ... } > ... < affectation > ... < loop > ... } } ... < affectation > ... < loop > ... }

with

formulation-id: string | string ~ { expression-cst } formulation-type: FemEquation | etc local-term-type: Galerkin | deRham quantity-type: Local | Global | Integral term-op-type: Dt | DtDt | JacNL | etc

Note:

1. IndexOfSystem permits to resolve ambiguous cases when several quantities belong to the same function space, but to different systems of equations. The integer parameter then specifies the index in the list of an OriginSystem command (see section 3.8 Resolution: solving systems of equations).
2. A GlobalTerm defines a term to be assembled in an equation associated with a global quantity. This equation is a finite element equation if that global quantity is linked with local quantities.
3. A GlobalEquation defines a global equation to be assembled in the matrix