GetDP 1.2: Expressions

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

# 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 |  |

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

## 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 |  |

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

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

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

## 2.3 Operators

> 2.3.1 Operator types |  |
> 2.3.2 Evaluation order |  |

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

### 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:

`?`

operator-ternary-right:

`:`
  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.

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

### 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), !`
`/\`
`*, /, %`
`+, -`
`<, >, <=, >=`
`!=, ==`
`&&, ||`
`?:`

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

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

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

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

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

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

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

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

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

## 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 `D`egrees `o`f `f`reedom), 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).

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

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

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

Back to geuz.org/getdp