GetDP 1.2: Objects

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

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

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

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

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

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

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

## 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 `FunctionSpace`s. 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.

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

## 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 `NameOfCoef`s 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.

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

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

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

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

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

## 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 of the system.

See 4.7 Types for `Formulation`, for the complete list of options and 5.8 `Formulation` examples, for some examples.

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

## 3.8 `Resolution`: solving systems of equations

The operations available in a `Resolution` include: the generation of a linear system, its solving with various kinds of linear solvers, the saving of the solution or its transfer to another system, the definition of various time stepping methods, the construction of iterative loops for nonlinear problems (Newton-Raphson and fixed point methods), etc. Multi-harmonic resolutions, coupled problems (e.g., magneto-thermal) or linked problems (e.g., pre-computations of source fields) are thus easily defined in GetDP.

The `Resolution` object is characterized by a list of systems to build and their associated formulations, using time or frequency domain, and a list of elementary operations:

    Resolution {
      { Name resolution-id;
        System {
          { Name system-id; NameOfFormulation formulation-list;
            < Type system-type; >
            < Frequency expression-cst-list-item |
              Frequency { expression-cst-list }; >
            < DestinationSystem system-id; >
            < OriginSystem system-id; | OriginSystem { system-id <,...> }; >
            < NameOfMesh expression-char > < Solver expression-char >
            < loop > } ...
          < loop > ...
        }
        Operation {
          < resolution-op; > ...
          < loop > ...
        }
      } ...
      < affectation > ...
      < loop > ...
    }

with

    resolution-id:
    system-id:
      string |
      string ~ { expression-cst }

    formulation-list:
      formulation-id <{}> | { formulation-id <{}> <,...> }

    system-type:
      Real | Complex

    resolution-op:
      Generate[system-id] | Solve[system-id] | etc

Notes:

1. The default type for a system of equations is `Real`. A frequency domain analysis is defined through the definition of one or several frequencies (`Frequency expression-cst-list-item | Frequency { expression-cst-list }`). Complex systems of equations with no predefined list of frequencies (e.g., in modal analyses) can be explicitely defined with `Type Complex`.
2. `NameOfMesh` permits to explicitely specify the mesh to be used for the construction of the system of equations.
3. `Solver` permits to explicitely specify the name of the solver parameter file to use for the solving of the system of equations. This is ony valid if GetDP was compiled against the default solver library (it is the case if you downloaded a pre-compiled copy of GetDP from the internet).
4. `DestinationSystem` permits to specify the destination system of a `TransferSolution` operation (see section 4.8 Types for `Resolution`).
5. `OriginSystem` permits to specify the systems from which ambiguous quantity definitions can be solved (see section 3.7 `Formulation`: building equations).

See 4.8 Types for `Resolution`, for the complete list of options and 5.9 `Resolution` examples, for some examples.

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

## 3.9 `PostProcessing`: exploiting computational results

The `PostProcessing` object is based on the quantities defined in a `Formulation` and permits the construction (thanks to the expression syntax) of any useful piecewise defined quantity of interest:

    PostProcessing {
      { Name post-processing-id;
        NameOfFormulation formulation-id <{}>; < NameOfSystem system-id; >
        Quantity {
          { Name post-quantity-id; Value { post-value ... } } ...
          < loop > ...
        }
      } ...
      < affectation > ...
      < loop > ...
    }

with

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

    post-value:
      Local { local-value } | Integral { integral-value }

    local-value:
      [ expression ]; In group-def; Jacobian jacobian-id;

    integral-value:
      [ expression ]; In group-def;
      Integration integration-id; Jacobian jacobian-id;

Notes:

1. The quantity defined with integral-value is piecewise defined over the elements of the mesh of group-def, and takes, in each element, the value of the integration of expression over this element. The global integral of expression over a whole region (being either group-def or a subset of group-def) has to be defined in the `PostOperation` with the `post-quantity-id[group-def]` command (see section 3.10 `PostOperation`: exporting results).
2. If `NameOfSystem system-id` is not given, the system is automatically selected as the one to which the first quantity listed in the `Quantity` field of formulation-id is associated.

See 4.9 Types for `PostProcessing`, for the complete list of options and 5.10 `PostProcessing` examples, for some examples.

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

## 3.10 `PostOperation`: exporting results

The `PostOperation` is the bridge between results obtained with GetDP and the external world. It defines several elementary operations on `PostProcessing` quantities (e.g., plot on a region, section on a user-defined plane, etc.), and outputs the results in several file formats.

    PostOperation {
      { Name post-operation-id; NameOfPostProcessing post-processing-id;
        < Format post-operation-fmt; > < Append expression-char; >
        Operation {
          < post-operation-op; > ...
        }
      } ...
      < affectation > ...
      < loop > ...
    } |
    PostOperation post-operation-id UsingPost post-processing-id {
      < post-operation-op; > ...
    } ...

with

    post-operation-id:
      string |
      string ~ { expression-cst }

    post-operation-op:
      Print[ post-quantity-term, print-support <,print-option> ... ] |
      Print[ "string", expression <,print-option> ... ] |
      Print[ "string", Str[ expression-char ] <,print-option> ... ] |
      Echo[ "string" <,print-option> ... ] |
      PrintGroup[ group-id, print-support <,print-option> ... ] |
      < loop > ...
      etc

    post-quantity-term:
      post-quantity-id <[group-def]> |
      post-quantity-id post-quantity-op post-quantity-id[group-def] |
      post-quantity-id[group-def] post-quantity-op post-quantity-id

    post-quantity-op:
      + | - | * | /

    print-support:
      OnElementsOf group-def | OnRegion group-def | OnGlobal | etc

    print-option:
      File expression-char | Format post-operation-fmt | etc

    post-operation-fmt:
      Table | TimeTable | etc

Notes:

1. Both `PostOperation` syntaxes are equivalent. The first one conforms to the overall interface, but the second one is more concise.
2. The format post-operation-fmt defined outside the `Operation` field is applied to all the post-processing operations, unless other formats are explicitly given in these operations with the `Format` option (see section 4.10 Types for `PostOperation`). The default format is `Gmsh`.
3. The optional argument `[group-def]` of the post-quantity-id can only be used when this quantity has been defined as an integral-value (see section 3.9 `PostProcessing`: exploiting computational results). In this case, the sum of all elementary integrals is performed over the region group-def.
4. The post-quantity-op allows the simple combination of space-dependent quantities (post-quantity-id) with global integral quantities (`post-quantity-id[group-def]`).

See 4.10 Types for `PostOperation`, for the complete list of options and 5.11 `PostOperation` examples, for some examples.

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

Back to geuz.org/getdp