\input texinfo.tex @c -*-texinfo-*-
@c GetDP - Copyright (C) 1997-2021 P. Dular and C. Geuzaine, University of Liege
@c
@c See the LICENSE.txt file for license information. Please report all
@c issues on https://gitlab.onelab.info/getdp/getdp/issues.
@c
@c =========================================================================
@c
@c This is the GetDP documentation texinfo source file
@c
@c Things to do -> "Ctrl+s todo:"
@c
@c Indexing: @cindex = concept index, e.g. "Numerical tools, overview"
@c           @vindex = (metasyntactic) variable index, e.g.  "constraint-type"
@c          /@tindex = type index (=frozen syntax ossature), e.g. "DefineGroup"
@c          \@findex = function index (=all types in the objects), e.g. "Curl"
@c
@c Before release, run C-u C-c C-u C-a in GNU Emacs
@c This updates all node pointers and menus
@c
@c =========================================================================
@c %**start of header
@setfilename getdp.info
@include version.texi
@set COPYRIGHT @copyright{} 1997-2021 P. Dular and C. Geuzaine, University of Liege
@settitle GetDP @value{GETDP-VERSION}
@footnotestyle separate
@setchapternewpage odd
@paragraphindent 0
@finalout
@c %**end of header

@c merge function index into type index
@syncodeindex fn tp

@c =========================================================================
@c Info directives
@c =========================================================================

@ifinfo
@dircategory Math
@direntry
* GetDP: (getdp). General finite element solver
@end direntry
@noindent
This is the @cite{GetDP Reference Manual} for GetDP
@value{GETDP-VERSION} (@today{}).
@noindent
Copyright @value{COPYRIGHT}.
@end ifinfo

@c =========================================================================
@c Title page
@c =========================================================================

@shorttitlepage GetDP

@titlepage

@title GetDP Reference Manual

@subtitle The documentation for GetDP @value{GETDP-VERSION}
@subtitle A General environment for the treatment of Discrete Problems
@subtitle
@subtitle @today{}

@author Patrick Dular
@author Christophe Geuzaine

@page
@vskip 0pt plus 1filll
Copyright @value{COPYRIGHT}
@sp 1
University of Li@`ege @*
Department of Electrical Engineering @*
Institut d'@'Electricit@'e Montefiore @*
Sart Tilman Campus, Building B28 @*
B-4000 Li@`ege @*
BELGIUM
@sp 1
Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on
all copies.

@end titlepage

@c =========================================================================
@c Table of contents
@c =========================================================================

@ifnothtml
@summarycontents
@end ifnothtml
@contents

@c =========================================================================
@c Top node (for all output, except TeX)
@c =========================================================================

@ifnottex
@node Top, Obtaining GetDP, (dir), (dir)
@top GetDP

Patrick Dular and Christophe Geuzaine

GetDP is a general finite element solver that uses mixed finite elements
to discretize de Rham-type complexes in one, two and three
dimensions. This is the @cite{GetDP Reference Manual} for GetDP
@value{GETDP-VERSION} (@today{}).
@end ifnottex

@c =========================================================================
@c Master menu
@c =========================================================================

@menu
* Obtaining GetDP::
* Copying conditions::          Terms and conditions of use.
* Overview::                    What is GetDP?
* How to Read this Manual::     Which parts of this manual should you read?
* Running GetDP::               How to run GetDP on your machine.
* Expressions::                 Definition of basic expressions in GetDP.
* Objects::                     Definition of the 10 GetDP objects.
* Types for objects::           Definition of all available types for the 10 objects.
* Short examples::              Simple object examples.
* Complete examples::           Some simple complete examples.
* File formats::                Input and output file formats.
* Gmsh examples::               Sample Gmsh input files.
* Compiling the source code::   Information on how to comile GetDP from source
* Frequently asked questions::  The GetDP FAQ
* Tips and tricks::             Some tips to make your life easier with GetDP.
* Version history::             Changelog
* Copyright and credits::       Copyright information and list of contributors
* 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.

@ifnothtml
@detailmenu
 --- The Detailed Node Listing ---

Overview

* Numerical tools as objects::
* Which problems can GetDP actually solve?::
* Bug reports::

How to read this manual

* Syntactic rules::

Expressions

* Comments::
* Includes::
* Expression definition::
* Constants::
* Operators::
* Functions::
* Current values::
* Arguments::
* Run-time variables and registers::
* Fields::
* Macros loops and conditionals::

Expressions definition

* Operators::
* Constants::
* Functions::
* Current values::
* Fields::

Operators

* Operator types::
* Evaluation order::

Objects

* Group::
* Function::
* Constraint::
* FunctionSpace::
* Jacobian::
* Integration::
* Formulation::
* Resolution::
* PostProcessing::
* PostOperation::

Types for objects

* Types for Group::
* Types for Function::
* Types for Constraint::
* Types for FunctionSpace::
* Types for Jacobian::
* Types for Integration::
* Types for Formulation::
* Types for Resolution::
* Types for PostProcessing::
* Types for PostOperation::

Types for @code{Function}

* Math functions::
* Extended math functions::
* Green functions::
* Type manipulation functions::
* Coordinate functions::
* Miscellaneous functions::

Short examples

* Constant expression examples::
* Group examples::
* Function examples::
* Constraint examples::
* FunctionSpace examples::
* Jacobian examples::
* Integration examples::
* Formulation examples::
* Resolution examples::
* PostProcessing examples::
* PostOperation examples::

@code{FunctionSpace} examples

* Conform space::
* High order space::
* Global values::
* Curl-conform space::
* Gauge condition::
* Coupled spaces::
* Multiply connected domains::

@code{Formulation} examples

* Electrostatics::
* Electrostatics 2::
* Magnetostatics::
* Magnetodynamics::
* Other formulations::

@code{Resolution} examples

* Static resolution::
* Frequency domain resolution::
* Time domain resolution::
* Nonlinear resolution::
* Coupled formulations::

Complete examples

* Electrostatic problem::
* Magnetostatic problem::
* Magnetodynamic problem::

File formats

* Input file format::
* Output file format::

Output file format

* File pre::
* File res::

Frequently asked questions

* The basics::
* Installation::
* Usage::

@end detailmenu
@end ifnothtml
@end menu

@c =========================================================================
@c Obtaining GetDP
@c =========================================================================

@node Obtaining GetDP, Copying conditions, Top, Top
@unnumbered Obtaining GetDP

@cindex Web site
@cindex Internet address
@cindex Download

The source code and various pre-compiled versions of GetDP (for Windows,
Linux and MacOS) can be downloaded from @uref{http://getdp.info}.

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
@url{http://getdp.info}.

@c =========================================================================
@c Copying Conditions
@c =========================================================================

@node Copying conditions, Overview, Obtaining GetDP, Top
@unnumbered Copying conditions

@cindex Copyright
@cindex License

@cindex Web site
@cindex Internet address
@cindex Download

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 (@pxref{License}). Further
information about this license is available from the GNU Project webpage
@uref{http://www.gnu.org/copyleft/gpl-faq.html}.  Detailed copyright
information can be found in @ref{Copyright and credits}.

If you want to integrate parts of GetDP into a closed-source software, or
want to sell a modified closed-source version of GetDP, you will need to
obtain a different license. Please @uref{http://geuz.org, contact us
directly} for more information.

@c =========================================================================
@c Overview
@c =========================================================================

@node Overview, How to Read this Manual, Copying conditions, Top
@chapter Overview

@cindex Introduction
@cindex Overview

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.

@c -------------------------------------------------------------------------
@c Numerical Tools as Objects
@c -------------------------------------------------------------------------

@menu
* Numerical tools as objects::
* Which problems can GetDP actually solve?::
* Bug reports::
@end menu

@node Numerical tools as objects, Which problems can GetDP actually solve?, Overview, Overview
@section Numerical tools as objects

@cindex Objects, dependences
@cindex Dependences, objects
@cindex Linking, objects
@cindex Tools, order of definition
@cindex Philosophy, general
@cindex Processing cycle

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.

@image{objects-wrap,13.5cm,}

@sp 1
@example
Group           @var{---}
Function        Group
Constraint      Group, Function, (Resolution)
FunctionSpace   Group, Constraint, (Formulation), (Resolution)
Jacobian        Group
Integration     @var{---}
Formulation     Group, Function, (Constraint), FunctionSpace,
                Jacobian, Integration
Resolution      Function, Formulation
PostProcessing  Group, Function, Jacobian, Integration,
                Formulation, Resolution
PostOperation   Group, PostProcessing
@end example
@sp 1

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 (@code{Formulation}) and function spaces
(@code{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., @code{Group}, @code{Function} and
@code{Constraint}) followed by those defining a resolution method, such
as unknowns, equations and related objects (i.e., @code{Jacobian},
@code{Integration}, @code{FunctionSpace}, @code{Formulation},
@code{Resolution} and @code{PostProcessing}).  The processing cycle ends
with the presentation of the results (i.e., lists of numbers in various
formats), defined in @code{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.

@c -------------------------------------------------------------------------
@c Which Problems can GetDP actually solve?
@c -------------------------------------------------------------------------

@node Which problems can GetDP actually solve?, Bug reports, Numerical tools as objects, Overview
@section Which problems can GetDP actually solve?

@cindex Scope of GetDP
@cindex Future developments
@cindex Developments, future
@cindex Physical problems
@cindex Method of Moments
@cindex Finite Element Method
@cindex Integral Equation Method
@cindex Boundary Element Method
@cindex Finite Difference Method
@cindex Finite Volume Method
@cindex Electromagnetism
@cindex Mechanics
@cindex Thermics

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:

@table @asis
@item Numerical methods
finite element method@*
boundary element method (experimental, undocumented)@*
volume integral methods (experimental, undocumented)
@item Geometrical models
one-dimensional models (1D)@*
two-dimensional models (2D), plane and axisymmetric@*
three-dimensional models (3D)
@item Time states
static states@*
sinusoidal and harmonic states@*
transient states@*
eigenvalue problems
@end table

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 @emph{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!

@c -------------------------------------------------------------------------
@c Bug reports
@c -------------------------------------------------------------------------

@node Bug reports,  , Which problems can GetDP actually solve?, Overview
@section Bug reports

@cindex Bugs, reporting
@cindex Reporting bugs

Please file issues on
@url{https://gitlab.onelab.info/getdp/getdp/issues}. Provide as precise
a description of the problem as you can, including sample input files
that produce the bug.  Don't forget to mention both the version of GetDP
and the version of your operation system (@pxref{Running GetDP} to see
how to get this information).

See @ref{Frequently asked questions}, and the
@url{https://gitlab.onelab.info/getdp/getdp/issues,bug tracking system}
to see which problems we already know about.

@c =========================================================================
@c How to Read this Manual
@c =========================================================================

@node How to Read this Manual, Running GetDP, Overview, Top
@chapter How to read this manual

@cindex Reading, guidelines

After reading @ref{Overview}, which depicts the general philosophy of
GetDP, you might want to skip @ref{Expressions}, @ref{Objects} and
@ref{Types for objects} and directly run the demo files bundled in the
distribution on your computer (@pxref{Running GetDP}). You should then
open these examples with a text editor and compare their structure with
the examples given in @ref{Short examples} and @ref{Complete
examples}. For each new syntax element that you fall onto, you can then
go back to @ref{Expressions}, @ref{Objects}, and @ref{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 (@pxref{Concept index}) and for all the syntax
elements (@pxref{Syntax index}) are available at the end of this
manual.

@c -------------------------------------------------------------------------
@c Syntactic Rules Used in this Document
@c -------------------------------------------------------------------------

@menu
* Syntactic rules::
@end menu

@node Syntactic rules,  , How to Read this Manual, How to Read this Manual
@section Syntactic rules used in this document

@cindex Syntax, rules
@cindex Rules, syntactic
@cindex Document syntax

@vindex @dots{}
@vindex <, >
@vindex |
@vindex :
@vindex @var{etc}

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 @ref{Metasyntactic variable index}, for an index of all
metasyntactic variables.

@enumerate
@item
Keywords and literal symbols are printed like @code{this}.
@item
Metasyntactic variables (i.e., text bits that are not part of the syntax,
but stand for other text bits) are printed like @var{this}.
@item
A colon (@code{:}) after a metasyntactic variable separates the variable
from its definition.
@item
Optional rules are enclosed in @code{<} @code{>} pairs.
@item
Multiple choices are separated by @code{|}.
@item
Three dots (@dots{}) indicate a possible repetition of the preceding rule.
@item
For conciseness, the notation @code{@var{rule} <, @var{rule} > @dots{}}
is replaced by @code{@var{rule} <,@dots{}>}.
@item
The @var{etc} symbol replaces nonlisted rules.
@end enumerate

@c =========================================================================
@c Running GetDP
@c =========================================================================

@node Running GetDP, Expressions, How to Read this Manual, Top
@chapter Running GetDP

@cindex Operating system
@cindex Platforms
@cindex Command line options
@cindex Options, command line
@cindex Running GetDP

GetDP has no graphical interface@footnote{If you are looking for a
graphical front-end to GetDP, you may consider using Gmsh (available at
@url{http://gmsh.info}). Gmsh permits to construct geometries, generate
meshes, launch computations and visualize results directly from within a
user-friendly graphical interface. The file formats used by Gmsh for
mesh generation and post-processing are the default file formats
accepted by GetDP (see @ref{Input file format}, and @ref{Types for
PostOperation}).}. It is a command-line driven program that reads a
problem definition file once at the beginning of the processing. This
problem definition file is a regular ASCII text file (@pxref{Numerical
tools as objects}), hence created with whatever text editor you like.

If you just type the program name at your shell prompt (without any
argument), you will get a short help on how to run GetDP. All GetDP
calls look like

@example
getdp @var{filename} @var{options}
@end example

@noindent
where @var{filename} is the ASCII file containing the problem definition,
i.e., the structures this user's guide has taught you to create. This file
can include other files (@pxref{Includes}), so that only one problem
definition file should always be given on the command line. The input files
containing the problem definition structure are usually given the
@file{.pro} extension (if so, there is no need to specify the extension on
the command line). The name of this file (without the extension) is used as
a basis for the creation of intermediate files during the pre-processing and
the processing stages.

The @var{options} are a combination of the following commands (in any
order):

@ftable @code
@item -pre
@var{resolution-id}

Performs the pre-processing associated with the resolution
@var{resolution-id}. In the pre-processing stage, GetDP creates the
geometric database (from the mesh file), identifies the degrees of
freedom (the unknowns) of the problem and sets up the constraints on
these degrees of freedom. The pre-processing creates a file with a
@file{.pre} extension. If @var{resolution-id} is omitted, the list of
available choices is displayed.

@item -cal

Performs the processing. This requires that a pre-processing has been
performed previously, or that a @code{-pre} option is given on the same
command line. The performed resolution is the one given as an argument to
the @code{-pre} option. In the processing stage, GetDP executes all the
commands given in the @code{Operation} field of the selected
@code{Resolution} object (such as matrix assemblies, system resolutions,
@dots{}).

@item -pos
@var{post-operation-id} @dots{}

Performs the operations in the @code{PostOperation}(s) selected by the
@var{post-operation-id}(s). This requires that a processing has been
performed previously, or that a @code{-cal} option is given on the same
command line. If @var{post-operation-id} is omitted, the list of available
choices is displayed.

@item -msh
@var{filename}

Reads the mesh (in @code{.msh} format) from @var{filename} (@pxref{File
formats}) rather than from the default problem file name (with the
@file{.msh} extension appended).

@item -msh_scaling
@var{value}

Multiplies the coordinates of all the nodes in the mesh by @var{value}.

@item -gmshread
@var{filename} @dots{}

Read gmsh data files (same as GmshRead in @code{Resolution}
operations). Allows to use such datasets outside resolutions (e.g. in
pre-processing).

@item -split

Saves processing results in separate files (one for each timestep).

@item -res
@var{filename} @dots{}

Loads processing results from file(s).

@item -name
@var{string}

Uses @var{string} as the default generic file name for input or output
of mesh, pre-processing and processing files.

@item -restart

Restarts processing of a time stepping resolution interrupted before being
complete.

@item -solve
@var{resolution-id}

Same as @code{-pre @var{resolution-id} -cal}.

@item -solver
@var{filename}

Specifies a solver option file (whose format varies depending on the
linear algebra toolkit used).

@item -slepc

Uses SLEPc instead of Arpack as eigensolver.

@item -adapt
@var{file}

Reads adaptation constraints from file.

@item -order
@var{real}

Specifies the maximum interpolation order.

@item -cache

Caches network computations to disk.

@item -bin

Selects binary format for output files.

@item -v2

Creates mesh-based Gmsh output files when possible.

@item -check

Lets you check the problem structure interactively.

@item -v
@itemx -verbose
@var{integer}

Sets the verbosity level. A value of 0 means that no information will be
displayed during the processing.

@item -cpu

Reports CPU times for all operations.

@item -p
@itemx -progress
@var{integer}

Sets the progress update rate. This controls the refreshment rate of the
counter indicating the progress of the current computation (in %).

@item -onelab
@var{name} <@var{address}>

Communicates with OneLab (file or server address)

@item -setnumber
@var{name} @var{value}

Sets constant number @var{name} to @var{value}

@item -setstring
@var{name} @var{value}

Sets constant string  @var{name} to @var{value}

@item -info

Displays the version information.

@item -version

Displays the version number.

@item -help

Displays a message listing basic usage and available options.

@end ftable

@c =========================================================================
@c Expressions
@c =========================================================================

@node Expressions, Objects, Running GetDP, Top
@chapter 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 @ref{Running GetDP}, and run the demo problems bundled in
the distribution on your computer. You should then open the @file{.pro}
files in a text editor and compare their structure with the examples
given in @ref{Short examples} and @ref{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.

@menu
* Comments::
* Includes::
* Expression definition::
* Constants::
* Operators::
* Functions::
* Current values::
* Arguments::
* Run-time variables and registers::
* Fields::
* Macros loops and conditionals::
@end menu

@c -------------------------------------------------------------------------
@c Comments
@c -------------------------------------------------------------------------

@node Comments, Includes, Expressions, Expressions
@section Comments

@cindex Comments
@cindex File, comment

@tindex /*, */
@tindex //

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

@enumerate
@item
the text region comprised between @code{/*} and @code{*/} pairs is ignored;
@item
the rest of a line after a double slash @code{//} is ignored.
@end enumerate

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

@c -------------------------------------------------------------------------
@c Includes
@c -------------------------------------------------------------------------

@node Includes, Expression definition, Comments, Expressions
@section Includes

@cindex Includes
@cindex File, include

@tindex Include
@tindex #include

An input data file can be included in another input data file by placing
one of the following commands (@var{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.

@example
@code{Include @var{expression-char}}
@code{#include @var{expression-char}}
@end example

See @ref{Constants}, for the definition of the character expression
@var{expression-char}.

@c -------------------------------------------------------------------------
@c Definition
@c -------------------------------------------------------------------------

@node Expression definition, Constants, Includes, Expressions
@section Expressions definition

@cindex Expression, definition

@vindex @var{expression}
@vindex @var{expression-list}

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 @var{expression}
(remember the definition of the syntactic rules in @ref{Syntactic rules}):

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

@noindent The following sections introduce the quantities that can appear in
expressions, i.e., constant terminals (@var{integer}, @var{real}) and
constant expression identifiers (@var{constant-id},
@var{expression-cst-list}), discretized fields (@var{quantity}), arguments
(@var{argument}), current values (@var{current-value}), register values
(@var{register-set}, @var{register-get}), operators
(@var{operator-unary}, @var{operator-binary}, @var{operator-ternary-left},
@var{operator-ternary-right}) and built-in or user-defined functions
(@var{built-in-function-id}, @var{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:

@example
@var{expression-list}:
  @var{expression} <,@dots{}>
@end example

@menu
* Operators::
* Constants::
* Functions::
* Current values::
* Fields::
@end menu

@c -------------------------------------------------------------------------
@c Constants
@c -------------------------------------------------------------------------

@node Constants, Operators, Expression definition, Expressions
@section Constants

@cindex Constant, definition
@cindex Constant, evaluation
@cindex Evaluation mechanism
@cindex Integer numbers
@cindex Real numbers
@cindex Floating point numbers
@cindex Numbers, real
@cindex Numbers, integer
@cindex String

@tindex DefineConstant
@tindex List
@tindex ListAlt
@tindex Pi
@tindex 0D
@tindex 1D
@tindex 2D
@tindex 3D
@tindex =
@tindex ~

@vindex @var{integer}
@vindex @var{real}
@vindex @var{string}
@vindex @var{expression-cst}
@vindex @var{expression-cst-list}
@vindex @var{expression-cst-list-item}
@vindex @var{constant-id}
@vindex @var{constant-def}
@vindex @var{string-id}
@vindex @var{expression-char}
@vindex @var{affectation}

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

@example
@var{expression-cst}:
  ( @var{expression-cst} ) |
  @var{integer} |
  @var{real} |
  @var{constant-id} |
  @var{operator-unary} @var{expression-cst} |
  @var{expression-cst} @var{operator-binary} @var{expression-cst} |
  @var{expression-cst} @var{operator-ternary-left} @var{expression-cst} @var{operator-ternary-right}
      @var{expression-cst} |
  @var{math-function-id} [ < @var{expression-cst-list} > ] |
  #@var{constant-id}() |
  @var{constant-id}(@var{expression-cst}) |
  StrFind[ @var{expression-char}, @var{expression-char} ] |
  StrCmp[ @var{expression-char}, @var{expression-char} ] |
  StrLen[ @var{expression-char} ] |
  StringToName[ @var{expression-char} ] | S2N[ @var{expression-char} ] |
  Exists[ @var{string} ] | FileExists[ @var{string} ] | GroupExists[ @var{string} ] |
  GetForced[ @var{string} ] | NbrRegions [ @var{string} ] |
  GetNumber[ @var{expression-char} <, @var{expression-cst}> ]
@end example

@code{StrFind} searches the first @var{expression-char} for any
occurrence of the second @var{expression-char}.  @code{StrCmp} compares
the two strings (returns an integer greater than, equal to, or less than
0, according as the first string is greater than, equal to, or less than
the second string).  @code{StrLen} returns the length of the
string. @code{StringToName} creates a name from the provided
string. @code{Exists} checks for the existence of a constant or a
function. @code{FileExists} checks for the existence of a
file. @code{GroupExists} checks for the existence of a
group. @code{GetForced} gets the value of a constant (zero if does not
exist).  @code{NbrRegions} counts the numbers of elementary regions in a
group. @code{GetNumber} allows to get the value of a ONELAB number
variable (the optional second argument specifies the default value
returned if the variable does not exist).

List of constant expressions are defined as:

@example
@var{expression-cst-list}:
  @var{expression-cst-list-item} <,@dots{}>
@end example

@noindent with

@example
@var{expression-cst-list-item}:
  @var{expression-cst} |
  @var{expression-cst} : @var{expression-cst} |
  @var{expression-cst} : @var{expression-cst} : @var{expression-cst} |
  @var{constant-id} () |
  @var{constant-id} ( @{ @var{expression-cst-list} @} ) |
  List[ @var{constant-id} ] |
  List[ @var{expression-cst-list-item} ] |
  List[ @{ @var{expression-cst-list} @} ] |
  ListAlt[ @var{constant-id}, @var{constant-id} ] |
  ListAlt[ @var{expression-cst-list-item}, @var{expression-cst-list-item} ] |
  LinSpace[ @var{expression-cst}, @var{expression-cst}, @var{expression-cst} ] |
  LogSpace[ @var{expression-cst}, @var{expression-cst}, @var{expression-cst} ] |
  - @var{expression-cst-list-item} |
  @var{expression-cst} * @var{expression-cst-list-item} |
  @var{expression-cst-list-item} * @var{expression-cst} |
  @var{expression-cst} / @var{expression-cst-list-item} |
  @var{expression-cst-list-item} / @var{expression-cst} |
  @var{expression-cst-list-item} ^ @var{expression-cst} |
  @var{expression-cst-list-item} + @var{expression-cst-list-item} |
  @var{expression-cst-list-item} - @var{expression-cst-list-item} |
  @var{expression-cst-list-item} * @var{expression-cst-list-item} |
  @var{expression-cst-list-item} / @var{expression-cst-list-item} |
  ListFromFile [ @var{expression-char} ] |
  ListFromServer [ @var{expression-char} ]
@end example

The second case in this last definition permits to create a list
containing the range of numbers comprised between the two
@var{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 @var{expression-cst}, but with a positive or negative
incrementation step equal to the third @var{expression-cst}. The fourth
and fifth cases permit to reference constant identifiers
(@var{constant-id}s) 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 @code{ListAlt}
must be @var{constant-id}s 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 (@pxref{Functions}). The next two cases
permit to create linear and logarithmic lists of numbers,
respectively. The remaining cases permit to apply arithmetic operators
item-wise in lists.  @code{ListFromFile} reads a list of numbers from a
file.  @code{ListFromServer} attemps to get a list of numbers from the
ONELAB variable @var{expression-char}.

Contrary to a general @var{expression} which is evaluated at runtime (thanks
to an internal stack mechanism), an @var{expression-cst} is completely
evaluated during the syntactic analysis of the problem (when GetDP reads the
@file{.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:

@example
@var{affectation}:
  DefineConstant [ @var{constant-id} < = @var{expression-cst} > <,@dots{}> ]; |
  DefineConstant [ @var{constant-id} = @{ @var{expression-cst} , @var{onelab-options} @} <,@dots{}> ]; |
  DefineConstant [ @var{string-id} < = @var{string-def} >  <,@dots{}> ]; |
  DefineConstant [ @var{string-id} = @{ @var{string-def} , @var{onelab-options} @} <,@dots{}> ]; |
  @var{constant-id} <()> = @var{constant-def}; |
  @var{constant-id} = DefineNumber[ @var{constant-def}, @var{onelab-options} ];
  @var{string-id} <()> = @var{string-def}; |
  @var{string-id} = DefineString[ @var{string-def}, @var{onelab-options} ]; |
  Printf [ "@var{string}" ] < > | >> @var{string-def} >; |
  Printf [ "@var{string}", @var{expression-cst-list} ] < > | >> @var{string-def} >; |
  Read [ @var{constant-id} ] ; |
  Read [ @var{constant-id} , @var{expression-cst} ]; |
  UndefineConstant | Delete [ @var{constant-id} ] ;
  UndefineFunction [ @var{constant-id} ] ;
  SetNumber[ @var{string} , @var{expression-cst} ];
  SetString[ @var{string} , @var{string-def} ];
@end example

@noindent with

@example
@var{constant-id}:
  @var{string} |
  @var{string} ( @var{expression-cst-list} ) |
  @var{string} ~ @{ @var{expression-cst} @} <,@dots{}>

@var{constant-def}:
  @var{expression-cst-list-item} |
  @{ @var{expression-cst-list} @}

@var{string-id}:
  @var{string} |
  @var{string} ~ @{ @var{expression-cst} @} <,@dots{}>

@var{string-def}:
  "@var{string}" |
  StrCat[ @var{expression-char} <,@dots{}> ] |
  Str[ @var{expression-char} <,@dots{}> ]
@end example

@noindent Notes:
@enumerate
@item
Five constants are predefined in GetDP: @code{Pi} (3.1415926535897932),
@code{0D} (0), @code{1D} (1), @code{2D} (2) and @code{3D} (3).
@item
When @code{~@{@var{expression-cst}@}} is appended to a string @var{string},
the result is a new string formed by the concatenation of @var{string},
@code{_} (an underscore) and the value of the @var{expression-cst}. This is
most useful in loops (@pxref{Macros loops and conditionals}), where it permits to
define unique strings automatically. For example,
@example
For i In @{1:3@}
  x~@{i@} = i;
EndFor
@end example
is the same as
@example
x_1 = 1;
x_2 = 2;
x_3 = 3;
@end example
@item
The assignment in @code{DefineConstant} (zero if no @var{expression-cst} is
given) is performed only if @var{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).

When @var{onelab-options} are provided, the parameter is exchanged with
the ONELAB server. See
@uref{https://gitlab.onelab.info/doc/tutorials/wikis/ONELAB-syntax-for-Gmsh-and-GetDP}
for more information.
@item
@code{DefineNumber} and @code{DefineString} allow to define a ONELAB
parameter. In this case the affectation always takes
place. @code{SetNumber} and @code{SetString} allow the direct setting of
ONELAB parameters without defining local variables.
@end enumerate

See @ref{Constant expression examples}, as well as @ref{Function examples}, for
some examples.

Character expressions are defined as follows:

@example
@var{expression-char}:
  "@var{string}" |
  @var{string-id} |
  StrCat[ @var{expression-char} <,@dots{}> ] |
  Str[ @var{expression-char} <,@dots{}> ]
  StrChoice[ @var{expression}, @var{expression-char}, @var{expression-char} ] |
  StrSub[ @var{expression-char}, @var{expression}, @var{expression} ] |
  StrSub[ @var{expression-char}, @var{expression} ] |
  UpperCase [ @var{expression-char} ] |
  Sprintf [ @var{expression-char} ] |
  Sprintf[ @var{expression-char}, @var{expression-cst-list} ] |
  NameToString ( @var{string} ) | N2S ( @var{string} ) |
  GetString[ @var{expression-char} <, @var{expression-char},> ] |
  Date | CurrentDirectory | CurrentDir |
  AbsolutePath [ @var{expression-char} ] |
  DirName [ @var{expression-char} ] |
  OnelabAction
@end example

@noindent @code{StrCat} and @code{Str} permit to concatenate
character expressions (@code{Str} adds a newline character after each
string except the last) when creating a string. @code{Str} is also used
to create string lists (when @var{string-id} is followed by
@code{()}). @code{StrChoice} returns the first or second
@var{expression-char} depending on the value of @var{expression}.
@code{StrSub} returns the portion of the string that starts at the
character position given by the first @var{expression} and spans the
number of characters given by the second @var{expression} or until the
end of the string (whichever comes first; or always if the second
@var{expression} is not provided). @code{UpperCase} converts the
@var{expression-char} to upper case. @code{Sprintf} is equivalent to the
@code{sprintf} C function (where @var{expression-char} is a format
string that can contain floating point formatting characters: @code{%e},
@code{%g}, etc.).  @code{NameToString} converts a variable name into a
string.  @code{GetString} allows to get the value of a ONELAB string
variable (the optional second argument specifies the default value
returned if the variable does not exist.)  @code{Date} permits to access
the current date. @code{CurrentDirectory} and @code{CurrentDir} return
the directory of the @code{.pro} file. @code{AbsolutePath} returns the
absolute path of a file. @code{DirName} returns the directory of a
file. @code{OnelabAction} returns the current ONELAB action
(e.g. @code{check} or @code{compute}).

List of character expressions are defined as:

@example
@var{expression-char-list}:
  @var{expression-char} <,@dots{}>
@end example

@c -------------------------------------------------------------------------
@c Operators
@c -------------------------------------------------------------------------

@node Operators, Functions, Constants, Expressions
@section Operators

@menu
* Operator types::
* Evaluation order::
@end menu

@c .........................................................................
@c Types
@c .........................................................................

@node Operator types, Evaluation order, Operators, Operators
@subsection Operator types

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

@cindex Operators, definition
@cindex Unary operators
@cindex Binary operators
@cindex Ternary operators

@vindex @var{operator-unary}
@vindex @var{operator-binary}
@vindex @var{operator-ternary-left}
@vindex @var{operator-ternary-right}

@tindex -
@tindex !
@tindex +
@tindex -
@tindex *
@tindex /\
@tindex /
@tindex ^
@tindex %
@tindex >
@tindex <
@tindex >=
@tindex <=
@tindex ==
@tindex !=
@tindex ||
@tindex &&
@tindex |
@tindex &
@tindex >>
@tindex <<
@tindex ?:

@noindent
@var{operator-unary}:
@table @code
@item -
Unary minus.
@item !
Logical not.
@end table

@noindent
@var{operator-binary}:
@table @code
@item ^
Exponentiation. The evaluation of the both arguments must result in a scalar
value.
@item *
Multiplication or scalar product, depending on the type of the arguments.
@item /\
Cross product. The evaluation of both arguments must result in vectors.
@item /
Division.
@item %
Modulo. The evaluation of the second argument must result in a scalar value.
@item +
Addition.
@item -
Subtraction.
@item ==
Equality.
@item !=
Inequality.
@item >
Greater. The evaluation of both arguments must result in scalar values.
@item >=
Greater or equality. The evaluation of both arguments must result in
scalar values.
@item <
Less. The evaluation of both arguments must result in scalar values.
@item <=
Less or equality. The evaluation of both arguments must result in scalar values.
@item &&
Logical `and'. The evaluation of both arguments must result in scalar
values.
@item ||
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 @code{||} is
evaluated even if the first one is true.
@item &
Binary `and'.
@item |
Binary `or'.
@item >>
Bitwise right-shift operator. Shifts the bits of the first argument to the right by the number of bits specified by the second argument.
@item <<
Bitwise left-shift operator. Shifts the bits of the first argument to the left by the number of bits specified by the second argument.
@end table

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


@c .........................................................................
@c Evaluation
@c .........................................................................

@node Evaluation order,  , Operator types, Operators
@subsection Evaluation order

@cindex Evaluation, order
@cindex Order of evaluation
@cindex Operation, priorities
@cindex Priorities, operations

@tindex ()

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

@table @code
@item ^
@item - (unary), !
@item | &
@item /\
@item *, /, %
@item +, -
@item <, >, <=, >=, <<, >>
@item !=, ==
@item &&, ||
@item ?:
@end table


@c -------------------------------------------------------------------------
@c Functions
@c -------------------------------------------------------------------------

@node Functions, Current values, Operators, Expressions
@section Functions

@cindex Function, definition
@cindex Built-in functions
@cindex Piecewise functions
@cindex Arguments
@cindex Parameters

@vindex @var{built-in-function-id}

Two types of functions coexist in GetDP: user-defined functions
(@var{function-id}, see @ref{Function}) and built-in functions
(@var{built-in-function-id}, defined in this section).

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

@example
@var{built-in-function-id} [ < @var{expression-list} > ] < @{ @var{expression-cst-list} @} >
@end example

@noindent with

@example
@var{built-in-function-id}:
  @var{math-function-id} |
  @var{extended-math-function-id} |
  @var{green-function-id} |
  @var{type-function-id} |
  @var{coord-function-id} |
  @var{misc-function-id}
@end example

@noindent Notes:
@enumerate
@item
All possible values for @var{built-in-function-id} are listed in
@ref{Types for Function}.
@item
Classical mathematical functions (@pxref{Math functions}) are
the only functions allowed in a constant definition (see the definition of
@var{expression-cst} in @ref{Constants}).
@end enumerate


@c -------------------------------------------------------------------------
@c Current Values
@c -------------------------------------------------------------------------

@node Current values, Arguments, Functions, Expressions
@section Current values

@cindex Current values
@cindex Values, current

@tindex $Time
@tindex $DTime
@tindex $Theta
@tindex $TimeStep
@tindex $Breakpoint
@tindex $Iteration
@tindex $EigenvalueReal
@tindex $EigenvalueImag
@tindex $X
@tindex $XS
@tindex $Y
@tindex $YS
@tindex $Z
@tindex $ZS
@tindex $A
@tindex $B
@tindex $C

Current values return the current floating point value of an internal
GetDP variable:

@table @code
@item $Time
Value of the current time. This value is set to zero for non time dependent
analyses.
@item $DTime
Value of the current time increment used in a time stepping algorithm.
@item $Theta
Current theta value in a theta time stepping algorithm.
@item $TimeStep
Number of the current time step in a time stepping algorithm.
@item $Breakpoint
In case of a breakpoint hit in TimeLoopAdaptive it is the number of the
current breakpoint. In the other case when $Time corresponds not to a
breakpoint the value is -1.
@item $Iteration, $NLIteration
Current iteration in a nonlinear loop.
@item $Residual, $NLResidual
Current residual in a nonlinear loop.
@item $EigenvalueReal
Real part of the current eigenvalue.
@item $EigenvalueImag
Imaginary part of the current eigenvalue.
@item $X, $XS
Value of the current (destination or source) X-coordinate.
@item $Y, $YS
Value of the current (destination or source) Y-coordinate.
@item $Z, $ZS
Value of the current (destination or source) Z-coordinate.
@item $A, $B, $C
Value of the current parametric coordinates used in the parametric
@code{OnGrid} @code{PostOperation} (@pxref{Types for PostOperation}).
@item $QuadraturePointIndex
Index of the current quadrature point.
@item $KSPIteration
Current iteration in a Krylov subspace solver.
@item $KSPResidual
Current residual in a Krylov subspace solver.
@item $KSPIterations
Total number of iterations of Krylov subspace solver.
@item $KSPSystemSize
System size of Krylov subspace solver.
@end table

@noindent Note:
@enumerate
@item
The current X, Y and Z coordinates refer to the `physical world'
coordinates, i.e., coordinates in which the mesh is expressed.
@end enumerate

Current values are ``read-only''. User-defined run-time variables, which
share the same syntax but whose value can be changed in an
@var{expression}, are defined in @ref{Run-time variables and registers}.

@c -------------------------------------------------------------------------
@c Arguments
@c -------------------------------------------------------------------------

@node Arguments, Run-time variables and registers, Current values, Expressions
@section Arguments

@cindex Arguments, definition

@vindex @var{argument}

@tindex $@var{integer}

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

@example
@var{argument}:
  $@var{integer}
@end example

See @ref{Function}, and @ref{Function examples}, for more details.


@c -------------------------------------------------------------------------
@c Run-time variables and registers
@c -------------------------------------------------------------------------

@node Run-time variables and registers, Fields, Arguments, Expressions
@section Run-time variables and registers

@cindex Run-time variables, definition
@cindex Registers, definition

@vindex @var{variable-set}
@vindex @var{variable-get}
@vindex @var{register-set}
@vindex @var{register-get}

@tindex #@var{expression-cst}

Constant expressions (@var{expression-cst}s) are evaluated only once
during the analysis of the problem definition structure, cf.@:
@ref{Constants}. While this is perfectly fine in most situations,
sometimes it is necessary to store and modify variables at run-time. For
example, an iteration in a @code{Resolution} could depend on values
computed at run-time. Also, to speed-up the evaluation of
@var{expression}s (which are evaluated at runtime through GetDP's
internal stack mechanism), it can be useful to save some results in a
temporary variable, at run-time, in order to reuse them later on.

Two mechanisms exit to handle such cases: run-time variables (which
follow the same syntax as @ref{Current values}), and registers.

Run-time variables have the following syntax:
@example
@var{variable-set}:
  $@var{variable-id} = @var{expression}

@var{variable-get}:
  $@var{variable-id}

@var{variable-id}:
  @var{string} |
  @var{string} ~ @{ @var{expression-cst} @} <,@dots{}>
@end example

@noindent Thus, run-time variables can simply be defined anywhere in an @var{expression}
and be reused later on. Current values can be seen as special cases of
run-time variables, which are read-only.

Registers have the following syntax:
@example
@var{register-set}:
  @var{expression}#@var{expression-cst}

@var{register-get}:
  #@var{expression-cst}
@end example

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

See @ref{Function examples}, for an example.

@c -------------------------------------------------------------------------
@c Fields
@c -------------------------------------------------------------------------

@node Fields, Macros loops and conditionals, Run-time variables and registers, Expressions
@section Fields

@cindex Fields
@cindex Operators, differential
@cindex Differential operators
@cindex Discrete quantities
@cindex Quantities, discrete
@cindex Interpolation
@cindex Gradient
@cindex Curl
@cindex Divergence
@cindex Exterior derivative
@cindex Derivative, exterior

@vindex @var{quantity}
@vindex @var{quantity-id}
@vindex @var{quantity-dof}
@vindex @var{quantity-operator}

A discretized quantity (defined in a function space, cf.@:
@ref{FunctionSpace}) is represented between braces @code{@{@}}, and can only
appear in well-defined expressions in @code{Formulation}
(@pxref{Formulation}) and @code{PostProcessing} (@pxref{PostProcessing})
objects:

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

@noindent with

@example
@var{quantity-id}:
  @var{string} |
  @var{string} ~ @{ @var{expression-cst} @}
@end example

@noindent and

@noindent
@var{quantity-dof}:
@ftable @code

@item Dof
Defines a vector of discrete quantities (vector of @code{D}egrees @code{o}f
@code{f}reedom), to be used only in @code{Equation} terms of formulations to
define (elementary) matrices.  Roughly said, the @code{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.

An @code{Equation} term must be linear with respect to the
@code{Dof}. Thus, for example, a nonlinear term like
@example
Integral @{ [ f[] * Dof@{T@}^4 , @{T@} ]; @dots{} @}
@end example
must first be linearized; and while
@example
Integral @{ [ f[] * Dof@{T@} , @{T@} ]; @dots{} @}
Integral @{ [ -f[] * 12 , @{T@} ]; @dots{} @}
@end example
is valid, the following, which is affine but not linear, is not:
@example
Integral @{ [ f[] * (Dof@{T@} - 12) , @{T@} ]; @dots{} @}
@end example

GetDP supports two linearization techniques. The first is functional
iteration (or Picard method), where one simply plugs the value obtained
at the previous iteration into the nonlinear equation (the previous
value is known, and is accessed e.g. with @code{@{T@}} instead
@code{Dof@{T@}}). The second is the Newton-Raphson iteration, where the
Jacobian is specified with a @code{JacNL} equation term.
@c FIXME See @url{https://onelab.info/trac/getdp} for an example.

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

@end ftable

@noindent
@var{quantity-operator}:
@ftable @code

@item d
Exterior derivative (d): applied to a @var{p}-form, gives a (@var{p+1})-form.

@item Grad
Gradient: applied to a scalar field, gives a vector.

@item Curl
@itemx Rot
Curl: applied to a vector field, gives a vector.

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

@item D1
Applies the operator specified in the first argument of @code{dFunction
@{ @var{basis-function-type}, @var{basis-function-type} @}}
(@pxref{FunctionSpace}).  This is currently only used for
nodal-interpolated vector fields (interpolated with @code{BF_Node_X},
@code{BF_Node_Y}, @code{BF_Node_Z})

When the first @var{basis-function-type} in @code{dFunction} is set to
@code{BF_NodeX_D1} for component X, @code{BF_NodeY_D1} for component Y
and @code{BF_NodeZ_D1} for component Z, then @code{D1} applied to a
vector [u_x, u_y, u_z] gives:
@tex
$$ \left[{{\partial u_x} \over {\partial x}}, {{\partial u_y} \over
{\partial y}}, {{\partial u_z} \over {\partial z}}\right] $$
@end tex
@ifnottex
[du_x/dx, du_y/dy, du_z/dz]
@end ifnottex
Note that in this case specifying explicitely @code{dFunction} is not
necessary, as @code{BF_NodeX_D1}, @code{BF_NodeY_D1} and
@code{BF_NodeZ_D1} are assigned by default as the ``@code{D1}
derivatives'' of @code{BF_NodeX}, @code{BF_NodeY} and @code{BF_NodeZ}.
This also holds for @code{BF_GroupOfNodes_X},  @code{BF_GroupOfNodes_Y}
and  @code{BF_GroupOfNodes_Z}.

When the first @var{basis-function-type} in @code{dFunction} is set to
@code{BF_NodeX_D12} for component X and @code{BF_NodeY_D12} for
component Y, then @code{D1} applied to a vector [u_x, u_y] gives:
@tex
$$ \left[{{\partial u_x} \over {\partial x}}, {{\partial u_y} \over
{\partial y}}, {{\partial u_y} \over {\partial x}} + {{\partial u_x}
\over {\partial y}}\right] $$
@end tex
@ifnottex
[du_x/dx, du_y/dy, du_y/dx + du_x/dy]
@end ifnottex

@noindent

@noindent
@item D2
Applies the operator specified in the second argument of @code{dFunction
@{ @var{basis-function-type}, @var{basis-function-type} @}}
(@pxref{FunctionSpace}).  This is currently only used for
nodal-interpolated vector fields (interpolated with @code{BF_Node_X},
@code{BF_Node_Y}, @code{BF_Node_Z})

More specifically, when the second @var{basis-function-type} is to
@code{BF_NodeX_D2} for component X, @code{BF_NodeY_D2} for component Y
and @code{BF_NodeZ_D2} for component Z, then @code{D2} applied to a
vector [u_x, u_y, u_z] gives:
@tex
$$ \left[{{\partial u_y} \over {\partial x}} + {{\partial u_x} \over
{\partial y}}, {{\partial u_z} \over {\partial y}} + {{\partial u_y}
\over {\partial z}}, {{\partial u_x} \over {\partial z}} + {{\partial
u_z} \over {\partial x}}\right] $$
@end tex
@ifnottex
[du_y/dx + du_x/dy, du_z/dy + du_y/dz, du_x/dz + du_z/dx]
@end ifnottex
Note that in this case specifying explicitely @code{dFunction} is not
necessary, as @code{BF_NodeX_D2}, @code{BF_NodeY_D2} and
@code{BF_NodeZ_D2} are assigned by default as the ``@code{D2}
derivatives'' of @code{BF_NodeX}, @code{BF_NodeY} and @code{BF_NodeZ}.
This also holds for @code{BF_GroupOfNodes_X}, @code{BF_GroupOfNodes_Y}
and @code{BF_GroupOfNodes_Z}.

@c This is very specific, and very rarely used

@c @noindent
@c @item dInv
@c d^(-1): applied to a p-form, gives a (p-1)-form.

@c @item GradInv
@c Inverse grad: applied to a gradient field, gives a scalar.

@c @item CurlInv
@c @itemx RotInv
@c Inverse curl: applied to a curl field, gives a vector.

@c @item DivInv
@c Inverse div: applied to a divergence field.

@end ftable

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

@c -------------------------------------------------------------------------
@c Macros, loops and conditionals
@c -------------------------------------------------------------------------

@node Macros loops and conditionals,  , Fields, Expressions
@section Macros, loops and conditionals

@cindex Macros
@cindex Loops
@cindex Conditionals
@cindex Parse

@vindex @var{loop}

Macros are defined as follows:

@ftable @code

@item Macro @var{string} | @var{expression-char}
Begins the declaration of a user-defined file macro named
@var{string}. The body of the macro starts on the line after
`@code{Macro @var{string}}', and can contain any GetDP command.

@item Return
Ends the body of the current user-defined file macro. Macro declarations
cannot be imbricated, and must be made outside any GetDP object.

@item Macro ( @var{expression-char} , @var{expression-char} ) ;
Begins the declaration of a user-defined string macro. The body of the
macro is given explicitly as the second argument.

@end ftable

Macros, 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).

@var{loop}:

@ftable @code

@item Call @var{string}  | @var{expression-char};
Executes the body of a (previously defined) macro named @var{string}.

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

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

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

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

@item EndFor
Ends a matching @code{For} command.

@item If ( @var{expression-cst} )
The body enclosed between `@code{If ( @var{expression-cst} )}' and the matching
@code{ElseIf}, @code{Else} or @code{EndIf}, is evaluated if @var{expression-cst}
is non-zero.

@item ElseIf ( @var{expression-cst} )
The body enclosed between `@code{ElseIf ( @var{expression-cst} )}' and the next
matching @code{ElseIf}, @code{Else} or @code{EndIf}, is evaluated if
@var{expression-cst} is non-zero and none of the @var{expression-cst} of the
previous matching codes @code{If} and @code{ElseIf} were non-zero.

@item Else
The body enclosed between @code{Else} and the matching @code{EndIf} is evaluated
if none of the @var{expression-cst} of the previous matching codes
@code{If} and @code{ElseIf} were non-zero.

@item EndIf
Ends a matching @code{If} command.

@item LevelTest
Variable equal to the level of imbrication of a body in an
@code{If}-@code{EndIf} test.

@item Parse [ @var{expression-char} ];
Parse the given string.
@end ftable

@c =========================================================================
@c Objects
@c =========================================================================

@node Objects, Types for objects, Expressions, Top
@chapter Objects

@cindex Objects, definition

This chapter presents the formal definition of the ten GetDP objects
mentioned in @ref{Overview}. To be concise, all the possible parameters for
these objects are not given here (cf.@: the @var{etc} syntactic rule defined
in @ref{Syntactic rules}). Please refer to @ref{Types for objects}, for
the list of all available options.

@menu
* Group::
* Function::
* Constraint::
* FunctionSpace::
* Jacobian::
* Integration::
* Formulation::
* Resolution::
* PostProcessing::
* PostOperation::
@end menu


@c -------------------------------------------------------------------------
@c Group
@c -------------------------------------------------------------------------

@node Group, Function, Objects, Objects
@section @code{Group}: defining topological entities

@cindex Mesh
@cindex Grid
@cindex Discretized Geometry
@cindex Group, definition
@cindex Topology
@cindex Entities, topological
@cindex Region groups
@cindex Function groups
@cindex Tree

@tindex Group
@tindex DefineGroup
@tindex =
@tindex All

@vindex @var{group-id}
@vindex @var{group-def}
@vindex @var{group-type}
@vindex @var{group-list}
@vindex @var{group-list-item}
@vindex @var{group-sub-type}

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 (@pxref{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, @dots{} 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
@code{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 @code{DefineConstant} procedure
introduced for constants in @ref{Constants}.

The syntax for the definition of groups is:

@example
Group @{
  < DefineGroup [ @var{group-id} <@{@var{integer}@}> <,@dots{}> ]; > @dots{}
  < @var{group-id} = @var{group-def}; > @dots{}
  < @var{group-id} += @var{group-def}; > @dots{}
  < @var{group-id} -= @var{group-def}; > @dots{}
  < @var{affectation} > @dots{}
  < @var{loop} > @dots{}
@}
@end example

@noindent with

@example
@var{group-id}:
  @var{string} |
  @var{string} ~ @{ @var{expression-cst} @}

@var{group-def}:
  @var{group-type} [ @var{group-list} <, @var{group-sub-type} @var{group-list} > ] |
  @var{group-id} <@{<@var{integer}>@}> |
  #@var{group-list}

@var{group-type}:
  Region | Global | NodesOf | EdgesOf | @var{etc}

@var{group-list}:
  All | @var{group-list-item} | @{ @var{group-list-item} <,@dots{}> @}

@var{group-list-item}:
  @var{integer} |
  @var{integer} : @var{integer} |
  @var{integer} : @var{integer} : @var{integer} |
  @var{group-id} <@{<@var{integer}>@}>

@var{group-sub-type}:
  Not | StartingOn | OnPositiveSideOf | @var{etc}
@end example

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

See @ref{Types for Group}, for the complete list of options and @ref{Group
examples}, for some examples.


@c -------------------------------------------------------------------------
@c Function
@c -------------------------------------------------------------------------

@node Function, Constraint, Group, Objects
@section @code{Function}: defining global and piecewise expressions

@cindex Function, definition
@cindex Piecewise functions
@cindex User-defined functions

@tindex Function
@tindex DefineFunction
@tindex =

@vindex @var{function-id}

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
@code{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:

@example
Function @{
  < DefineFunction [ @var{function-id} <,@dots{}> ]; > @dots{}
  < @var{function-id} [ < @var{group-def} <, @var{group-def} > > ] = @var{expression}; > @dots{}
  < @var{affectation} > @dots{}
  < @var{loop} > @dots{}
@}
@end example

@noindent with

@example
@var{function-id}:
  @var{string}
@end example

@noindent Note:
@enumerate
@item
The first optional @var{group-def} in brackets must be of @code{Region} type, and
indicates on which region the (piecewise) function is defined.
The second optional @var{group-def} in brackets, also of @code{Region} type, defines
an association with a second region for mutual contributions.
A default piecewise function can be defined with @code{All} for @var{group-def},
for all the other non-defined regions.
Warning: it is incorrect to write @code{f[reg1]=1; g[reg2]=f[]+1;} since the
domains of definition of @code{f[]} and @code{g[]} don't match.
@item
One can also define initially empty functions inline by replacing the
expression with @code{***}.
@end enumerate

See @ref{Types for Function}, for the complete list of built-in functions
and @ref{Function examples}, for some examples.


@c -------------------------------------------------------------------------
@c Constraint
@c -------------------------------------------------------------------------

@node Constraint, FunctionSpace, Function, Objects
@section @code{Constraint}: specifying constraints on function spaces and formulations

@cindex Constraint, definition
@cindex Circuit equations
@cindex Boundary conditions
@cindex Networks

@tindex Constraint
@tindex Append
@tindex Name
@tindex Type
@tindex Case
@tindex Region
@tindex SubRegion
@tindex TimeFunction

@vindex @var{constraint-id}
@vindex @var{constraint-type}
@vindex @var{constraint-val}
@vindex @var{constraint-case-id}
@vindex @var{constraint-case-val}

Constraints can be referred to in @code{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
@code{Formulation} objects.

The syntax for the definition of constraints is:

@example
Constraint @{
  @{ < Append < @var{expression-cst} >; >
    Name @var{constraint-id}; Type @var{constraint-type};
    Case @{
      @{ Region @var{group-def}; < Type @var{constraint-type}; >
        < SubRegion @var{group-def}; > < TimeFunction @var{expression}; >
        < RegionRef @var{group-def}; > < SubRegionRef @var{group-def}; >
        < Coefficient @var{expression}; > < Function @var{expression}; >
        < Filter @var{expression}; >
        @var{constraint-val}; @} @dots{}
      < @var{loop} > @dots{}
    @}
  | Case @var{constraint-case-id} @{
      @{ Region @var{group-def}; < Type @var{constraint-type}; >
        @var{constraint-case-val}; @} @dots{}
      < @var{loop} > @dots{}
    @} @dots{}
  @} @dots{}
  < @var{affectation} > @dots{}
  < @var{loop} > @dots{}
@}
@end example

@noindent with

@example
@var{constraint-id}:
@var{constraint-case-id}:
  @var{string} |
  @var{string} ~ @{ @var{expression-cst} @}

@var{constraint-type}:
  Assign | Init | Network | Link | @var{etc}

@var{constraint-val}:
  Value @var{expression} | NameOfResolution @var{resolution-id} | @var{etc}

@var{constraint-case-val}:
  Branch @{ @var{integer}, @var{integer} @} | @var{etc}
@end example

@noindent Notes:
@enumerate
@item
The optional @code{Append < @var{expression-cst} >} (when the optional level
@var{expression-cst} is strictly positive) permits to append an existing
@code{Constraint} of the same @code{Name} with additional @code{Case}s.
@item
The constraint type @var{constraint-type} defined outside the @code{Case}
fields is applied to all the cases of the constraint, unless other types are
explicitly given in these cases.  The default type is @code{Assign}.
@item
The region type @code{Region @var{group-def}} will be the main
@var{group-list} argument of the @var{group-def} to be built for the
constraints of @code{FunctionSpace}s. The optional region type
@code{SubRegion @var{group-def}} will be the argument of the associated
@var{group-sub-type}.
@item
@var{expression} in @code{Value} of @var{constraint-val} cannot be time
dependent (@code{$Time}) because it is evaluated only once during the
pre-processing (for efficiency reasons).  Time dependences must be defined
in @code{TimeFunction @var{expression}}.
@end enumerate

See @ref{Types for Constraint}, for the complete list of options and
@ref{Constraint examples}, for some examples.


@c -------------------------------------------------------------------------
@c FunctionSpace
@c -------------------------------------------------------------------------

@node FunctionSpace, Jacobian, Constraint, Objects
@section @code{FunctionSpace}: building function spaces

@cindex Function space, definition
@cindex Discrete function spaces
@cindex Spaces, discrete
@cindex Approximation spaces
@cindex Basis Functions
@cindex Interpolation
@cindex Hierarchical basis functions

@tindex FunctionSpace
@tindex Append
@tindex Name
@tindex Type
@tindex BasisFunction
@tindex NameOfCoef
@tindex Function
@tindex dFunction
@tindex Quantity
@tindex Formulation
@tindex Group
@tindex Resolution
@tindex Support
@tindex Entity
@tindex SubSpace
@tindex NameOfBasisFunction
@tindex GlobalQuantity
@tindex Constraint
@tindex EntityType
@tindex EntitySubType
@tindex NameOfConstraint

@vindex @var{function-space-id}
@vindex @var{function-space-type}
@vindex @var{basis-function-id}
@vindex @var{basis-function-type}
@vindex @var{coef-id}
@vindex @var{sub-space-id}
@vindex @var{basis-function-list}
@vindex @var{global-quantity-id}
@vindex @var{global-quantity-type}

A @code{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
(@pxref{FunctionSpace examples}).

The syntax for the definition of function spaces is:

@example
FunctionSpace @{
  @{ < Append < @var{expression-cst} >; >
    Name @var{function-space-id};
    Type @var{function-space-type};
    BasisFunction @{
     @{ Name @var{basis-function-id}; NameOfCoef @var{coef-id};
       Function @var{basis-function-type}
         < @{ Quantity @var{quantity-id};
             Formulation @var{formulation-id} @{ @var{expression-cst} @};
             Group @var{group-def};
             Resolution @var{resolution-id} @{ @var{expression-cst} @} @} >;
       < dFunction @{ @var{basis-function-type}, @var{basis-function-type} @} ; >
       Support @var{group-def}; Entity @var{group-def}; @} @dots{}
    @}
  < SubSpace @{
     @{ < Append < @var{expression-cst} >; >
       Name @var{sub-space-id};
       NameOfBasisFunction @var{basis-function-list}; @} @dots{}
    @} >
  < GlobalQuantity @{
     @{ Name @var{global-quantity-id}; Type @var{global-quantity-type};
       NameOfCoef @var{coef-id}; @} @dots{}
    @} >
  < Constraint @{
     @{ NameOfCoef @var{coef-id};
       EntityType Auto | @var{group-type}; < EntitySubType @var{group-sub-type}; >
       NameOfConstraint @var{constraint-id} <@{@}>; @} @dots{}
    @} >
  @} @dots{}
  < @var{affectation} > @dots{}
  < @var{loop} > @dots{}
@}
@end example

@noindent with

@example
@var{function-space-id}:
@var{formulation-id}:
@var{resolution-id}:
  @var{string} |
  @var{string} ~ @{ @var{expression-cst} @}

@var{basis-function-id}:
@var{coef-id}:
@var{sub-space-id}:
@var{global-quantity-id}:
  @var{string}

@var{function-space-type}:
  Scalar | Vector | Form0 | Form1 | @var{etc}

@var{basis-function-type}:
  BF_Node | BF_Edge | @var{etc}

@var{basis-function-list}:
  @var{basis-function-id} | @{ @var{basis-function-id} <,@dots{}> @}

@var{global-quantity-type}:
  AliasOf | AssociatedWith

@end example

@noindent Notes:
@enumerate
@item
The optional @code{Append < @var{expression-cst} >} (when the optional level
@var{expression-cst} is strictly positive; its omission fixes it to a top
value) permits to append an existing
@code{FunctionSpace} of the same @code{Name} with additional
@code{BasisFunction}s, @code{SubSpace}s, @code{GlobalQuantity}'s and
@code{Constraint}s,
or an existing @code{SubSpace} of the same @code{Name} with additional
@code{NameOfBasisFunction}'s. If the @code{Append} @code{FunctionSpace} level is 2,
the @code{Append} @code{SubSpace} level is automatically 1 if omitted.
@item
When the definition region of a function type group used as an @code{Entity} of
a @code{BasisFunction} is the same as that of the associated @code{Support},
it is replaced by @code{All} for more efficient treatments during the
computation process (this prevents the construction and the analysis of a list
of geometrical entities).
@item
The same @code{Name} for several @code{BasisFunction} fields permits to
define piecewise basis functions; separate @code{NameOfCoef}s must be
defined for those fields.
@item
A constraint is associated with geometrical entities defined by an
automatically created @code{Group} of type @var{group-type}
(@code{Auto} automatically fixes it as the @code{Entity} @var{group-def}
type of the related @code{BasisFunction}), using the
@code{Region} defined in a @code{Constraint} object as its main
argument, and the optional @code{SubRegion} in the same object as a
@var{group-sub-type} argument.
@item
A global basis function (@code{BF_Global} or @code{BF_dGlobal}) needs
parameters, i.e., it is given by the quantity (@var{quantity-id})
pre-computed from multiresolutions performed on multiformulations.
@item
Explicit derivatives of the basis functions can be specified using
@code{dFunction @{ @var{basis-function-type} , @var{basis-function-type}
@}}. These derivates can be accessed using the special @code{D1} and
@code{D2} operators (@pxref{Fields}).
@end enumerate

See @ref{Types for FunctionSpace}, for the complete list of options and
@ref{FunctionSpace examples}, for some examples.


@c -------------------------------------------------------------------------
@c Jacobian
@c -------------------------------------------------------------------------

@node Jacobian, Integration, FunctionSpace, Objects
@section @code{Jacobian}: defining jacobian methods

@cindex Jacobian, definition
@cindex Transformations, geometric
@cindex Geometric transformations
@cindex Coordinate change
@cindex Change of coordinates
@cindex Axisymmetric, transformation

@tindex Jacobian
@tindex Append
@tindex Name
@tindex Case
@tindex Region
@tindex All

@vindex @var{jacobian-id}
@vindex @var{jacobian-type}

Jacobian methods can be referred to in @code{Formulation} and
@code{PostProcessing} objects to be used in the computation of integral
terms and for changes of coordinates. They are based on @code{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 @code{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:

@example
Jacobian @{
  @{ < Append < @var{expression-cst} >; >
    Name @var{jacobian-id};
    Case @{
      @{ Region @var{group-def} | All;
        Jacobian @var{jacobian-type} < @{ @var{expression-cst-list} @} >; @} @dots{}
    @}
  @} @dots{}
@}
@end example

@noindent with

@example
@var{jacobian-id}:
  @var{string}

@var{jacobian-type}:
  Vol | Sur | VolAxi | @var{etc}
@end example


@noindent Note:
@enumerate
@item
The optional @code{Append < @var{expression-cst} >} (when the optional level
@var{expression-cst} is strictly positive) permits to append an existing
@code{Jacobian} of the same @code{Name} with additional @code{Case}s.
@item
The default case of a @code{Jacobian} object is defined by @code{Region All}
and must follow all the other cases.
@end enumerate

See @ref{Types for Jacobian}, for the complete list of options and
@ref{Jacobian examples}, for some examples.

@c -------------------------------------------------------------------------
@c Integration
@c -------------------------------------------------------------------------

@node Integration, Formulation, Jacobian, Objects
@section @code{Integration}: defining integration methods

@cindex Integration, definition
@cindex Analytical integration
@cindex Numerical integration
@cindex Gauss, integration

@tindex Integration
@tindex Append
@tindex Name
@tindex Criterion
@tindex Case
@tindex Type
@tindex GeoElement
@tindex NumberOfPoints
@tindex Analytic

@vindex @var{integration-id}
@vindex @var{element-type}
@vindex @var{integration-type}

Various numerical or analytical integration methods can be referred to in
@code{Formulation} and @code{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:

@example
Integration @{
  @{ < Append < @var{expression-cst} >; >
    Name @var{integration-id}; < Criterion @var{expression}; >
    Case @{
    < @{ Type @var{integration-type};
        Case @{
          @{ GeoElement @var{element-type}; NumberOfPoints @var{expression-cst} @} @dots{}
        @}
      @} @dots{} >
    < @{ Type Analytic; @} @dots{} >
    @}
  @} @dots{}
@}
@end example

@noindent with

@example
@var{integration-id}:
  @var{string}

@var{integration-type}:
  Gauss | @var{etc}

@var{element-type}:
  Line | Triangle | Tetrahedron @var{etc}
@end example


@noindent Note:
@enumerate
@item
The optional @code{Append < @var{expression-cst} >} (when the optional level
@var{expression-cst} is strictly positive) permits to append an existing
@code{Integration} of the same @code{Name} with additional @code{Case}s.
@end enumerate

See @ref{Types for Integration}, for the complete list of options and
@ref{Integration examples}, for some examples.

@c -------------------------------------------------------------------------
@c Formulation
@c -------------------------------------------------------------------------

@node Formulation, Resolution, Integration, Objects
@section @code{Formulation}: building equations

@cindex Formulation, definition
@cindex Equations
@cindex Time derivative
@cindex Derivative, time
@cindex Elementary matrices
@cindex Matrices, elementary
@cindex Local quantity
@cindex Global quantity
@cindex Integral quantity
@cindex Quantity, local
@cindex Quantity, global
@cindex Quantity, integral
@cindex Symmetry, integral kernel

@tindex Formulation
@tindex Append
@tindex Name
@tindex Type
@tindex Quantity
@tindex NameOfSpace
@tindex Symmetry
@tindex In
@tindex Jacobian
@tindex Integration
@tindex IndexOfSystem
@tindex Equation
@tindex GlobalTerm
@tindex GlobalEquation
@tindex Network
@tindex NameOfConstraint
@tindex Node
@tindex Loop

@vindex @var{formulation-id}
@vindex @var{formulation-type}
@vindex @var{local-term-type}
@vindex @var{quantity-type}
@vindex @var{term-op-type}

The @code{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
@var{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 @code{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:

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

@noindent with

@example
@var{formulation-id}:
  @var{string} |
  @var{string} ~ @{ @var{expression-cst} @}

@var{formulation-type}:
  FemEquation | @var{etc}

@var{local-term-type}:
  Integral | deRham

@var{equation-term-sub-type}:
  Self (default) | Mutual | SelfAndMutual

@var{quantity-type}:
  Local | Global | Integral

@var{term-op-type}:
  DtDof | DtDtDof | Eig | JacNL | @var{etc}
@end example

@noindent Note:
@enumerate
@item
The optional @code{Append < @var{expression-cst} >} (when the optional level
@var{expression-cst} is strictly positive) permits to append an existing
@code{Formulation} of the same @code{Name} with additional
@code{Quantity}'s and @code{Equation}s.
@item
@code{IndexOfSystem} permits to resolve ambiguous cases when several
quantities belong to the same function space, but to different systems of
equations. The @var{integer} parameter then specifies the index in the list
of an @code{OriginSystem} command (@pxref{Resolution}).
@item
A @code{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. The optional associated
@code{SubType} defines either self (default) or mutual contributions, or both.
Mutual contributions need piecewise functions defined on pairs or regions.
@item
A @code{GlobalEquation} defines a global equation to be assembled in the
matrix of the system.
@end enumerate

See @ref{Types for Formulation}, for the complete list of options and
@ref{Formulation examples}, for some examples.


@c -------------------------------------------------------------------------
@c Resolution
@c -------------------------------------------------------------------------

@node Resolution, PostProcessing, Formulation, Objects
@section @code{Resolution}: solving systems of equations

@cindex Resolution, definition
@cindex Linear system solving
@cindex Nonlinear system solving
@cindex Iterative loop
@cindex Relaxation factor
@cindex Newton, nonlinear scheme
@cindex Picard, nonlinear scheme
@cindex Newmark, time scheme
@cindex Theta, time scheme
@cindex Solving, system
@cindex Time stepping
@cindex Time, discretization
@cindex Frequency
@cindex System, definition
@cindex Complex-valued, system

@tindex Resolution
@tindex Append
@tindex Name
@tindex System
@tindex NameOfFormulation
@tindex Type
@tindex Frequency
@tindex DestinationSystem
@tindex OriginSystem
@tindex NameOfMesh
@tindex Solver
@tindex Operation

@vindex @var{resolution-id}
@vindex @var{system-id}
@vindex @var{system-type}
@vindex @var{formulation-list}
@vindex @var{resolution-op}

The operations available in a @code{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 @code{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:

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

@noindent with

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

@var{formulation-list}:
  @var{formulation-id} <@{@}> | @{ @var{formulation-id} <@{@}> <,@dots{}> @}

@var{system-type}:
  Real | Complex

@var{resolution-op}:
  Generate[@var{system-id}] | Solve[@var{system-id}] | @var{etc}
@end example

@noindent Notes:
@enumerate
@item
The optional @code{Append < @var{expression-cst} >} (when the optional level
@var{expression-cst} is strictly positive) permits to append an existing
@code{Resolution} of the same @code{Name} with additional
@code{System}s and @code{Operation}s.
@item
The default type for a system of equations is @code{Real}. A frequency
domain analysis is defined through the definition of one or several
frequencies (@code{Frequency @var{expression-cst-list-item} | Frequency @{
@var{expression-cst-list} @}}). Complex systems of equations with no
predefined list of frequencies (e.g., in modal analyses) can be explicitely
defined with @code{Type Complex}.
@item
@code{NameOfMesh} permits to explicitely specify the mesh to be used for the
construction of the system of equations.
@item
@code{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).
@item
@code{DestinationSystem} permits to specify the destination system of a
@code{TransferSolution} operation (@pxref{Types for Resolution}).
@item
@code{OriginSystem} permits to specify the systems from which ambiguous
quantity definitions can be solved (@pxref{Formulation}).
@end enumerate

See @ref{Types for Resolution}, for the complete list of options and
@ref{Resolution examples}, for some examples.

@c -------------------------------------------------------------------------
@c PostProcessing
@c -------------------------------------------------------------------------

@node PostProcessing, PostOperation, Resolution, Objects
@section @code{PostProcessing}: exploiting computational results

@cindex Post-processing, definition
@cindex Quantity, post-processing
@cindex Results, exploitation

@tindex PostProcessing
@tindex Append
@tindex Name
@tindex NameOfFormulation
@tindex NameOfSystem
@tindex Quantity
@tindex Value
@tindex Local
@tindex Integral
@tindex In
@tindex Integration
@tindex Jacobian

@vindex @var{post-processing-id}
@vindex @var{post-quantity-id}
@vindex @var{post-quantity-type}
@vindex @var{post-value}
@vindex @var{local-value}
@vindex @var{integral-value}

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

@example
PostProcessing @{
  @{ < Append < @var{expression-cst} >; >
    Name @var{post-processing-id};
    NameOfFormulation @var{formulation-id} <@{@}>; < NameOfSystem @var{system-id}; >
    Quantity @{
      @{ < Append < @var{expression-cst} >; >
        Name @var{post-quantity-id}; Value @{ @var{post-value} @dots{} @} @} @dots{}
      < @var{loop} > @dots{}
    @}
  @} @dots{}
  < @var{affectation} > @dots{}
  < @var{loop} > @dots{}
@}
@end example

@noindent with

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

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

@var{local-value}:
  [ @var{expression} ]; In @var{group-def}; Jacobian @var{jacobian-id};

@var{integral-value}:
  [ @var{expression} ]; In @var{group-def};
  Integration @var{integration-id}; Jacobian @var{jacobian-id};
@end example

@noindent Notes:
@enumerate
@item
The optional @code{Append < @var{expression-cst} >} (when the optional level
@var{expression-cst} is strictly positive; its omission fixes it to a top
value) permits to append an existing
@code{PostProcessing} of the same @code{Name} with additional
@code{Value}s,
or an existing @code{Quantity} of the same @code{Name} with additional
@code{Quantity}'s. If the @code{Append} @code{PostProcessing} level is 2,
the @code{Append} @code{Quantity} level is automatically 1 if omitted.
Fixing the @code{Append} @code{Quantity} level to @var{-n} suppresses the
@var{n} lastly defined @code{Quantity}'s before appending.
@item
The quantity defined with @var{integral-value} is piecewise defined over the
elements of the mesh of @var{group-def}, and takes, in each element, the
value of the integration of @var{expression} over this element. The global
integral of @var{expression} over a whole region (being either
@var{group-def} or a subset of @var{group-def}) has to be defined in the
@code{PostOperation} with the @code{@var{post-quantity-id}[@var{group-def}]}
command (@pxref{PostOperation}).
@item
If @code{NameOfSystem @var{system-id}} is not given, the system is
automatically selected as the one to which the first quantity listed in
the @code{Quantity} field of @var{formulation-id} is associated.
@end enumerate

See @ref{Types for PostProcessing}, for the complete list of options and
@ref{PostProcessing examples}, for some examples.


@c -------------------------------------------------------------------------
@c PostOperation
@c -------------------------------------------------------------------------

@node PostOperation,  , PostProcessing, Objects
@section @code{PostOperation}: exporting results

@cindex Post-operation, definition
@cindex Exporting results
@cindex Results, export
@cindex Sections
@cindex Maps
@cindex Format, output

@tindex PostOperation
@tindex Append
@tindex Name
@tindex NameOfPostProcessing
@tindex Format
@tindex Operation
@tindex UsingPost
@tindex Print

@vindex @var{post-operation-id}
@vindex @var{post-operation-op}
@vindex @var{post-operation-fmt}
@vindex @var{print-support}
@vindex @var{print-option}

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

@example
PostOperation @{
  @{ < Append < @var{expression-cst} >; >
    Name @var{post-operation-id}; NameOfPostProcessing @var{post-processing-id};
    < Hidden @var{expression-cst}; >
    < Format @var{post-operation-fmt}; >
    < TimeValue @var{expression-cst-list}; > < TimeImagValue @var{expression-cst-list}; >
    < LastTimeStepOnly < @var{expression-cst} >; >
    < OverrideTimeStepValue @var{expression-cst}; >
    < NoMesh @var{expression-cst}; > < AppendToExistingFile @var{expression-cst}; >
    < ResampleTime[@var{expression-cst}, @var{expression-cst}, @var{expression-cst}]; >
    < AppendTimeStepToFileName < @var{expression-cst} >; >
    Operation @{
      < @var{post-operation-op}; > @dots{}
    @}
  @} @dots{}
  < @var{affectation} > @dots{}
  < @var{loop} > @dots{}
@} |
PostOperation < (Append < @var{expression-cst} >) > @var{post-operation-id} UsingPost @var{post-processing-id} @{
  < @var{post-operation-op}; > @dots{}
@} @dots{}
@end example

@noindent with

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

@var{post-operation-op}:
  Print[ @var{post-quantity-id} <[@var{group-def}]>, @var{print-support} <,@var{print-option}> @dots{} ] |
  Print[ @var{expression-list}, Format "@var{string}" <,@var{print-option}> @dots{} ] |
  PrintGroup[ @var{group-id}, @var{print-support} <,@var{print-option}> @dots{} ] |
  Echo[ "@var{string}" <,@var{print-option}> @dots{} ] |
  CreateDir [ "@var{string}" ] |
  DeleteFile [ "@var{string}" ] |
  SendMergeFileRequest[ @var{expression-char} ] |
  < @var{loop} > @dots{}
  @var{etc}

@var{print-support}:
  OnElementsOf @var{group-def} | OnRegion @var{group-def} | OnGlobal | @var{etc}

@var{print-option}:
  File @var{expression-char} | Format @var{post-operation-fmt} | @var{etc}

@var{post-operation-fmt}:
  Table | TimeTable | @var{etc}
@end example

@noindent Notes:
@enumerate
@item
The optional @code{Append < @var{expression-cst} >} (when the optional level
@var{expression-cst} is strictly positive) permits to append an existing
@code{PostOperation} of the same @code{Name} with additional
@code{Operation}s.
@item
Both @code{PostOperation} syntaxes are equivalent.  The first one conforms to
the overall interface, but the second one is more concise.
@item
The format @var{post-operation-fmt} defined outside the @code{Operation}
field is applied to all the post-processing operations, unless other formats
are explicitly given in these operations with the @code{Format} option
(@pxref{Types for PostOperation}). The default format is @code{Gmsh}.
@item
The @code{ResampleTime} option allows equidistant resampling of the time steps by a
spline interpolation. The parameters are: start time, stop time, time step.
@item
The optional argument @code{[@var{group-def}]} of the @var{post-quantity-id}
can only be used when this quantity has been defined as an
@var{integral-value} (@pxref{PostProcessing}). In this case, the sum of all
elementary integrals is performed over the region @var{group-def}.
@end enumerate

See @ref{Types for PostOperation}, for the complete list of options and
@ref{PostOperation examples}, for some examples.


@c =========================================================================
@c Types for Objects
@c =========================================================================

@node Types for objects, Short examples, Objects, Top
@chapter Types for objects

This chapter presents the complete list of choices associated with
metasyntactic variables introduced for the ten GetDP objects.

@cindex Types, definition
@cindex Objects, types

@menu
* Types for Group::
* Types for Function::
* Types for Constraint::
* Types for FunctionSpace::
* Types for Jacobian::
* Types for Integration::
* Types for Formulation::
* Types for Resolution::
* Types for PostProcessing::
* Types for PostOperation::
@end menu

@c -------------------------------------------------------------------------
@c Group
@c -------------------------------------------------------------------------

@node Types for Group, Types for Function, Types for objects, Types for objects
@section Types for @code{Group}

@cindex Group, types

@vindex @var{group-type}

@noindent Types in

@example
@var{group-type} [ @var{R1} <, @var{group-sub-type} @var{R2} <, @var{group-sub-type-2} @var{R3} > > ]
@end example

@noindent
@code{@var{group-type} < @var{group-sub-type} < @var{group-sub-type-2} > >}:
@ftable @code

@item Region
Regions in @var{R1}.

@item Global
Regions in @var{R1}
(variant of @code{Region} used with global @code{BasisFunction}s
@code{BF_Global} and @code{BF_dGlobal}).

@item NodesOf
Nodes of elements of @var{R1}

< @code{Not}: but not those of @var{R2} >.

@item EdgesOf
Edges of elements of @var{R1}

< @code{Not}: but not those of @var{R2} >.

@item FacetsOf
Facets of elements of @var{R1}

< @code{Not}: but not those of @var{R2} >.

@item VolumesOf
Volumes of elements of @var{R1}

< @code{Not}: but not those of @var{R2} >.

@item ElementsOf
Elements of regions in @var{R1}

< @code{OnOneSideOf}: only elements on one side
of @var{R2} (non-automatic, i.e., both sides if both in @var{R1}) > |
< @code{OnPositiveSideOf}: only elements on positive (normal) side of @var{R2}
  < , @code{Not}: but not those touching only its skin @var{R3}
  (mandatory for free skins for correct separation of side layers) > >.

@item GroupsOfNodesOf
Groups of nodes of elements of @var{R1}
(a group is associated with each region).

@item GroupsOfEdgesOf
Groups of edges of elements of @var{R1}
(a group is associated with each region).

< @code{InSupport}: in a support @var{R2} being a group of type @code{ElementOf},
i.e., containing elements >.

@item GroupsOfEdgesOnNodesOf
Groups of edges incident to nodes of elements of @var{R1}
(a group is associated with each node).

< @code{Not}: but not those of @var{R2}) >.

@item GroupOfRegionsOf
Single group of elements of regions in @var{R1}
(with basis function BF_Region just one DOF is created for all elements of @var{R1}).

@item EdgesOfTreeIn
Edges of a tree of edges of @var{R1}

< @code{StartingOn}: a complete tree is first built on @var{R2} >.

@item FacetsOfTreeIn
Facets of a tree of facets of @var{R1}

< @code{StartingOn}: a complete tree is first built on @var{R2} >.

@item DualNodesOf
Dual nodes of elements of @var{R1}.

@item DualEdgesOf
Dual edges of elements of @var{R1}.

@item DualFacetsOf
Dual facets of elements of @var{R1}.

@item DualVolumesOf
Dual volumes of elements of @var{R1}.

@end ftable


@c -------------------------------------------------------------------------
@c Function
@c -------------------------------------------------------------------------

@node Types for Function, Types for Constraint, Types for Group, Types for objects
@section Types for @code{Function}

@menu
* Math functions::
* Extended math functions::
* Green functions::
* Type manipulation functions::
* Coordinate functions::
* Miscellaneous functions::
@end menu

@c .........................................................................
@c Math functions
@c .........................................................................

@node Math functions, Extended math functions, Types for Function, Types for Function
@subsection Math functions

@vindex @var{math-function-id}

The following functions are the equivalent of the functions of the C or
C++ math library. Unless indicated otherwise, arguments to these
functions can be real or complex valued when used in @var{expression}s.
When used in constant expressions (@var{expression-cst}, see
@ref{Constants}), only real-valued arguments are accepted.

@noindent
@var{math-function-id}:
@ftable @code

@item Exp
@code{[@var{expression}]}

Exponential function: e^@var{expression}.

@item Log
@code{[@var{expression}]}

Natural logarithm: ln(@var{expression}), @var{expression}>0.

@item Log10
@code{[@var{expression}]}

Base 10 logarithm: log10(@var{expression}), @var{expression}>0.

@item Sqrt
@code{[@var{expression}]}

Square root, @var{expression}>=0.

@item Sin
@code{[@var{expression}]}

Sine of @var{expression}.

@item Asin
@code{[@var{expression}]}

Arc sine (inverse sine) of @var{expression} in [-Pi/2,Pi/2],
@var{expression} in [-1,1] (real valued only).

@item Cos
@code{[@var{expression}]}

Cosine of @var{expression}.

@item Acos
@code{[@var{expression}]}

Arc cosine (inverse cosine) of @var{expression} in [0,Pi],
@var{expression} in [-1,1] (real valued only).

@item Tan
@code{[@var{expression}]}

Tangent of @var{expression}.

@item Atan
@code{[@var{expression}]}

Arc tangent (inverse tangent) of @var{expression} in [-Pi/2,Pi/2] (real
valued only).

@item Atan2
@code{[@var{expression},@var{expression}]}

Arc tangent (inverse tangent) of the first @var{expression} divided by the
second, in [-Pi,Pi] (real valued only).

@item Sinh
@code{[@var{expression}]}

Hyperbolic sine of @var{expression}.

@item Cosh
@code{[@var{expression}]}

Hyperbolic cosine of @var{expression}.

@item Tanh
@code{[@var{expression}]}

Hyperbolic tangent of the real valued @var{expression}.

@item TanhC2
@code{[@var{expression}]}

Hyperbolic tangent of a complex valued @var{expression}.

@item Fabs
@code{[@var{expression}]}

Absolute value of @var{expression} (real valued only).

@item Abs
@code{[@var{expression}]}

Absolute value of @var{expression}.

@item Floor
@code{[@var{expression}]}

Rounds downwards to the nearest integer that is not greater than
@var{expression} (real valued only).

@item Ceil
@code{[@var{expression}]}

Rounds upwards to the nearest integer that is not less than
@var{expression} (real valued only).

@item Fmod
@code{[@var{expression},@var{expression}]}

Remainder of the division of the first @var{expression} by the second,
with the sign of the first (real valued only).

@item Min
@code{[@var{expression},@var{expression}]}

Minimum of the two (scalar) expressions (real valued only).

@item Max
@code{[@var{expression},@var{expression}]}

Maximum of the two (scalar) expressions (real valued only).

@item Sign
@code{[@var{expression}]}

-1 for @var{expression} less than zero and 1 otherwise (real valued only).

@item Jn
@code{[@var{expression}]}

Returns the Bessel function of the first kind of order given by the
first @var{expression} for the value of the second @var{expression}
(real valued only).

@item dJn
@code{[@var{expression}]}

Returns the derivative of the Bessel function of the first kind of order
given by the first @var{expression} for the value of the second
@var{expression} (real valued only).

@item Yn
@code{[@var{expression}]}

Returns the Bessel function of the second kind of order given by the
first @var{expression} for the value of the second @var{expression}
(real valued only).

@item dYn
@code{[@var{expression}]}

Returns the derivative of the Bessel function of the second kind of
order given by the first @var{expression} for the value of the second
@var{expression} (real valued only).

@end ftable

@c .........................................................................
@c Extended Math
@c .........................................................................

@node Extended math functions, Green functions, Math functions, Types for Function
@subsection Extended math functions

@vindex @var{extended-math-function-id}

@noindent
@var{extended-math-function-id}:
@ftable @code

@item Cross
@code{[@var{expression},@var{expression}]}

Cross product of the two arguments; @var{expression} must be a vector.

@item Hypot
@code{[@var{expression},@var{expression}]}

Square root of the sum of the squares of its arguments.

@item Norm
@code{[@var{expression}]}

Absolute value if @var{expression} is a scalar; euclidian norm if @var{expression}
is a vector.

@item SquNorm
@code{[@var{expression}]}

Square norm: @code{Norm[@var{expression}]^2}.

@item Unit
@code{[@var{expression}]}

Normalization: @code{@var{expression}/Norm[@var{expression}]}. Returns 0 if the norm is
smaller than 1.e-30.

@item Transpose
@code{[@var{expression}]}

Transposition; @var{expression} must be a tensor.

@item Inv
@code{[@var{expression}]}

Inverse of the tensor @var{expression}.

@item Det
@code{[@var{expression}]}

Determinant of the tensor @var{expression}.

@item Rotate
@code{[@var{expression},@var{expression},@var{expression},@var{expression}]}

Rotation of a vector or tensor given by the first @var{expression} by the
angles in radians given by the last three @var{expression} values around the x-, y- and
z-axis.

@item TTrace
@code{[@var{expression}]}

Trace; @var{expression} must be a tensor.

@item Cos_wt_p
@code{[]@{@var{expression-cst},@var{expression-cst}@}}

The first parameter represents the angular frequency and the second
represents the phase. If the type of the current system is @code{Real},
@code{F_Cos_wt_p[]@{w,p@}} is identical to @code{Cos[w*$Time+p]}. If the
type of the current system is @code{Complex}, it is identical to
@code{Complex[Cos[p],Sin[p]]}.

@item Sin_wt_p
@code{[]@{@var{expression-cst},@var{expression-cst}@}}

The first parameter represents the angular frequency and the second
represents the phase. If the type of the current system is @code{Real},
@code{F_Sin_wt_p[]@{w,p@}} is identical to @code{Sin[w*$Time+p]}. If the
type of the current system is @code{Complex}, it is identical to
@code{Complex[Sin[p],-Cos[p]]}.

@item Period
@code{[@var{expression}]@{@var{expression-cst}@}}

@code{Fmod[@var{expression},@var{expression-cst}]}
@code{+}
@code{(@var{expression}<0 ? @var{expression-cst} : 0)};
the result is always in [0,@var{expression-cst}[.

@item Interval
@code{[@var{expression},@var{expression},@var{expression}]@{@var{expression-cst},
@var{expression-cst},@var{expression-cst}@}}

Not documented yet.

@end ftable

@c .........................................................................
@c Green functions
@c .........................................................................

@node Green functions, Type manipulation functions, Extended math functions, Types for Function
@subsection Green functions

@vindex @var{green-function-id}

The Green functions are only used in integral quantities
(@pxref{Formulation}). The first parameter represents the dimension of the
problem:
@itemize @bullet
@item @code{1D}:
@code{r = Fabs[$X-$XS]}
@item @code{2D}:
@code{r = Sqrt[($X-$XS)^2+($Y-$YS)^2]}
@item @code{3D}:
@code{r = Sqrt[($X-$XS)^2+($Y-$YS)^2+($Z-$ZS)^2]}
@end itemize
The triplets of values given in the definitions below correspond to the
@code{1D}, @code{2D} and @code{3D} cases.

@noindent
@var{green-function-id}:
@ftable @code

@item Laplace
@code{[]@{@var{expression-cst}@}}

@code{r/2}, @code{1/(2*Pi)*ln(1/r)}, @code{1/(4*Pi*r)}.

@item GradLaplace
@code{[]@{@var{expression-cst}@}}

Gradient of @code{Laplace} relative to the destination point (@code{$X},
@code{$Y}, @code{$Z}).

@item Helmholtz
@code{[]@{@var{expression-cst}, @var{expression-cst}@}}

@code{exp(j*k0*r)/(4*Pi*r)}, where @code{k0} is given by the second parameter.

@item GradHelmholtz
@code{[]@{@var{expression-cst}, @var{expression-cst}@}}

Gradient of @code{Helmholtz} relative to the destination point (@code{$X},
@code{$Y}, @code{$Z}).

@end ftable


@c .........................................................................
@c Type
@c .........................................................................

@node Type manipulation functions, Coordinate functions, Green functions, Types for Function
@subsection Type manipulation functions

@vindex @var{type-function-id}

@noindent
@var{type-function-id}:
@ftable @code

@item Complex
@code{[@var{expression-list}]}

Creates a (multi-harmonic) complex expression from an number of
real-valued expressions. The number of expressions in @var{expression-list}
must be even.

@item Complex_MH
@code{[@var{expression-list}]@{@var{expression-cst-list}@}}

Not documented yet.

@item Re
@code{[@var{expression}]}

Takes the real part of a complex-valued expression.

@item Im
@code{[@var{expression}]}

Takes the imaginary part of a complex-valued expression.

@item Conj
@code{[@var{expression}]}

Computes the conjugate of a complex-valued expression.

@item Cart2Pol
@code{[@var{expression}]}

Converts the cartesian form (reale, imaginary) of a complex-valued expression
into polar form (amplitude, phase [radians]).

@item Vector
@code{[@var{expression},@var{expression},@var{expression}]}

Creates a vector from 3 scalars.

@item Tensor
@code{[@var{expression},@var{expression},@var{expression},@var{expression},@var{expression},@var{expression},}

@code{@var{expression},@var{expression},@var{expression}]}

Creates a second-rank tensor of order 3 from 9 scalars, by row:
@smallexample
@group
    [ scalar0 scalar1 scalar2 ]   [ CompXX CompXY CompXZ ]
T = [ scalar3 scalar4 scalar5 ] = [ CompYX CompYY CompYZ ]
    [ scalar6 scalar7 scalar8 ]   [ CompZX CompZY CompZZ ]
@end group
@end smallexample

@item TensorV
@code{[@var{expression},@var{expression},@var{expression}]}

Creates a second-rank tensor of order 3 from 3 row vectors:
@smallexample
@group
    [ vector0 ]
T = [ vector1 ]
    [ vector2 ]
@end group
@end smallexample

@item TensorSym
@code{[@var{expression},@var{expression},@var{expression},@var{expression},@var{expression},@var{expression}]}

Creates a symmetrical second-rank tensor of order 3 from 6 scalars.

@item TensorDiag
@code{[@var{expression},@var{expression},@var{expression}]}

Creates a diagonal second-rank tensor of order 3 from 3 scalars.

@item SquDyadicProduct
@code{[@var{expression}]}

Dyadic product of the vector given by @var{expression} with itself.

@item CompX
@code{[@var{expression}]}

Gets the X component of a vector.

@item CompY
@code{[@var{expression}]}

Gets the Y component of a vector.

@item CompZ
@code{[@var{expression}]}

Gets the Z component of a vector.

@item CompXX
@code{[@var{expression}]}

Gets the XX component of a tensor.

@item CompXY
@code{[@var{expression}]}

Gets the XY component of a tensor.

@item CompXZ
@code{[@var{expression}]}

Gets the XZ component of a tensor.

@item CompYX
@code{[@var{expression}]}

Gets the YX component of a tensor.

@item CompYY
@code{[@var{expression}]}

Gets the YY component of a tensor.

@item CompYZ
@code{[@var{expression}]}

Gets the YZ component of a tensor.

@item CompZX
@code{[@var{expression}]}

Gets the ZX component of a tensor.

@item CompZY
@code{[@var{expression}]}

Gets the ZY component of a tensor.

@item CompZZ
@code{[@var{expression}]}

Gets the ZZ component of a tensor.

@item Cart2Sph
@code{[@var{expression}]}

Gets the tensor for transformation of vector from cartesian to spherical coordinates.

@item Cart2Cyl
@code{[@var{expression}]}

Gets the tensor for transformation of vector from cartesian to cylindric coordinates.
E.g. to convert a vector with (x,y,z)-components to one with (radial, tangential, axial)-components:
Cart2Cyl[XYZ[]] * vector

@item UnitVectorX
@code{[]}

Creates a unit vector in x-direction.

@item UnitVectorY
@code{[]}

Creates a unit vector in y-direction.

@item UnitVectorZ
@code{[]}

Creates a unit vector in z-direction.

@end ftable


@c .........................................................................
@c Coord
@c .........................................................................

@node Coordinate functions, Miscellaneous functions, Type manipulation functions, Types for Function
@subsection Coordinate functions

@vindex @var{coord-function-id}


@noindent
@var{coord-function-id}:
@ftable @code

@item X
@code{[]}

Gets the X coordinate.

@item Y
@code{[]}

Gets the Y coordinate.

@item Z
@code{[]}

Gets the Z coordinate.

@item XYZ
@code{[]}

Gets X, Y and Z in a vector.

@c todo:

@c @item F_aX_bY_cZ
@c @code{[]@{@var{expression-cst},@var{expression-cst},@var{expression-cst}@}}

@c @item F_aX21_bY21_cZ21
@c @code{[]@{@var{expression-cst},@var{expression-cst},@var{expression-cst}@}}

@end ftable


@c .........................................................................
@c Misc
@c .........................................................................

@node Miscellaneous functions,  , Coordinate functions, Types for Function
@subsection Miscellaneous functions

@vindex @var{misc-function-id}

@noindent
@var{misc-function-id}:
@ftable @code

@item Printf
@code{[@var{expression}]}

Prints the value of @var{expression} when evaluated. (@code{MPI_Printf}
can be use instead, to print the message for all MPI ranks.)

@item Rand
@code{[@var{expression}]}

Returns a pseudo-random number in [0, @var{expression}].

@item Normal
@code{[]}

Computes the normal to the element.

@item NormalSource
@code{[]}

Computes the normal to the source element (only valid in a quantity of
Integral type).

@item Tangent
@code{[]}

Computes the tangent to the element (only valid for line elements).

@item TangentSource
@code{[]}

Computes the tangent to the source element (only valid in a quantity of
Integral type and only for line elements).

@item ElementVol
@code{[]}

Computes the element's volume.

@item SurfaceArea
@code{[]@{@var{expression-cst-list}@}}

Computes the area of the physical surfaces in @var{expression-cst-list}
or of the actual surface if @var{expression-cst-list} is empty.

@item GetVolume
@code{[]}

Computes the volume of the actual physical group.

@item CompElementNum
@code{[]}

Returns 0 if the current element and the current source element are
identical.

@item GetNumElements
@code{[]@{@var{expression-cst-list}@}}

Counts the elements of physical numbers in @var{expression-cst-list}
or of the actual region if @var{expression-cst-list} is empty.

@item ElementNum
@code{[]}

Returns the tag (number) of the current element.

@item QuadraturePointIndex
@code{[]}

Returns the index of the current quadrature point.

@item AtIndex
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Returns the i-th entry of @var{expression-cst-list}. This can be used to
get an element in a list, using an index that is computed at runtime.

@item InterpolationLinear
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Linear interpolation of points. The number of constant expressions in
@var{expression-cst-list} must be even.

@item dInterpolationLinear
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Derivative of linear interpolation of points. The number of constant
expressions in @var{expression-cst-list} must be even.

@item InterpolationBilinear
@code{[@var{expression},@var{expression}]@{@var{expression-cst-list}@}}

Bilinear interpolation of a table based on two variables.
@c FIXME See @url{https://onelab.info/trac/getdp/wiki/UsageOfTables} for an example.

@item dInterpolationBilinear
@code{[@var{expression},@var{expression}]@{@var{expression-cst-list}@}}

Derivative of bilinear interpolation of a table based on two variables.
The result is a vector.
@c FIXME See @url{https://onelab.info/trac/getdp/wiki/UsageOfTables} for an example.

@item InterpolationAkima
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Akima interpolation of points. The number of constant expressions in
@var{expression-cst-list} must be even.

@item dInterpolationAkima
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Derivative of Akima interpolation of points. The number of constant
expressions in @var{expression-cst-list} must be even.

@item Order
@code{[@var{quantity}]}

Returns the interpolation order of the @var{quantity}.

@item Field
@code{[@var{expression}]}

Evaluate the last one of the fields (``views'') loaded with
@code{GmshRead} (@pxref{Types for Resolution}), at the point
@var{expression}. Common usage is thus @code{Field[XYZ[]]}.

@item Field
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Idem, but evaluate all the fields corresponding to the tags in the list,
and sum all the values. A field having no value at the given position
does not produce an error: its contribution to the sum is simply zero.

@item ScalarField
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Idem, but consider only real-valued scalar fields. A second optional
argument is the value of the time step. A third optional argument is a
boolean flag to indicate that the interpolation should be performed (if
possible) in the same element as the current element.

@item VectorField
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Idem, but consider only real-valued vector fields. Optional arguments
are treated in the same way as for @code{ScalarField}.

@item TensorField
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Idem, but consider only real-valued tensor fields. Optional arguments
are treated in the same way as for @code{ScalarField}.

@item ComplexScalarField
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Idem, but consider only complex-valued scalar fields. Optional arguments
are treated in the same way as for @code{ScalarField}.

@item ComplexVectorField
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Idem, but consider only complex-valued vector fields. Optional arguments
are treated in the same way as for @code{ScalarField}.

@item ComplexTensorField
@code{[@var{expression}]@{@var{expression-cst-list}@}}

Idem, but consider only complex-valued tensor fields. Optional arguments
are treated in the same way as for @code{ScalarField}.

@item Distance
@code{[@var{expression}]@{@var{expression-cst}@}}

Evaluate the distance between the point (whose x, y, z coordinates are
given as a vector argument) and a vector valued view, interpreted as a
displacement field (i.e. compute the minimal distance between the point
and the deformed mesh in the view).

@item GetCpuTime
@code{[]}

Returns current CPU time, in seconds (total amount of time spent
executing in user mode since GetDP was started).

@item GetWallClockTime
@code{[]}

Returns the current wall clock time, in seconds (total wall clock time
since GetDP was started).

@item GetMemory
@code{[]}

Returns the current memory usage, in megabytes (maximum resident set
size).

@item SetNumberRunTime
@code{[@var{expression}]@{@var{char-expression}@}}

Sets the @var{char-expression} ONELAB variable at run-time to
@var{expression}.

@item SetNumberRunTimeWithChoices
@code{[@var{expression}]@{@var{char-expression}@}}

Same as @code{SetNumberRunTime}, but adds the value to the choices of
the ONELAB variable (i.e. in the same way as @code{SendToServer} in
@code{PostOperation}, which are used for plotting the history of the
variable).

@item GetNumberRunTime
@code{[ <@var{expression}> ]@{@var{char-expression}@}}

Gets the value of the @var{char-expression} ONELAB variable at
run-time. If the optional @var{expression} is provided, it is used as a
default value if ONELAB is not available.

@item SetVariable
@code{[ @var{expression} <,@dots{}> ]@{ $@var{variable-id} @}}

Sets the value of the runtime variable @code{$@var{variable-id}} to the
value of the first @var{expression}, and returns this value. If
optional @var{expression}s are provided, they are appended to the
variable name, separated by @code{_}.

@item GetVariable
@code{[ <@var{expression}> <,@dots{}> ]@{ $@var{variable-id} @}}

Gets the value of the runtime variable @code{$@var{variable-id}}. If
the optional @var{expression}s are provided, they are appended to the
variable name, separated by @code{_}.

@item ValueFromIndex
@code{[ ]@{ @var{expression-cst-list} @}}

Treats @var{expression-cst-list} as a map of (@var{entity}, @var{value})
pairs. Useful to specify nodal or element-wise constraints, where
@var{entity} is the node (mesh vertex) or element number (tag).

@item VectorFromIndex
@code{[ ]@{ @var{expression-cst-list} @}}

Same @code{ValueFromIndex}, but with 3 scalar values per @var{entity}.

@item ValueFromTable
@code{[ @var{expression} ]@{ @var{char-expression} @}}

Accesses the map @var{char-expression} created by a @code{NodeTable} or
@code{ElementTable} @code{PostOperation}. If the map is not available
(e.g. in pre-processing), or if the entity is not found in the map, use
@var{expression} as default value. Useful to specify nodal or
element-wise constraints, where @var{entity} is the node (mesh vertex)
or element number (tag).

@end ftable

@c -------------------------------------------------------------------------
@c Constraint
@c -------------------------------------------------------------------------

@node Types for Constraint, Types for FunctionSpace, Types for Function, Types for objects
@section Types for @code{Constraint}

@cindex Constraint, types

@vindex @var{constraint-type}

@noindent
@var{constraint-type}:
@ftable @code

@item Assign
To assign a value (e.g., for boundary condition).

@item Init
To give an initial value (e.g., initial value in a time domain
analysis). If two values are provided (with @code{Value [
@var{expression}, @var{expression} ]}), the first value can be used
using the @code{InitSolution1} operation. This is mainly useful for the
Newmark time-stepping scheme.

@item AssignFromResolution
To assign a value to be computed by a pre-resolution.

@item InitFromResolution
To give an initial value to be computed by a pre-resolution.

@item Network
To describe the node connections of branches in a network.

@item Link
To define links between degrees of freedom in the constrained region with
degrees of freedom in a ``reference'' region, with some coefficient. For
example, to link the degrees of freedom in the contrained region @code{Left}
with the degrees of freedom in the reference region @code{Right}, located Pi
units to the right of the region @code{Left} along the X-axis, with the
coeficient @code{-1}, one could write:

@example
@{ Name periodic;
  Case @{
    @{ Region Left; Type Link ; RegionRef Right;
      Coefficient -1; Function Vector[X[]+Pi, Y[], Z[]] ;
      < FunctionRef XYZ[]; >
    @}
  @}
@}
@end example

In this example, @code{Function} defines the mapping that translates the
geometrical elements in the region @code{Left} by Pi units along the
X-axis, so that they correspond with the elements in the reference
region @code{Right}. For this mapping to work, the meshes of @code{Left}
and @code{Right} must be identical. (The optional @code{FunctionRef}
function allows to transform the reference region, useful e.g. to avoid
generating overlapping meshes for rotational links.)

@item LinkCplx
To define complex-valued links between degrees of freedom. The syntax is the
same as for constraints of type @code{Link}, but @code{Coeficient} can be
complex.

@end ftable

@c -------------------------------------------------------------------------
@c FunctionSpace
@c -------------------------------------------------------------------------

@node Types for FunctionSpace, Types for Jacobian, Types for Constraint, Types for objects
@section Types for @code{FunctionSpace}

@cindex Function space, types

@vindex @var{function-space-type}
@vindex @var{basis-function-type}
@vindex @var{global-quantity-type}

@noindent
@var{function-space-type}:
@ftable @code

@item Form0
0-form, i.e., scalar field of potential type.

@item Form1
1-form, i.e., curl-conform field (associated with a curl).

@item Form2
2-form, i.e., div-conform field (associated with a divergence).

@item Form3
3-form, i.e., scalar field of density type.

@item Form1P
1-form perpendicular to the @var{z}=0 plane, i.e., perpendicular
curl-conform field (associated with a curl).

@item Form2P
2-form in the @var{z}=0 plane, i.e., parallel div-conform field
(associated with a divergence).

@item Scalar
Scalar field.

@item Vector
Vector field.

@end ftable


@noindent
@var{basis-function-type}:
@ftable @code

@item BF_Node
Nodal function (on @code{NodesOf}, value @code{Form0}).

@item BF_Edge
Edge function (on @code{EdgesOf}, value @code{Form1}).

@item BF_Facet
Facet function (on @code{FacetsOf}, value @code{Form2}).

@item BF_Volume
Volume function (on @code{VolumesOf}, value @code{Form3}).

@item BF_GradNode
Gradient of nodal function
(on @code{NodesOf}, value @code{Form1}).

@item BF_CurlEdge
Curl of edge function
(on @code{EdgesOf}, value @code{Form2}).

@item BF_DivFacet
Divergence of facet function
(on @code{FacetsOf}, value @code{Form3}).

@item BF_GroupOfNodes
Sum of nodal functions
(on @code{GroupsOfNodesOf}, value @code{Form0}).

@item BF_GradGroupOfNodes
Gradient of sum of nodal functions
(on @code{GroupsOfNodesOf}, value @code{Form1}).

@item BF_GroupOfEdges
Sum of edge functions
(on @code{GroupsOfEdgesOf}, value @code{Form1}).

@item BF_CurlGroupOfEdges
Curl of sum of edge functions
(on @code{GroupsOfEdgesOf}, value @code{Form2}).

@item BF_PerpendicularEdge
1-form (0, 0, @code{BF_Node}) (on @code{NodesOf}, value @code{Form1P}).

@item BF_CurlPerpendicularEdge
Curl of 1-form (0, 0, @code{BF_Node}) (on @code{NodesOf}, value @code{Form2P}).

@item BF_GroupOfPerpendicularEdge
Sum of 1-forms (0, 0, @code{BF_Node}) (on @code{NodesOf}, value @code{Form1P}).

@item BF_CurlGroupOfPerpendicularEdge
Curl of sum of 1-forms (0, 0, @code{BF_Node}) (on @code{NodesOf},
value @code{Form2P}).

@item BF_PerpendicularFacet
2-form (90 degree rotation of @code{BF_Edge})
(on @code{EdgesOf}, value @code{Form2P}).

@item BF_DivPerpendicularFacet
Div of 2-form (90 degree rotation of @code{BF_Edge})
(on @code{EdgesOf}, value @code{Form3}).

@item BF_Region
Unit value 1 (on @code{Region} or @code{GroupOfRegionsOf}, value @code{Scalar}).

@item BF_RegionX
Unit vector (1, 0, 0) (on @code{Region}, value @code{Vector}).

@item BF_RegionY
Unit vector (0, 1, 0) (on @code{Region}, value @code{Vector}).

@item BF_RegionZ
Unit vector (0, 0, 1) (on @code{Region}, value @code{Vector}).

@item BF_Global
Global pre-computed quantity
(on @code{Global}, value depends on parameters).

@item BF_dGlobal
Exterior derivative of global pre-computed quantity
(on @code{Global}, value depends on parameters).

@item BF_NodeX
Vector (@code{BF_Node}, 0, 0)
(on @code{NodesOf}, value @code{Vector}).

@item BF_NodeY
Vector (0, @code{BF_Node}, 0)
(on @code{NodesOf}, value @code{Vector}).

@item BF_NodeZ
Vector (0, 0, @code{BF_Node})
(on @code{NodesOf}, value @code{Vector}).

@item BF_Zero
Zero value 0 (on all regions, value @code{Scalar}).

@item BF_One
Unit value 1 (on all regions, value @code{Scalar}).

@end ftable


@noindent
@var{global-quantity-type}:
@ftable @code

@item AliasOf
Another name for a name of coefficient of basis function.

@item AssociatedWith
A global quantity associated with a name of coefficient of basis function,
and therefore with this basis function.

@end ftable


@c -------------------------------------------------------------------------
@c Jacobian
@c -------------------------------------------------------------------------

@node Types for Jacobian, Types for Integration, Types for FunctionSpace, Types for objects
@section Types for @code{Jacobian}

@cindex Jacobian, types

@vindex @var{jacobian-type}

@noindent
@var{jacobian-type}:
@ftable @code

@item Vol
Volume Jacobian, for @var{n}-D regions in @var{n}-D geometries,
@var{n} = 1, 2 or 3.

@item Sur
Surface Jacobian, for (@var{n}-1)-D regions in @var{n}-D geometries,
@var{n} = 1, 2 or 3.

@item Lin
Line Jacobian, for (@var{n}-2)-D regions in @var{n}-D geometries,
@var{n} = 2 or 3.


@item VolAxi
Axisymmetrical volume Jacobian (1st type: @math{r}),
for 2-D regions in axisymmetrical geometries.

@item SurAxi
Axisymmetrical surface Jacobian (1st type: @math{r}),
for 1-D regions in axisymmetrical geometries.


@item VolAxiSqu
Axisymmetrical volume Jacobian (2nd type: @math{r^2}),
for 2-D regions in axisymmetrical geometries.


@item VolSphShell
Volume Jacobian with spherical shell transformation,
for @var{n}-D regions in @var{n}-D geometries, @var{n} = 2 or 3.

@i{Parameters}: @var{radius-internal}, @var{radius-external}
               <, @var{center-X}, @var{center-Y}, @var{center-Z},
                  @var{power}, @var{1/infinity} >.

@item VolCylShell
Volume Jacobian with cylindrical shell transformation, for @var{n}-D
regions in @var{n}-D geometries, @var{n} = 2 or 3. For @var{n}=2,
@code{VolCylShell} is identical to @code{VolSphShell}. For @var{n}=3,
the axis of the cylinder is supposed to be along the @var{z} axis.

@i{Parameters}: @var{radius-internal}, @var{radius-external}
               <, @var{center-X}, @var{center-Y}, @var{center-Z},
                  @var{power}, @var{1/infinity} >.

@item VolAxiSphShell
Same as @code{VolAxi}, but with spherical shell transformation.

@i{Parameters}: @var{radius-internal}, @var{radius-external}
               <, @var{center-X}, @var{center-Y}, @var{center-Z},
                  @var{power}, @var{1/infinity} >.

@item VolAxiSquSphShell
Same as @code{VolAxiSqu}, but with spherical shell transformation.

@i{Parameters}: @var{radius-internal}, @var{radius-external}
               <, @var{center-X}, @var{center-Y}, @var{center-Z},
                  @var{power}, @var{1/infinity} >.


@item VolRectShell
Volume Jacobian with rectangular shell transformation,
for @var{n}-D regions in @var{n}-D geometries, @var{n} = 2 or 3.

@i{Parameters}: @var{radius-internal}, @var{radius-external}
               <, @var{direction},
                  @var{center-X}, @var{center-Y}, @var{center-Z},
                  @var{power}, @var{1/infinity} >.

@item VolAxiRectShell
Same as @code{VolAxi}, but with rectangular shell transformation.

@i{Parameters}: @var{radius-internal}, @var{radius-external}
               <, @var{direction},
                  @var{center-X}, @var{center-Y}, @var{center-Z},
                  @var{power}, @var{1/infinity} >.

@item VolAxiSquRectShell
Same as @code{VolAxiSqu}, but with rectangular shell transformation.

@i{Parameters}: @var{radius-internal}, @var{radius-external}
               <, @var{direction},
                  @var{center-X}, @var{center-Y}, @var{center-Z},
                  @var{power}, @var{1/infinity} >.

@end ftable


@c -------------------------------------------------------------------------
@c Integration
@c -------------------------------------------------------------------------

@node Types for Integration, Types for Formulation, Types for Jacobian, Types for objects
@section Types for @code{Integration}

@cindex Integration, types

@vindex @var{integration-type}
@vindex @var{element-type}

@noindent
@var{integration-type}:
@ftable @code

@item Gauss
Numerical Gauss integration.

@item GaussLegendre
Numerical Gauss integration obtained by application of a multiplicative rule
on the one-dimensional Gauss integration.

@end ftable


@noindent
@var{element-type}:
@ftable @code

@item Line
Line (2 nodes, 1 edge, 1 volume) (#1).

@item Triangle
Triangle (3 nodes, 3 edges, 1 facet, 1 volume) (#2).

@item Quadrangle
Quadrangle (4 nodes, 4 edges, 1 facet, 1 volume) (#3).

@item Tetrahedron
Tetrahedron (4 nodes, 6 edges, 4 facets, 1 volume) (#4).

@item Hexahedron
Hexahedron (8 nodes, 12 edges, 6 facets, 1 volume) (#5).

@item Prism
Prism (6 nodes, 9 edges, 5 facets, 1 volume) (#6).

@item Pyramid
Pyramid (5 nodes, 8 edges, 5 facets, 1 volume) (#7).

@item Point
Point (1 node) (#15).

@end ftable

@noindent Note:
@enumerate
@item
@var{n} in (#@var{n}) is the type number of the element
(@pxref{Input file format}).
@end enumerate


@c -------------------------------------------------------------------------
@c Formulation
@c -------------------------------------------------------------------------

@node Types for Formulation, Types for Resolution, Types for Integration, Types for objects
@section Types for @code{Formulation}

@cindex Formulation, types

@vindex @var{formulation-type}
@vindex @var{local-term-type}
@vindex @var{quantity-type}
@vindex @var{term-op-type}


@noindent
@var{formulation-type}:
@ftable @code

@item FemEquation
Finite element method formulation (all methods of moments, integral methods).

@end ftable


@noindent
@var{local-term-type}:
@ftable @code

@item Integral
Integral of Galerkin or Petrov-Galerkin type.

@item deRham
deRham projection (collocation).

@end ftable

@noindent
@var{quantity-type}:
@ftable @code

@item Local
Local quantity defining a field in a function space.  In case a subspace is
considered, its identifier has to be given between the brackets following
the @code{NameOfSpace @var{function-space-id}}.

@item Global
Global quantity defining a global quantity from a function space.  The
identifier of this quantity has to be given between the brackets following
the @code{NameOfSpace @var{function-space-id}}.

@item Integral
Integral quantity obtained by the integration of a
@code{LocalQuantity} before its use in an @code{Equation} term.

@end ftable


@noindent
@var{term-op-type}:
@ftable @code

@item Dt
Time derivative applied to the whole term of the equation. (Not
implemented yet.)

@item DtDof
Time derivative applied only to the @code{Dof@{@}} term of the equation.

@item DtDt
Time derivative of 2nd order applied to the whole term of the
equation. (Not implemented yet.)

@item DtDtDof
Time derivative of 2nd order applied only to the @code{Dof@{@}} term of the
equation.

@item Eig
The term is multiplied by (a certain function of) the eigenvalue.  This
is to be used with the @code{GenerateSeparate} and @code{EigenSolve}
@code{Resolution} operations. An optional @code{Order @var{expression};}
or @code{Rational @var{expression};} statement can be added in the term
to specify the eigenvalue function. Full documentation of this feature
is not available yet.

@item JacNL
Nonlinear part of the Jacobian matrix (tangent stiffness matrix) to be
assembled for nonlinear analysis.

@item DtDofJacNL
Nonlinear part of the Jacobian matrix for the first order time
derivative (tangent mass matrix) to be assembled for nonlinear analysis.

@item NeverDt
No time scheme applied to the term (e.g., Theta is always 1 even if a
theta scheme is applied).

@end ftable




@c -------------------------------------------------------------------------
@c Resolution
@c -------------------------------------------------------------------------

@node Types for Resolution, Types for PostProcessing, Types for Formulation, Types for objects
@section Types for @code{Resolution}

@cindex Resolution, types

@vindex @var{resolution-op}

@noindent
@var{resolution-op}:
@ftable @code

@item Generate
@code{[@var{system-id}]}

Generate the system of equations @var{system-id}.

@item Solve
@code{[@var{system-id}]}

Solve the system of equations @var{system-id}.

@item SolveAgain
@code{[@var{system-id}]}

Save as @code{Solve}, but reuses the preconditionner when called
multiple times.

@item SetGlobalSolverOptions
@code{[@var{char-expression}]}

Set global PETSc solver options (with the same syntax as PETSc options
specified on the command line, e.g. @code{"-ksp_type gmres -pc_type ilu"}).

@item GenerateJac
@code{[@var{system-id}]}

Generate the system of equations @var{system-id} using a jacobian matrix (of
which the unknowns are corrections @var{dx} of the current solution
@var{x}).

@c FIXME: explain this better

@item SolveJac
@code{[@var{system-id}]}

Solve the system of equations @var{system-id} using a jacobian matrix (of
which the unknowns are corrections @var{dx} of the current solution
@var{x}). Then, Increment the solution (@var{x}=@var{x}+@var{dx}) and
compute the relative error @var{dx}/@var{x}.

@c FIXME: explain this better, using equations. Write out explicitly the
@c formulas when there is a JacNL term, and when there isn't
@c
@c (A(x) + JacNL(x)) dx = b(x) - A(x) x ;
@c x <- x + dx

@item GenerateSeparate
@code{[@var{system-id}]}

Generate matrices separately for @code{DtDtDof}, @code{DtDof} and
@code{NoDt} terms in @var{system-id}. The separate matrices can be used
with the @code{Update} operation (for efficient time domain analysis of
linear PDEs with constant coefficients), or with the @code{EigenSolve}
operation (for solving generalized eigenvalue problems).

@item GenerateOnly
@code{[@var{system-id}, @var{expression-cst-list}]}

Not documented yet.

@item GenerateOnlyJac
@code{[@var{system-id}, @var{expression-cst-list}]}

Not documented yet.

@item GenerateGroup

Not documented yet.

@item GenerateRightHandSideGroup

Not documented yet.

@item Update
@code{[@var{system-id}]}

Update the system of equations @var{system-id} (built from sub-matrices
generated separately with @code{GenerateSeparate}) with the
@code{TimeFunction}(s) provided in @code{Assign} constraints. This
assumes that the problem is linear, that the matrix coefficients are
independent of time, and that all sources are imposed using
@code{Assign} constraints.

@item Update
@code{[@var{system-id}, @var{expression}]}

Update the system of equations @var{system-id} (built from sub-matrices
generated separately with @code{GenerateSeparate}) with
@var{expression}. This assumes that the problem is linear, that the
matrix coefficients are independent of time, and that the
right-hand-side of the linear system can simply be multiplied by
@var{expression} at each step.

@item UpdateConstraint
@code{[@var{system-id}, @var{group-id}, @var{constraint-type}]}

Recompute the constraint of type @var{constraint-type} acting on
@var{group-id} during processing.

@item GetResidual
@code{[@var{system-id}, $@var{variable-id}]}

Compute the residual @code{r = b - A x} and store its L2 norm in the
run-time variable $@var{variable-id}.

@item GetNormSolution | GetNormRightHandSide | GetNormResidual | GetNormIncrement
@code{[@var{system-id}, $@var{variable-id}]}

Compute the norm of the solution (resp. right-hand-side, residual or
increment) and store its L2 norm in the run-time variable
$@var{variable-id}.

@item SwapSolutionAndResidual
@code{[@var{system-id}]}

Swap the solution @code{x} and residual @code{r} vectors.

@item SwapSolutionAndRightHandSide
@code{[@var{system-id}]}

Swap the solution @code{x} and right-hand-side @code{b} vectors.

@item InitSolution
@code{[@var{system-id}]}

Creates a new solution vector, adds it to the solution vector list for
@var{system-id}, and initializes the solution. The values in the vector
are initialized to the values given in a @code{Constraint} of
@code{Init} type (if two values are given in @code{Init}, the second
value is used). If no constraint is provided, the values are initialized
to zero if the solution vector is the first in the solution list;
otherwise the values are initialized using the previous solution in the
list.

@item InitSolution1
@code{[@var{system-id}]}

Same as @code{InitSolution}, but uses the first value given in the
@code{Init} constraints.

@item CreateSolution
@code{[@var{system-id}]}

Creates a new solution vector, adds it to the solution vector list for
@var{system-id}, and initializes the solution to zero.

@item CreateSolution
@code{[@var{system-id}, @var{expression-cst}]}

Same as @code{CreateSolution}, but initialize the solution by copying
the @var{expression-cst}th solution in the solution list.

@item Apply
@code{[@var{system-id}]}

@code{x <- Ax}

@item SetSolutionAsRightHandSide
@code{[@var{system-id}]}

@code{b <- x}

@item SetRightHandSideAsSolution
@code{[@var{system-id}]}

@code{x <- b}

@item Residual
@code{[@var{system-id}]}

@code{res <- b - Ax}

@item CopySolution
@code{[@var{system-id}, @var{char-expression} | @var{constant-id}() ]}

Copy the current solution @code{x} into a vector named
@var{char-expression} or into a list named @var{constant-id}.

@item CopySolution
@code{[@var{char-expression} | @var{constant-id}(), @var{system-id}]}

Copy the vector named @var{char-expression} or the list named
@var{constant-id} into the current solution @code{x}.

@item CopyRightHandSide
@code{[@var{system-id}, @var{char-expression} | @var{constant-id}() ]}

Copy the current right-hand side @code{b} into a vector named
@var{char-expression} or into a list named @var{constant-id}.

@item CopyRightHandSide
@code{[@var{char-expression} | @var{constant-id}(), @var{system-id}]}

Copy the vector named @var{char-expression} or the list named
@var{constant-id} into the current right-hand-side @code{b}.

@item CopyResidual
@code{[@var{system-id}, @var{char-expression} | @var{constant-id}() ]}

Copy the current residual into a vector named @var{char-expression} or
into a list named @var{constant-id}.

@item CopyResidual
@code{[@var{char-expression} | @var{constant-id}(), @var{system-id}]}

Copy the vector named @var{char-expression} or the list named
@var{constant-id} into the current residual.

@item SaveSolution
@code{[@var{system-id}]}

Save the solution of the system of equations @var{system-id}.

@item SaveSolutions
@code{[@var{system-id}]}

Save all the solutions available for the system of equations
@var{system-id}. This should be used with algorithms that generate more than
one solution at once, e.g., @code{EigenSolve} or @code{FourierTransform}.

@item RemoveLastSolution
@code{[@var{system-id}]}

Removes the last solution (i.e. associated with the last time step)
associated with system @var{system-id}.

@item TransferSolution
@code{[@var{system-id}]}

Transfer the solution of system @var{system-id}, as an @code{Assign}
constraint, to the system of equations defined with a
@code{DestinationSystem} command. This is used with the
@code{AssignFromResolution} constraint type (@pxref{Types for Constraint}).

@item Evaluate
@code{[@var{expression} <, @var{expression}>]}

Evaluate the @var{expression}(s).

@item SetTime
@code{[@var{expression}]}

Change the current time.

@item SetTimeStep
@code{[@var{expression}]}

Change the current time step number (1, 2, 3, ...)

@item SetDTime
@code{[@var{expression}]}

Change the current time step value (dt).

@item SetFrequency
@code{[@var{system-id}, @var{expression}]}

Change the frequency of system @var{system-id}.

@item SystemCommand
@code{[@var{expression-char}]}

Execute the system command given by @var{expression-char}.

@item Error
@code{[@var{expression-char}]}

Output error message @var{expression-char}.

@item Test
@code{[@var{expression}] @{ @var{resolution-op} @}}

If @var{expression} is true (nonzero), perform the operations in
@var{resolution-op}.

@item Test
@code{[@var{expression}] @{ @var{resolution-op} @} @{ @var{resolution-op} @}}

If @var{expression} is true (nonzero), perform the operations in the first
@var{resolution-op}, else perform the operations in the second
@var{resolution-op}.

@item While
@code{[@var{expression}] @{ @var{resolution-op} @}}

While @var{expression} is true (nonzero), perform the operations in
@var{resolution-op}.

@item Break
@code{[]}

Aborts an iterative loop, a time loop or a While loop.

@item Exit
@code{[]}

Exit, brutally.

@item Sleep
@code{[@var{expression}]}

Sleeps for @var{expression} seconds;

@item SetExtrapolationOrder
@code{[@var{expression-cst}]}

Chooses the extrapolation order to compute the initialization of the
solution vector in time loops. Default is 0.

@item Print
@code{[ @{ @var{expression-list} @} <, File @var{expression-char} > <, Format @var{expression-char} > ]}

Print the expressions listed in @var{expression-list}. If @code{Format}
is given, use it to format the (scalar) expressions like @code{Printf}.

@item Print
@code{[ @var{system-id} <, File @var{expression-char} > <, @{ @var{expression-cst-list} @} >}@*
@code{<, TimeStep @{ @var{expression-cst-list} @} >]}

Print the system @var{system-id}. If the @var{expression-cst-list} is given,
print only the values of the degrees of freedom given in that list.
If the @code{TimeStep} option is present, limit the printing to the selected
time steps.

@item EigenSolve
@code{[@var{system-id}, @var{expression-cst}, @var{expression-cst}, @var{expression-cst} < , @var{expression} > ]}

Eigenvalue/eigenvector computation using Arpack or SLEPc. The parameters
are: the system (which has to be generated with
@code{GenerateSeparate[]}), the number of eigenvalues/eigenvectors to
compute and the real and imaginary spectral shift (around which to look
for eigenvalues). The last optional argument allows to filter which
eigenvalue/eigenvector pairs will be saved. For example,
@code{($EigenvalueReal > 0)} would only keep pairs corresponding to
eigenvalues with a striclty positive real part.

@item Lanczos
@code{[@var{system-id}, @var{expression-cst}, @{ @var{expression-cst-list} @} , @var{expression-cst}]}

Eigenvalue/eigenvector computation using the Lanczos algorithm. The
parameters are: the system (which has to be generated with
@code{GenerateSeparate[]}), the size of the Lanczos space, the indices
of the eigenvalues/eigenvectors to store, the spectral shift. This
routine is deprecated: use @code{EigenSolve} instead.

@item FourierTransform
@code{[@var{system-id}, @var{system-id}, @{ @var{expression-cst-list} @}]}

On-the-fly (incremental) computation of a Fourier transform. The
parameters are: the (time domain) system, the destination system in
which the result of the Fourier tranform is to be saved (it should be
declared with @code{Type Complex}) and the list of frequencies to
consider. The computation is an approximation that assumes that the time
step is constant; it is not an actual Discrete Fourier Transform (the
number of samples is unknown a priori).

@item TimeLoopTheta
@code{[@var{expression-cst},@var{expression-cst},@var{expression},@var{expression-cst}]}
@code{@{ @var{resolution-op} @}}

Time loop of a theta scheme. The parameters are: the initial time, the end
time, the time step and the theta parameter (e.g., 1 for implicit
Euler, 0.5 for Crank-Nicholson).

Warning: GetDP automatically handles time-dependent constraints when
they are provided using the @code{TimeFunction} mechanism in an
@code{Assign}-type @code{Constraint} (@pxref{Constraint}). However,
GetDP cannot automatically transform general time-dependent source terms
in weak formulations (time-dependent functions written in a
@code{Integral} term). Such source terms will be correctly treated only
for implicit Euler, as the expression in the @code{Integral} term is
evaluated at the current time step. For other schemes, the source term
should be written explicitly, by splitting it in two (@code{theta f_n+1
+ (1-theta) f_n}), making use of the @code{AtAnteriorTimeStep[]} for the
second part, and specifying @code{NeverDt} in the @code{Integral} term.

@item TimeLoopNewmark
@code{[@var{expression-cst},@var{expression-cst},@var{expression},@var{expression-cst},@var{expression-cst}]}@*
@{ @var{resolution-op} @}

Time loop of a Newmark scheme. The parameters are: the initial time, the end
time, the time step, the beta and the gamma parameter.

Warning: same restrictions apply for time-dependent functions in the
weak formulations as for @code{TimeLoopTheta}.

@item TimeLoopAdaptive
@code{[@var{expression-cst},@var{expression-cst},@var{expression-cst},@var{expression-cst},
@var{expression-cst},@var{integration-method},<@var{expression-cst-list}>,@*
System @{ @{@var{system-id},@var{expression-cst},@var{expression-cst},@var{norm-type}@} ... @} |@*
PostOperation @{ @{@var{post-operation-id},@var{expression-cst},@var{expression-cst},@var{norm-type}@}
... @} ]}@*
@code{@{ @var{resolution-op} @}}@*
@code{@{ @var{resolution-op} @}}

Time loop with variable time steps. The step size is adjusted according the local
truncation error (LTE) of the specified Systems/PostOperations via a predictor-corrector
method.@*
The parameters are: start time, end time, initial time step, min. time step,
max. time step, integration method, list of breakpoints (time points to be hit).
The LTE calculation can be based on all DOFs of a system and/or on a PostOperation
result. The parameters here are: System/PostOperation for LTE assessment, relative
LTE tolerance, absolute LTE tolerance, norm-type for LTE calculation.@*
Possible choices for @var{integration-method} are: @code{Euler, Trapezoidal, Gear_2,
Gear_3, Gear_4, Gear_5, Gear_6}.
The Gear methods correspond to backward differentiation formulas of
order 2..6.@*
Possible choices for @var{norm-type}: @code{L1Norm, MeanL1Norm, L2Norm,
MeanL2Norm, LinfNorm}.@*
@code{MeanL1Norm} and @code{MeanL2Norm} correspond to @code{L1Norm} and
@code{L2Norm} divided by the number of degrees of freedom, respectively.@*
The first @var{resolution-op} is executed every time step. The second one is
only executed if the actual time step is accepted (LTE is in the specified range).
E.g. @code{SaveSolution[]} is usually placed in the 2nd @var{resolution-op}.@*
@c FIXME See @url{https://onelab.info/trac/getdp/wiki/TimeLoopAdaptive} for more details and an example.

@item IterativeLoop
@code{[@var{expression-cst},@var{expression},@var{expression-cst}<,@var{expression-cst}>]}
@{ @var{resolution-op} @}

Iterative loop for nonlinear analysis. The parameters are: the maximum
number of iterations (if no convergence), the relative error to achieve and
the relaxation factor (multiplies the iterative correction @var{dx}). The
optional parameter is a flag for testing purposes.

@item IterativeLoopN
@code{[@var{expression-cst},@var{expression},@*
System @{ @{@var{system-id},@var{expression-cst},@var{expression-cst},
@var{assessed-object} @var{norm-type}@} ... @} |@*
PostOperation @{ @{@var{post-operation-id},@var{expression-cst},@var{expression-cst},
@var{norm-type}@} ... @} ]}@*
@{ @var{resolution-op} @}

Similar to @code{IterativeLoop[]} but allows to specify in detail the
tolerances and the type of norm to be calculated for convergence assessment.@*
The parameters are: the maximum number of iterations (if no convergence),
the relaxation factor (multiplies the iterative correction @var{dx}).
The convergence assessment can be based on all DOFs of a system and/or on a
PostOperation result. The parameters here are: System/PostOperation for
convergence assessment, relative tolerance, absolute tolerance,
assessed object (only applicable for a specified system), norm-type for
error calculation.@*
Possible choices for @var{assessed-object}: @code{Solution, Residual,
RecalcResidual}. @code{Residual} assesses the residual from the last iteration
whereas @code{RecalcResidual} calculates the residual once again after each
iteration. This means that with @code{Residual} usually one extra iteration is
performed, but @code{RecalcResidual} causes higher computational effort per
iteration. Assessing the residual can only be used for Newton's method.@*
Possible choices for @var{norm-type}: @code{L1Norm, MeanL1Norm, L2Norm,
MeanL2Norm, LinfNorm}.@*
@code{MeanL1Norm} and @code{MeanL2Norm} correspond to @code{L1Norm} and
@code{L2Norm} divided by the number of degrees of freedom, respectively.@*
@c FIXME See @url{https://onelab.info/trac/getdp/wiki/IterativeLoopN} for more details and an example.

@item IterativeLinearSolver

Generic iterative linear solver. To be documented.

@item PostOperation
@code{[@var{post-operation-id}]}

Perform the specified @code{PostOperation}.

@item GmshRead
@code{[@var{expression-char}]}

When GetDP is linked with the Gmsh library, read a file using Gmsh. This
file can be in any format recognized by Gmsh. If the file contains one
or multiple post-processing fields, these fields will be evaluated using
the built-in @code{Field[]}, @code{ScalarField[]}, @code{VectorField[]},
etc., functions (@pxref{Miscellaneous functions}).

(Note that @code{GmshOpen} and @code{GmshMerge} can be used instead of
@code{GmshRead} to force Gmsh to do classical ``open'' and ``merge''
operations, instead of trying to ``be intelligent'' when reading
post-processing datasets, i.e., creating new models on the fly if
necessary.)

@item GmshRead
@code{[@var{expression-char}, @var{expression-cst}]}

Same thing as the @code{GmshRead} command above, except that the field
is forced to be stored with the given tag. The tag can be used to
retrieve the given field with the built-in @code{Field[]},
@code{ScalarField[]}, @code{VectorField[]}, etc., functions
(@pxref{Miscellaneous functions}).

@item GmshRead
@code{[@var{expression-char}, @code{$}@var{string}]}

Same as the @code{GmshRead}, but evaluates @var{expression-char} by
replacing a double precision format specifier with the value of the runtime
variable @code{$}@var{string}.

@item GmshWrite
@code{[@var{expression-char}, @var{expression-cst}]}

Writes the a Gmsh field to disk. (The format is guessed from the file extension.)

@item GmshClearAll
@code{[]}

Clears all Gmsh data (loaded with @code{GmshRead} and friends).

@item DeleteFile
@code{[@var{expression-char}]}

Delete a file.

@item RenameFile
@code{[@var{expression-char}, @var{expression-char}]}

Rename a file.

@item CreateDir | CreateDirectory
@code{[@var{expression-char}]}

Create a directory.

@item MPI_SetCommSelf
@code{[]}

Changes MPI communicator to self.

@item MPI_SetCommWorld
@code{[]}

Changes MPI communicator to world.

@item MPI_Barrier
@code{[]}

MPI barrier (blocks until all processes have reached this call).

@item MPI_BroadcastFields
@code{[ < @var{expression-list} > ]}

Broadcast all fields over MPI (except those listed in the list).

@item MPI_BroadcastVariables
@code{[]}

Broadcast all runtime variables over MPI.

@c todo:

@c @item Perturbation

@c @item ChangeOfCoordinates

@c @item SaveMesh

@c @item DeformMesh

@c @item IterativeTimeReduction
@c @{ @var{iterative-time-reduction-arg}; @}
@c
@c  Iterative reduction of time interval to delimit variations of solutions
@c  (e.g., used in types of nonlinear analyses).

@end ftable

@c  todo: Patrick, la suite est-elle comprehensible ?

@c  @noindent
@c  @var{iterative-time-reduction-arg}:
@c  @ftable @code

@c  @item NbrMaxIteration
@c  @var{expression-cst}

@c  Maximum number of iterations (if no convergence).

@c  @item DivisionCoefficient
@c  @var{expression-cst}

@c  Division coefficient of the time interval (usually 2 for dichotomy).

@c  @item Criterion
@c  @var{expression-cst}

@c  Dimension of the time interval to achieve before stopping divisions.

@c  @item Flag
@c  @var{expression-cst}

@c  Option for test. [To be explained later.]

@c  @item System
@c  @var{system-id}

@c  System containing the quantities to test.

@c  @item ChangeOfState
@c  @{ @{ @var{change-of-state-arg} @} @dots{} @}

@c  Tests to perform.

@c  @item Operation
@c  @{ < @var{resolution-op}; > @dots{} @}

@c  Operations to perform at each step.

@c  @item OperationEnd
@c  @{ < @var{resolution-op}; > @dots{} @}

@c  Operations to perform after the last iteration (when leaving the loop).

@c  @end ftable

@c  @noindent
@c  @var{change-of-state-arg}:
@c  @ftable @code

@c  @item Type
@c  @var{change-of-state-type}

@c  Type of change of state analysis.

@c  @item Quantity
@c  @var{quantity-id}
@c  @itemx In
@c  @var{group-def}

@c  Global quantity to analyse.

@c  @item Criterion
@c  @var{expression-cst}

@c  Relative error accepted.

@c  @item Function
@c  @var{expression}

@c  Reference function.

@c  @end ftable

@c  @noindent
@c  @var{change-of-state-type}:
@c  @ftable @code

@c  @item ChangeSign
@c  Test of change of sign of quantities.

@c  @item ChangeLevel
@c  Test of change of level of quantities.

@c  @item ChangeReference
@c  Compare quantities to reference functions (e.g., for regulation).

@c  @item ChangeReference2
@c  Compare quantities to reference functions (e.g., for regulation).

@c  @end ftable


@c -------------------------------------------------------------------------
@c PostProcessing
@c -------------------------------------------------------------------------

@node Types for PostProcessing, Types for PostOperation, Types for Resolution, Types for objects
@section Types for @code{PostProcessing}

@cindex Post-processing, types

@vindex @var{post-value}

@noindent
@var{post-value}:
@ftable @code

@item Local
@{ @var{local-value} @}

To compute a local quantity.

@item Integral
@{ @var{integral-value} @}

To integrate the expression over each element.

@end ftable


@c -------------------------------------------------------------------------
@c PostOperation
@c -------------------------------------------------------------------------

@node Types for PostOperation,  , Types for PostProcessing, Types for objects
@section Types for @code{PostOperation}

@cindex Post-operation, types

@vindex @var{print-support}

@noindent
@var{print-support}:
@ftable @code

@item OnElementsOf
@var{group-def}

To compute a quantity on the elements belonging to the region
@var{group-def}, where the solution was computed during the processing
stage.

@item OnRegion
@var{group-def}

To compute a global quantity associated with the region @var{group-def}.

@item OnGlobal
To compute a global integral quantity, with no associated region.

@item OnSection
@{ @{ @var{expression-cst-list} @} @{ @var{expression-cst-list} @} @{ @var{expression-cst-list} @} @}

To compute a quantity on a section of the mesh defined by three points
(i.e., on the intersection of the mesh with a cutting a plane, specified by
three points). Each @var{expression-cst-list} must contain exactly three
elements (the coordinates of the points).

@item OnGrid
@var{group-def}

To compute a quantity in elements of a mesh which differs from the real
support of the solution. @code{OnGrid @var{group-def}} differs from
@code{OnElementsOf @var{group-def}} by the reinterpolation that must be
performed.

@item OnGrid
@code{@{ @var{expression},  @var{expression},  @var{expression} @}}@*
@code{@{    @var{expression-cst-list-item} | @{ @var{expression-cst-list} @} ,}@*
@code{@: @: @var{expression-cst-list-item} | @{ @var{expression-cst-list} @} ,}@*
@code{@: @: @var{expression-cst-list-item} | @{ @var{expression-cst-list} @} @}}

To compute a quantity on a parametric grid. The three @var{expression}s
represent the three cartesian coordinates @var{x}, @var{y} and @var{z}, and
can be functions of the current values @code{$A}, @code{$B} and
@code{$C}. The values for @code{$A}, @code{$B} and @code{$C} are specified
by each @var{expression-cst-list-item} or @var{expression-cst-list}. For
example, @code{OnGrid @{Cos[$A], Sin[$A], 0@} @{ 0:2*Pi:Pi/180, 0, 0 @}} will
compute the quantity on 360 points equally distributed on a circle in the
z=0 plane, and centered on the origin.

@item OnPoint
@{ @var{expression-cst-list} @}

To compute a quantity at a point. The @var{expression-cst-list} must contain
exactly three elements (the coordinates of the point).

@item OnLine
@{ @{ @var{expression-cst-list} @} @{ @var{expression-cst-list} @} @} @{ @var{expression-cst} @}

To compute a quantity along a line (given by its two end points), with an
associated number of divisions equal to @var{expression-cst}. The
interpolation points on the line are equidistant. Each
@var{expression-cst-list} must contain exactly three elements (the
coordinates of the points).

@item OnPlane
@{ @{ @var{expression-cst-list} @} @{ @var{expression-cst-list} @} @{ @var{expression-cst-list} @} @}@*
@code{@{ @var{expression-cst}, @var{expression-cst} @}}

To compute a quantity on a plane (specified by three points), with an
associated number of divisions equal to each @var{expression-cst} along both
generating directions. Each @var{expression-cst-list} must contain exactly
three elements (the coordinates of the points).

@item OnBox
@{ @{ @var{expression-cst-list} @} @{ @var{expression-cst-list} @} @{ @var{expression-cst-list} @}@*
@code{@: @: @{ @var{expression-cst-list} @} @} @{ @var{expression-cst}, @var{expression-cst}, @var{expression-cst} @}}

To compute a quantity in a box (specified by four points), with an
associated number of divisions equal to each @var{expression-cst} along the
three generating directions. Each @var{expression-cst-list} must contain
exactly three elements (the coordinates of the points).

@c todo: OnRegion WithArgument
@c Il faudrait en fait plutot ajouter WithArgument comme une option
@c accessible partout, et retravailler le post en ce sens...
@c en tout cas, iul faut changer la syntaxe de WithArgument pour utiliser
@c uniquement une expression-cst-list, et non plus uniquement start, end, num.

@end ftable

@vindex @var{print-option}

@noindent
@var{print-option}:
@ftable @code

@item File
@code{@var{expression-char}}

Outputs the result in a file named @var{expression-char}.

@item File
@code{> @var{expression-char}}

Same as @code{File @var{expression-char}}, except that, if several @code{File >
@var{expression-char}} options appear in the same @code{PostOperation}, the results
are concatenated in the file @var{expression-char}.

@item File
@code{>> @var{expression-char}}

Appends the result to a file named @var{expression-char}.

@item AppendToExistingFile
@var{expression-cst}

Appends the result to the file specified with @code{File}. (Same
behavior as @code{>} if @var{expression-cst} = 1; same behavior as
@code{>>} if @var{expression-cst} = 2.)

@item Name | Label
@code{@var{expression-char}}

For formats that support it, sets the label of the output field to
@var{expression-char} (also used with with @code{SendToServer} to force
the label).

@item Depth
@var{expression-cst}

Recursive division of the elements if @var{expression-cst} is greater than
zero, derefinement if @var{expression-cst} is smaller than zero. If
@var{expression-cst} is equal to zero, evaluation at the barycenter of the
elements.

@item AtGaussPoints
@var{expression-cst}

Print result at the specified number of Gauss points.

@item Skin
Computes the result on the boundary of the region.

@item Smoothing
< @var{expression-cst} >

Smoothes the solution at the nodes.

@item HarmonicToTime
@var{expression-cst}

Converts a harmonic solution into a time-dependent one (with @var{expression-cst}
steps).

@item Dimension
@var{expression-cst}

Forces the dimension of the elements to consider in an element
search. Specifies the problem dimension during an adaptation (h- or
p-refinement).

@item TimeStep
@code{@var{expression-cst-list-item} | @{ @var{expression-cst-list} @}}

Outputs results for the specified time steps only.

@item TimeValue
@code{@var{expression-cst-list-item} | @{ @var{expression-cst-list} @}}

Outputs results for the specified time value(s) only.

@item TimeImagValue
@code{@var{expression-cst-list-item} | @{ @var{expression-cst-list} @}}

Outputs results for the specified imaginary time value(s) only.

@item LastTimeStepOnly

Outputs results for the last time step only (useful when calling a
@code{PostOperation} directly in a @code{Resolution}, for example).

@item AppendExpressionToFileName
@var{expression}

Evaluate the given @var{expression} at run-time and append it to the filename.

@item AppendExpressionFormat
@var{expression-char}

C-style format string for printing the @var{expression} provided in
@code{AppendExpressionToFileName}. Default is @code{"%.16g"}.

@item AppendTimeStepToFileName
< @var{expression-cst} >

Appends the time step to the output file; only makes sense with @code{LastTimeStepOnly}.

@item AppendStringToFileName
@var{expression-char}

Append the given @var{expression-char} to the filename.

@item OverrideTimeStepValue
@var{expression-cst}

Overrides the value of the current time step with the given value.

@item NoMesh
< @var{expression-cst} >

Prevents the mesh from being written in the output file (useful with new
mesh-based solution formats).

@item SendToServer
@var{expression-char}

Send the value to the Onelab server, using @var{expression-char} as the
parameter name.

@item SendToServer
@var{expression-char}  @{ @var{expression-cst-list} @}

Send the requested harmonics of the value to the Onelab server, using
@var{expression-char} as the parameter name.

@item Color
@var{expression-char}

Used with @code{SendToServer}, sets the color of the parameter in the
Onelab server.

@item Hidden
< @var{expression-cst} >

Used with @code{SendToServer}, selects the visibility of the exchanged value.

@item Closed
@var{expression-char}

Used with @code{SendToServer}, closes (or opens) the subtree containing
the parameter.

@item Units
@var{expression-char}

Used with @code{SendToServer}, sets the units of the parameter in the
Onelab server.

@item Frequency
@code{@var{expression-cst-list-item} | @{ @var{expression-cst-list} @}}

Outputs results for the specified frequencies only.

@item Format
@var{post-operation-fmt}

Outputs results in the specified format.

@item Adapt
@code{P1 | H1 | H2}

Performs p- or h-refinement on the post-processing result, considered as an
error map.

@item Target
@var{expression-cst}

Specifies the target for the optimizer during adaptation (error for
@code{P1|H1}, number of elements for @code{H2}).

@item Value
@code{@var{expression-cst-list-item} | @{ @var{expression-cst-list} @}}

Specifies acceptable output values for discrete optimization (e.g. the
available interpolation orders with @code{Adapt P1}).

@item Sort
@code{Position | Connection}

Sorts the output by position (x, y, z) or by connection (for @code{LINE}
elements only).

@item Iso
@var{expression-cst}

Outputs directly contour prints (with @var{expression-cst} values) instead of
elementary values.

@item Iso
@code{@{ @var{expression-cst-list} @}}

Outputs directly contour prints for the values specified in the
@var{expression-cst-list} instead of elementary values.

@item NoNewLine
Suppresses the new lines in the output when printing global quantities
(i.e., with @code{Print OnRegion} or @code{Print OnGlobal}).

@item ChangeOfCoordinates
@code{@{ @var{expression}, @var{expression}, @var{expression} @}}

Changes the coordinates of the results according to the three expressions
given in argument. The three @var{expression}s represent the three new
cartesian coordinates @var{x}, @var{y} and @var{z}, and can be functions of
the current values of the cartesian coordinates @code{$X}, @code{$Y} and
@code{$Z}.

@item ChangeOfValues
@code{@{ @var{expression-list} @}}

Changes the values of the results according to the expressions given in
argument. The @var{expression}s represent the new values (@var{x}-compoment,
@var{y}-component, etc.), and can be functions of the current values of the
solution (@var{$Val0}, @var{$Val1}, etc.).

@item DecomposeInSimplex

Decomposes all output elements in simplices (points, lines, triangles or
tetrahedra).

@item StoreInVariable
@code{$@var{expression-char}}

Stores the result of a point-wise evaluation or an @code{OnRegion}
post-processing operation in the run-time variable
$code[$]@var{expression-char}.

@item StoreInRegister
@code{@var{expression-cst}}

Stores the result of point-wise evaluation or an @code{OnRegion}
post-processing operation in the register @var{expression-cst}.

@item StoreMinInRegister
@item StoreMaxInRegister
@code{@var{expression-cst}}

Stores the minimum or maximum value of an @code{OnElementsOf} post-processing
operation in the register @var{expression-cst}.

@item StoreMinXinRegister
@item StoreMinYinRegister
@item StoreMinZinRegister
@item StoreMaxXinRegister
@item StoreMaxYinRegister
@item StoreMaxZinRegister
@code{@var{expression-cst}}

Stores the X, Y or Z coordinate of the location, where the minimum or maximum
of an @code{OnElementsOf} post-processing operation occurs, in the register
@var{expression-cst}.

@item StoreInField
@code{@var{expression-cst}}

Stores the result of a post-processing operation in the field (Gmsh
list-based post-processing view) with tag @var{expression-cst}.

@item StoreInMeshBasedField
@code{@var{expression-cst}}

Stores the result of a post-processing operation in the mesh-based field
(Gmsh mesh-based post-processing view) with tag @var{expression-cst}.

@item TimeLegend
@code{< @{ @var{expression}, @var{expression}, @var{expression} @} >}

Includes a time legend in Gmsh plots. If the three optional expressions
giving the position of the legend are not specified, the legend is centered
on top of the plot.

@item FrequencyLegend
@code{< @{ @var{expression}, @var{expression}, @var{expression} @} >}

Includes a frequency legend in Gmsh plots. If the three optional expressions
giving the position of the legend are not specified, the legend is centered
on top of the plot.

@item EigenvalueLegend
@code{< @{ @var{expression}, @var{expression}, @var{expression} @} >}

Includes an eigenvalue legend in Gmsh plots. If the three optional
expressions giving the position of the legend are not specified, the legend
is centered on top of the plot.

@end ftable


@vindex @var{post-operation-fmt}

@noindent
@var{post-operation-fmt}:
@ftable @code

@item Gmsh
@itemx GmshParsed
Gmsh output. See @ref{Input file format} and the documentation of Gmsh
(@url{http://gmsh.info}) for a description of the file formats.

@item Table
Space oriented column output, e.g., suitable for Gnuplot, Excel, Caleida
Graph, etc. The columns are: @var{element-type} @var{element-index}
@var{x-coord} @var{y-coord} @var{z-coord} <@var{x-coord} @var{y-coord}
@var{z-coord}> @dots{} @var{real} @var{real} @var{real} @var{values}. The
three @var{real} numbers preceding the @var{values} contain
context-dependent information, depending on the type of plot: curvilinear
abscissa for @code{OnLine} plots, normal to the plane for @code{OnPlane}
plots, parametric coordinates for parametric @code{OnGrid} plots, etc.

@item SimpleTable
Like @code{Table}, but with only the @var{x-coord} @var{y-coord}
@var{z-coord} and @var{values} columns.

@item TimeTable
Time oriented column output, e.g., suitable for Gnuplot, Excel, Caleida
Graph, etc. The columns are: @var{time-step} @var{time} @var{x-coord}
@var{y-coord} @var{z-coord} <@var{x-coord} @var{y-coord} @var{z-coord}>
@dots{} @var{value}.

@item NodeTable
Table of nodal values, in the form @var{node-number}
@var{node-value}(s). When exported to a file, the total number of nodal
values is printed first. The data is automatically exported as a
run-time accessible list as well as a ONELAB variable, with the name of
the @code{PostOperation} quantity. The values are also directly usable
by the @code{ValueFromTable} function, which allows to use them as
values in a nodal @code{Constraint}.

@item ElementTable
Table of element values, in the form @var{element-number}
@var{element-node-value}(s). When exported to a file, the total number
of element values is printed first. The data is automatically exported
as a run-time accessible list as well as a ONELAB variable, with the
name of the @code{PostOperation} quantity. The values are also directly
usable by the @code{ValueFromTable} function, which allows to use them
as values in an element-wise @code{Constraint}.

@item Gnuplot
Space oriented column output similar to the @code{Table} format, except that
a new line is created for each node of each element, with a repetition of
the first node if the number of nodes in the element is greater than 2. This
permits to draw unstructured meshes and nice three-dimensional elevation
plots in Gnuplot. The columns are: @var{element-type} @var{element-index}
@var{x-coord} @var{y-coord} @var{z-coord} @var{real} @var{real} @var{real}
@var{values}. The three @var{real} numbers preceding the @var{values}
contain context-dependent information, depending on the type of plot:
curvilinear abscissa for @code{OnLine} plots, normal to the plane for
@code{OnPlane} plots, parametric coordinates for parametric @code{OnGrid}
plots, etc.

@item Adaptation
Adaptation map, suitable for the GetDP @code{-adapt} command line option.

@end ftable


@c =========================================================================
@c Short Examples
@c =========================================================================

@node Short examples, Complete examples, Types for objects, Top
@chapter Short examples

@cindex Short examples
@cindex Examples, short

@menu
* Constant expression examples::
* Group examples::
* Function examples::
* Constraint examples::
* FunctionSpace examples::
* Jacobian examples::
* Integration examples::
* Formulation examples::
* Resolution examples::
* PostProcessing examples::
* PostOperation examples::
@end menu

@c -------------------------------------------------------------------------
@c Constant Expression Examples
@c -------------------------------------------------------------------------

@node Constant expression examples, Group examples, Short examples, Short examples
@section Constant expression examples

The simplest constant expression consists of an @var{integer} or a
@var{real} number as in

@example
21
-3
@end example

@noindent or

@example
-3.1415
27e3
-290.53e-12
@end example

@noindent
Using operators and the classic math functions, @var{constant-id}s can
be defined:

@example
c1 = Sin[2/3*3.1415] * 5000^2;
c2 = -1/c1;
@end example

@c todo: ajouter un exemple de liste et de string

@c -------------------------------------------------------------------------
@c Group Examples
@c -------------------------------------------------------------------------

@node Group examples, Function examples, Constant expression examples, Short examples
@section @code{Group} examples

@cindex Group, examples

Let us assume that some elements in the input mesh have the region numbers
1000, 2000 and 3000. In the definitions

@example
Group @{
  Air = Region[1000]; Core = Region[2000]; Inductor = Region[3000];
  NonConductingDomain = Region[@{Air, Core@}];
  ConductingDomain    = Region[@{Inductor@}];
@}
@end example

@noindent
@code{Air}, @code{Core}, @code{Inductor} are identifiers of elementary
region groups while @code{NonConductingDom@-ain} and
@code{ConductingDomain} are global region groups.

Groups of function type contain lists of entities built on the region groups
appearing in their arguments. For example,

@example
NodesOf[NonConductingDomain]
@end example

@noindent
represents the group of nodes of geometrical elements belonging to the regions
in @code{NonConduc@-tingDomain} and

@example
EdgesOf[DomainC, Not SkinDomainC]
@end example

@noindent
represents the group of edges of geometrical elements belonging to the regions
in @code{DomainC} but not to those of @code{SkinDomainC}.


@c -------------------------------------------------------------------------
@c Function Examples
@c -------------------------------------------------------------------------

@node Function examples, Constraint examples, Group examples, Short examples
@section @code{Function} examples

@cindex Function, examples

A physical characteristic is a piecewise defined function. The magnetic
permeability @code{mu[]} can for example be defined in the considered
regions by

@example
Function @{
  mu[Air] = 4.e-7*Pi;
  mu[Core] = 1000.*4.e-7*Pi;
@}
@end example

@noindent
A nonlinear characteristic can be defined through an @var{expression}
with arguments, e.g.,

@example
Function @{
  mu0 = 4.e-7*Pi;
  a1 = 1000.; b1 = 100.; // Constants
  mu[NonlinearCore] = mu0 + 1./(a1+b1*Norm[$1]^6);
@}
@end example

@noindent
where function @code{mu[]} in region @code{NonLinearCore} has one argument
@code{$1} which has to be the magnetic flux density.  This function is
actually called when writing the equations of a formulation, which permits
to directly extend it to a nonlinear form by adding only the necessary
arguments. For example, in a magnetic vector potential formulation, one may
write @code{mu[@{Curl a@}]} instead of @code{mu[]} in @code{Equation} terms
(@pxref{Formulation examples}). Multiple arguments can be specified in a
similar way: writing @code{mu[@{Curl a@},@{T@}]} in an @code{Equation} term
will provide the function @code{mu[]} with two usable arguments, @code{$1}
(the magnetic flux density) and @code{$2} (the temperature).

It is also possible to directly interpolate one-dimensional functions from
tabulated data. In the following example, the function @var{f}(@var{x}) as
well as its derivative @var{f}'(@var{x}) are interpolated from the
(@var{x},@var{f}(@var{x})) couples (0,0.65), (1,0.72), (2,0.98) and
(3,1.12):

@example
Function @{
  couples = @{0, 0.65 , 1, 0.72 , 2, 0.98 , 3, 1.12@};
  f[] = InterpolationLinear[$1]@{List[couples]@};
  dfdx[] = dInterpolationLinear[$1]@{List[couples]@};
@}
@end example

@noindent The function @code{f[]} may then be called in an @code{Equation}
term of a @code{Formulation} with one argument, @var{x}. Notice how the list
of constants @code{List[couples]} is supplied as a list of parameters to the
built-in function @code{InterpolationLinear} (@pxref{Constants}, as well as
@ref{Functions}). In order to facilitate the construction of such
interpolations, the couples can also be specified in two separate lists,
merged with the alternate list @code{ListAlt} command (@pxref{Constants}):

@example
Function @{
  data_x = @{0, 1, 2, 3@};
  data_f = @{0.65, 0.72, 0.98, 1.12@};
  f[] = InterpolationLinear[$1]@{ListAlt[data_x, data_f]@};
  dfdx[] = dInterpolationLinear[$1]@{ListAlt[data_x, data_f]@};
@}
@end example

@noindent In order to optimize the evaluation time of complex expressions,
registers may be used (@pxref{Run-time variables and registers}). For
example, the evaluation of @code{g[] = f[$1]*Sin[f[$1]^2]} would require
two (costly) linear interpolations. But the result of the evaluation of
@code{f[]} may be stored in a register (for example the register 0) with

@example
g[] = f[$1]#0 * Sin[#0^2];
@end example

@noindent thus reducing the number of evaluations of @code{f[]} (and of the
argument @code{$1}) to one.

The same results can be obtained using a run-time variable @code{$v}:
@example
g[] = ($v = f[$1]) * Sin[$v^2];
@end example

A function can also be time dependent, e.g.,

@example
Function @{
  Freq = 50.; Phase = 30./180.*Pi; // Constants
  TimeFct_Sin[] = Sin [ 2.*Pi*Freq * $Time + Phase ];
  TimeFct_Exp[] = Exp [ - $Time / 0.0119 ];
  TimeFct_ExtSin[] = Sin_wt_p [] @{2.*Pi*Freq, Phase@};
@}
@end example

@noindent
Note that @code{TimeFct_ExtSin[]} is identical to @code{TimeFct_Sin[]} in a
time domain analysis, but also permits to define phasors implicitely in the
case of harmonic analyses.

@c -------------------------------------------------------------------------
@c Constraint Examples
@c -------------------------------------------------------------------------

@node Constraint examples, FunctionSpace examples, Function examples, Short examples
@section @code{Constraint} examples

@cindex Constraint, examples

Constraints are referred to in @code{FunctionSpace}s and are usually used
for boundary conditions (@code{Assign} type).
For example, essential conditions on two surface regions,
@code{Surf0} and @code{Surf1}, will be first defined by

@example
Constraint @{
  @{ Name DirichletBoundaryCondition1; Type Assign;
    Case @{
      @{ Region Surf0; Value 0.; @}
      @{ Region Surf1; Value 1.; @}
    @}
  @}
@}
@end example

@noindent
The way the @code{Value}s are associated with @code{Region}s (with their
nodes, their edges, their global regions, @dots{}) is defined in the
@code{FunctionSpace}s which use the @code{Constraint}.  In other words, a
@code{Constraint} defines data but does not define the method to process
them. A time dependent essential boundary condition on @code{Surf1} would be
introduced as (cf.@: @ref{Function examples} for the definition of
@code{TimeFct_Exp[]}):

@example
      @{ Region Surf1; Value 1.; TimeFunction 3*TimeFct_Exp[] @}
@end example

@noindent It is important to notice that the time dependence cannot be
introduced in the @code{Value} field, since the @code{Value} is only
evaluated once during the pre-processing.

Other constraints can be referred to in @code{Formulation}s. It is the case of
those defining electrical circuit connections (@code{Network} type), e.g.,

@example
Constraint @{
  @{ Name ElectricalCircuit; Type Network;
    Case Circuit1 @{
      @{ Region VoltageSource; Branch @{1,2@}; @}
      @{ Region PrimaryCoil; Branch @{1,2@}; @}
    @}
    Case Circuit2 @{
      @{ Region SecondaryCoil; Branch @{1,2@}; @}
      @{ Region Charge; Branch @{1,2@}; @}
    @}
  @}
@}
@end example

@noindent
which defines two non-connected circuits (@code{Circuit1} and @code{Circuit2}),
with an independent numbering of nodes: region @code{VoltageSource} is connected in
parallel with region @code{PrimaryCoil}, and region @code{SecondaryCoil} is
connected in parallel with region @code{Charge}.

@c todo: ajouter un vrai exemple de circuit

@c -------------------------------------------------------------------------
@c FunctionSpace Examples
@c -------------------------------------------------------------------------

@node FunctionSpace examples, Jacobian examples, Constraint examples, Short examples
@section @code{FunctionSpace} examples

@cindex Function space, examples

Various discrete function spaces can be defined in the frame of the finite
element method.

@menu
* Conform space::
* High order space::
* Global values::
* Curl-conform space::
* Gauge condition::
* Coupled spaces::
* Multiply connected domains::
@end menu

@c .........................................................................
@c Nodal Finite Element Spaces
@c .........................................................................

@node Conform space, High order space, FunctionSpace examples, FunctionSpace examples
@subsection Nodal finite element spaces

The most elementary function space is the nodal finite element space,
defined on a mesh of a domain @var{W} and denoted @i{S0(W)}
(associated finite elements can be of various geometries),
and associated with essential boundary conditions (Dirichlet conditions).
It contains 0-forms, i.e., scalar fields of potential type:

@tex
$$ v = \sum_{n\in N} v_n s_n \quad v\in S^0(W) $$
@end tex
@ifnottex
@var{v} = Sum [ @var{vn} * @var{sn},  for all @var{n} in @var{N} ],
@var{v} in @i{S0(W)}
@end ifnottex

@noindent
where @var{N} is the set of nodes of @var{W}, @var{sn} is the nodal basis function
associated with node @var{n} and @var{vn} is the value of @var{v} at node @var{n}.
It is defined by

@example
FunctionSpace @{
  @{ Name Hgrad_v; Type Form0;
    BasisFunction @{
      @{ Name sn; NameOfCoef vn; Function BF_Node;
        Support Domain; Entity NodesOf[All]; @}
    @}
    Constraint @{
      @{ NameOfCoef vn; EntityType NodesOf;
        NameOfConstraint DirichletBoundaryCondition1; @}
    @}
  @}
@}
@end example

@noindent
Function @code{sn} is the built-in basis function BF_Node associated with
all nodes (@code{NodesOf}) in the mesh of @var{W} (@code{Domain}). Previously
defined @code{Constraint DirichletBoundaryCondition1}
(@pxref{Constraint examples}) is used as boundary condition.

In the example above, @code{Entity NodesOf[All]} is preferred to
@code{Entity NodesOf[Domain]}.
In this way, the list of all the nodes of @code{Domain} will not have to be
generated. All the nodes of each geometrical element in @code{Support Domain}
will be directly taken into account.


@c .........................................................................
@c High Order Nodal Finite Element Space
@c .........................................................................

@node High order space, Global values, Conform space, FunctionSpace examples
@subsection High order nodal finite element space

Higher order finite elements can be directly taken into account by @code{BF_Node}.
Hierarchical finite elements for 0-forms can be used by simply adding other basis
functions (associated with other geometrical entities, e.g., edges and facets) to
@code{BasisFunction}, e.g.,

@example
    @dots{}
    BasisFunction @{
      @{ Name sn; NameOfCoef vn; Function BF_Node;
        Support Domain; Entity NodesOf[All]; @}
      @{ Name s2; NameOfCoef v2; Function BF_Node_2E;
        Support Domain; Entity EdgesOf[All]; @}
    @}
    @dots{}
@end example

@c .........................................................................
@c Nodal Finite Element Space with Floating Potentials
@c .........................................................................

@node Global values, Curl-conform space, High order space, FunctionSpace examples
@subsection Nodal finite element space with floating potentials

A scalar potential with floating values @var{vf} on certain boundaries @var{Gf},
@var{f} in @var{Cf}, e.g., for electrostatic problems, can be expressed as

@tex
$$ v = \sum_{n\in N_v} v_n s_n + \sum_{f\in C_f} v_f s_f    \quad v\in S^0(W)  $$
@end tex
@ifnottex
@var{v} = Sum [ @var{vn} * @var{sn},  for all @var{n} in @var{Nv} ] + Sum [ @var{vf} * @var{sf},  for all @var{f} in @var{Cf} ],
@var{v} in @i{S0(W)}
@end ifnottex

@noindent
where @var{Nv} is the set of inner nodes of @var{W} and each function @var{sf}
is associated with the group of nodes of boundary @var{Gf}, @var{f} in @var{Cf}
(@code{SkinDomainC}); @var{sf} is the sum of the nodal basis functions
of all the nodes of @var{Cf}. Its function space is defined by

@example
FunctionSpace @{
  @{ Name Hgrad_v_floating; Type Form0;
    BasisFunction @{
      @{ Name sn; NameOfCoef vn; Function BF_Node;
        Support Domain; Entity NodesOf[All, Not SkinDomainC]; @}
      @{ Name sf; NameOfCoef vf; Function BF_GroupOfNodes;
        Support Domain; Entity GroupsOfNodesOf[SkinDomainC]; @}
    @}
    GlobalQuantity @{
      @{ Name GlobalElectricPotential; Type AliasOf; NameOfCoef vf; @}
      @{ Name GlobalElectricCharge; Type AssociatedWith;
        NameOfCoef vf; @}
    @}
    Constraint @{ @dots{} @}
  @}
@}
@end example

@noindent
Two global quantities have been associated with this space: the electric
potential @code{Global@-ElectricPotential}, being an alias of
coefficient @code{vf}, and the electric charge
@code{GlobalElec@-tricCharge}, being associated with coefficient
@code{vf}.

@c .........................................................................
@c Edge Finite Element Space
@c .........................................................................

@node Curl-conform space, Gauge condition, Global values, FunctionSpace examples
@subsection Edge finite element space

Another space is the edge finite element space, denoted @i{S1(W)},
containing 1-forms, i.e., curl-conform fields:

@tex
$$ {\bf h} = \sum_{e\in E} h_e {\bf s}_e   \quad{\bf h}\in S^1(W)  $$
@end tex
@ifnottex
@var{h} = Sum [ @var{he} * @var{se},  for all @var{e} in @var{E} ],
@var{h} in @i{S1(W)}
@end ifnottex

@noindent
where @var{E} is the set of edges of @var{W}, @var{se} is the edge basis
function for edge @var{e} and @var{he} is the circulation of @var{h} along
edge @var{e}. It is defined by

@example
FunctionSpace @{
  @{ Name Hcurl_h; Type Form1;
    BasisFunction @{
      @{ Name se; NameOfCoef he; Function BF_Edge;
        Support Domain; Entity EdgesOf[All]; @}
    @}
    Constraint @{ @dots{} @}
  @}
@}
@end example

@c .........................................................................
@c Edge Finite Element Space with Gauge Condition
@c .........................................................................

@node Gauge condition, Coupled spaces, Curl-conform space, FunctionSpace examples
@subsection Edge finite element space with gauge condition

A 1-form function space containing vector potentials can be associated
with a gauge condition, which can be defined as a constraint, e.g., a
zero value is fixed for all circulations along edges of a tree
(@code{EdgesOfTreeIn}) built in the mesh (@code{Domain}), having to be
complete on certain boundaries (@code{StartingOn Surf}):

@example
Constraint @{
  @{ Name GaugeCondition_a_Mag_3D; Type Assign;
    Case @{
      @{ Region Domain; SubRegion Surf; Value 0.; @}
    @}
  @}
@}

FunctionSpace @{
  @{ Name Hcurl_a_Gauge; Type Form1;
    BasisFunction @{
      @{ Name se; NameOfCoef ae; Function BF_Edge;
        Support Domain; Entity EdgesOf[All]; @}
    @}
    Constraint @{
      @{ NameOfCoef ae;
        EntityType EdgesOfTreeIn; EntitySubType StartingOn;
        NameOfConstraint GaugeCondition_a_Mag_3D; @}
      @dots{}
    @}
  @}
@}
@end example

@c .........................................................................
@c Coupled Edge and Nodal Finite Element Spaces
@c .........................................................................

@node Coupled spaces, Multiply connected domains, Gauge condition, FunctionSpace examples
@subsection Coupled edge and nodal finite element spaces

A 1-form function space, containing curl free fields in certain regions @var{WcC}
(@code{DomainCC}) of @var{W}, which are the complementary part of @var{Wc}
(@code{DomainC}) in @var{W}, can be explicitly characterized by


@tex
$$ {\bf h} = \sum_{k\in E_c} h_k {\bf s}_k + \sum_{n\in N_c^C} \phi_n {\bf v}_n  \quad{\bf h}\in S^1(W)  $$
@end tex
@ifnottex
@var{h} = Sum [ @var{hk} * @var{sk},  for all @var{e} in @var{Ec} ] + Sum [ @var{phin} * @var{vn},  for all @var{n} in @var{NcC} ],
@var{h} in @i{S1(W)}
@end ifnottex

@noindent
where @var{Ec} is the set of inner edges of @var{W}, @var{NcC} is the set of
nodes inside @var{WcC} and on its boundary @var{dWcC}, @var{sk} is an edge
basis function and @var{vn} is a vector nodal function. Such a space, coupling
a vector field with a scalar potential, can be defined by

@example
FunctionSpace @{
  @{ Name Hcurl_hphi; Type Form1;
    BasisFunction @{
      @{ Name sk; NameOfCoef hk; Function BF_Edge;
        Support DomainC; Entity EdgesOf[All, Not SkinDomainC]; @}
      @{ Name vn; NameOfCoef phin; Function BF_GradNode;
        Support DomainCC; Entity NodesOf[All]; @}
      @{ Name vn; NameOfCoef phic; Function BF_GroupOfEdges;
        Support DomainC; Entity GroupsOfEdgesOnNodesOf[SkinDomainC];@}
    @}
    Constraint @{
      @{ NameOfCoef hk;
        EntityType EdgesOf; NameOfConstraint MagneticField; @}
      @{ NameOfCoef phin;
        EntityType NodesOf; NameOfConstraint MagneticScalarPotential; @}
      @{ NameOfCoef phic;
        EntityType NodesOf; NameOfConstraint MagneticScalarPotential; @}
    @}
  @}
@}
@end example

@noindent
This example points out the definition of a piecewise defined basis function, e.g.,
function @code{vn} being defined with @code{BF_GradNode} in @code{DomainCC} and
@code{BF_GroupOfEdges} in @code{DomainC}. This leads to an easy coupling
between these regions.


@c .........................................................................
@c Coupled Edge and Nodal Finite Element Spaces for Multiply Connected Domains
@c .........................................................................

@node Multiply connected domains,  , Coupled spaces, FunctionSpace examples
@subsection Coupled edge and nodal finite element spaces for multiply connected domains

In case a multiply connected domain @var{WcC} is considered, basis functions
associated with cuts (@code{SurfaceCut}) have to be added to the previous
basis functions, which gives the function space below:

@example
Group @{
  _TransitionLayer_SkinDomainC_ =
    ElementsOf[SkinDomainC, OnOneSideOf SurfaceCut];
@}

FunctionSpace @{
  @{ Name Hcurl_hphi; Type Form1;
    BasisFunction @{

      @dots{} @var{same as above} @dots{}

      @{ Name sc; NameOfCoef Ic; Function BF_GradGroupOfNodes;
        Support ElementsOf[DomainCC, OnOneSideOf SurfaceCut];
        Entity GroupsOfNodesOf[SurfaceCut]; @}
      @{ Name sc; NameOfCoef Icc; Function BF_GroupOfEdges;
        Support DomainC;
        Entity GroupsOfEdgesOf
                 [SurfaceCut,
                  InSupport _TransitionLayer_SkinDomainC_]; @}
    @}
    GlobalQuantity @{
      @{ Name I; Type AliasOf       ; NameOfCoef Ic; @}
      @{ Name U; Type AssociatedWith; NameOfCoef Ic; @}
    @}
    Constraint @{

      @dots{} @var{same as above} @dots{}

      @{ NameOfCoef Ic;
        EntityType GroupsOfNodesOf; NameOfConstraint Current; @}
      @{ NameOfCoef Icc;
        EntityType GroupsOfNodesOf; NameOfConstraint Current; @}
      @{ NameOfCoef U;
        EntityType GroupsOfNodesOf; NameOfConstraint Voltage; @}
    @}
  @}
@}
@end example

@noindent
Global quantities associated with the cuts, i.e., currents and voltages
if @var{h} is the magnetic field, have also been defined.


@c -------------------------------------------------------------------------
@c Jacobian Examples
@c -------------------------------------------------------------------------

@node Jacobian examples, Integration examples, FunctionSpace examples, Short examples
@section @code{Jacobian} examples

@cindex Jacobian, examples


A simple Jacobian method is for volume transformations (of @var{n}-D
regions in @var{n}-D geometries; @var{n} = 1, 2 or 3),
e.g., in region @code{Domain},

@example
Jacobian @{
  @{ Name Vol;
    Case @{
      @{ Region Domain; Jacobian Vol; @}
    @}
  @}
@}
@end example

@noindent
@code{Jacobian VolAxi} would define a volume Jacobian for axisymmetrical problems.

A Jacobian method can also be piecewise defined, in @code{DomainInf}, where
an infinite geometrical transformation has to be made using two constant
parameters (inner and outer radius of a spherical shell), and in all the
other regions (@code{All}, being the default); in each case, a volume
Jacobian is used.  This method is defined by:

@example
Jacobian @{
  @{ Name Vol;
    Case @{
      @{ Region DomainInf; Jacobian VolSphShell @{Val_Rint, Val_Rext@}; @}
      @{ Region All; Jacobian Vol; @}
    @}
  @}
@}
@end example

@c -------------------------------------------------------------------------
@c Integration Examples
@c -------------------------------------------------------------------------

@node Integration examples, Formulation examples, Jacobian examples, Short examples
@section @code{Integration} examples

@cindex Integration, examples


A commonly used numerical integration method is the @code{Gauss} integration,
with a number of integration points (@code{NumberOfPoints}) depending on
geometrical element types (@code{GeoElement}), i.e.

@example
Integration @{
  @{ Name Int_1;
    Case @{ @{Type Gauss;
            Case @{ @{ GeoElement Triangle   ; NumberOfPoints 4; @}
                   @{ GeoElement Quadrangle ; NumberOfPoints 4; @}
                   @{ GeoElement Tetrahedron; NumberOfPoints 4; @}
                   @{ GeoElement Hexahedron ; NumberOfPoints 6; @}
                   @{ GeoElement Prism      ; NumberOfPoints 9; @} @}
           @}
         @}
  @}
@}
@end example

@noindent
The method above is valid for both 2D and 3D problems, for different kinds
of elements.

@c -------------------------------------------------------------------------
@c Formulation Examples
@c -------------------------------------------------------------------------

@node Formulation examples, Resolution examples, Integration examples, Short examples
@section @code{Formulation} examples

@cindex Formulation, examples

@menu
* Electrostatics::
* Electrostatics 2::
* Magnetostatics::
* Magnetodynamics::
* Other formulations::
@end menu

@c todo: ajouter un vrai exemple de circuit (cf. constraint example)

@c .........................................................................
@c Electrostatic Scalar Potential Formulation
@c .........................................................................

@node Electrostatics, Electrostatics 2, Formulation examples, Formulation examples
@subsection Electrostatic scalar potential formulation

@cindex Electrostatic formulation
@cindex Formulation, electrostatics
@cindex Nodal function space, example

An electrostatic formulation using an electric scalar potential @var{v}, i.e.

@tex
$$ (\epsilon\,{\rm grad}\,v, {\rm grad}\,v')_W = 0 \quad\forall v'\in S^0(W)  $$
@end tex
@ifnottex
( epsr grad @var{v}, grad @var{vp} ) @var{W} = 0,  for all @var{vp} in @i{S0(W)},
@end ifnottex

@noindent
is expressed by

@example
Formulation @{
  @{ Name Electrostatics_v; Type FemEquation;
    Quantity @{
      @{ Name v; Type Local; NameOfSpace Hgrad_v; @}
    @}
    Equation @{
      Integral @{ [ epsr[] * Dof@{Grad v@} , @{Grad v@} ];
                 In Domain; Jacobian Vol; Integration Int_1; @}
    @}
  @}
@}
@end example

@noindent
The density of the @code{Integral} term is a copy of the symbolic form of
the formulation, i.e., the product of a relative permittivity function
@code{epsr[]} by a vector of degrees of freedom (@code{Dof@{.@}}); the
scalar product of this with the gradient of test function @code{v} results
in a symmetrical matrix.

@noindent
Note that another @code{Quantity} could be defined for test functions,
e.g., @code{vp} defined by @code{@{ Name vp; Type Local; NameOfSpace
Hgrad_v; @}}.  However, its use would result in the computation of a full
matrix and consequently in a loss of efficiency.

@c .........................................................................
@c Electrostatic Scalar Potential Formulation with Floating Potentials and Electric Charges
@c .........................................................................

@node Electrostatics 2, Magnetostatics, Electrostatics, Formulation examples
@subsection Electrostatic scalar potential formulation with floating potentials and electric charges

@cindex Floating potential, example
@cindex Global quantity, example

An extension of the formulation above can be made to take floating
potentials and electrical charges into account (the latter being defined in
@code{FunctionSpace Hgrad_v_floating}), i.e.

@example
Formulation @{
  @{ Name Electrostatics_v_floating; Type FemEquation;
    Quantity @{
      @{ Name v; Type Local; NameOfSpace Hgrad_v_floating; @}
      @{ Name V; Type Global;
        NameOfSpace Hgrad_v_floating [GlobalElectricPotential]; @}
      @{ Name Q; Type Global;
        NameOfSpace Hgrad_v_floating [GlobalElectricCharge]; @}
    @}
    Equation @{
      Integral @{ [ epsr[] * Dof@{Grad v@} , @{Grad v@} ];
                 In Domain; Jacobian Vol; Integration Int_1; @}
      GlobalTerm @{ [ - Dof@{Q@}/eps0 , @{V@} ]; In SkinDomainC; @}
    @}
  @}
@}
@end example

@noindent
with the predefinition @code{Function @{ eps0 = 8.854187818e-12; @}}.

@c .........................................................................
@c Magnetostatic 3D Vector Potential Formulation
@c .........................................................................

@node Magnetostatics, Magnetodynamics, Electrostatics 2, Formulation examples
@subsection Magnetostatic 3D vector potential formulation

@cindex Edge element space, example

A magnetostatic 3D vector potential formulation

@tex
$$ (\nu\,{\rm curl}\,{\bf a}, {\rm curl}\,{\bf a}')_W =
({\bf j}_s , {\bf a}')_{W_s}  \quad\forall{\bf a}'\in S^1(W), {\rm\ with\ gauge\ condition} $$
@end tex
@ifnottex
( @var{nu} curl @var{a} , curl @var{ap} ) @var{W} -
( @var{js} , @var{ap} ) @var{Ws} = 0,
for all @var{ap} in @i{S1(W)} with gauge condition,
@end ifnottex

@noindent
with a source current density @var{js} in inductors @var{Ws}, is expressed by

@example
Formulation @{
  @{ Name Magnetostatics_a_3D; Type FemEquation;
    Quantity @{
      @{ Name a; Type Local; NameOfSpace Hcurl_a_Gauge; @}
    @}
    Equation @{
      Integral @{ [ nu[] * Dof@{Curl a@} , @{Curl a@} ];
                 In Domain; Jacobian Vol; Integration Int_1; @}
      Integral @{ [ - SourceCurrentDensity[] , @{a@} ];
                 In DomainWithSourceCurrentDensity;
                 Jacobian Vol; Integration Int_1; @}
    @}
  @}
@}
@end example

@noindent
Note that @var{js} is here given by a function @code{SourceCurrentDensity[]},
but could also be given by data computed from another problem,
e.g., from an electrokinetic problem (coupling of formulations) or
from a fully fixed function space (constraints fixing the density, which is
usually more efficient in time domain analyses).

@c .........................................................................
@c Magnetodynamic 3D or 2D Magnetic Field and Magnetic Scalar Potential Formulation
@c .........................................................................

@node Magnetodynamics, Other formulations, Magnetostatics, Formulation examples
@subsection Magnetodynamic 3D or 2D magnetic field and magnetic scalar potential formulation

A magnetodynamic 3D or 2D @var{h-phi} formulation, i.e., coupling the magnetic
field @var{h} with a magnetic scalar potential @var{phi},

@tex
$$ \partial_t (\mu\,{\bf h}, {\bf h}')_W +
   (\rho\,{\rm curl}\,{\bf h}, {\rm curl}\,{\bf h}')_{W_c} = 0
   \quad\forall{\bf h}'\in S^1(W) $$
@end tex
@ifnottex
Dt ( @var{mu} @var{h} , @var{hp} ) @var{W} +
( @var{ro} curl @var{h} , curl @var{hp} ) @var{Wc} = 0,
for all @var{hp} in @i{S1(W)},
@end ifnottex

@noindent
can be expressed by


@example
Formulation @{
  @{ Name Magnetodynamics_hphi; Type FemEquation;
    Quantity @{
      @{ Name h; Type Local; NameOfSpace Hcurl_hphi; @}
    @}
    Equation @{
      Integral @{ Dt [ mu[] * Dof@{h@} , @{h@} ];
                 In Domain; Jacobian Vol; Integration Int_1; @}
      Integral @{ [ rho[] * Dof@{Curl h@} , @{Curl h@} ];
                 In DomainC; Jacobian Vol; Integration Int_1; @}
    @}
  @}
@}
@end example

@c .........................................................................
@c Nonlinearities, Mixed Formulations, ...
@c .........................................................................

@node Other formulations,  , Magnetodynamics, Formulation examples
@subsection Nonlinearities, Mixed formulations, @dots{}

In case nonlinear physical characteristics are considered, arguments are
used for associated functions, e.g., @code{mu[@{h@}]}. Several test
functions can be considered in an @code{Equation} field.  Consequently,
mixed formulations can be defined.


@c -------------------------------------------------------------------------
@c Resolution Examples
@c -------------------------------------------------------------------------

@node Resolution examples, PostProcessing examples, Formulation examples, Short examples
@section @code{Resolution} examples

@cindex Resolution, examples

@menu
* Static resolution::
* Frequency domain resolution::
* Time domain resolution::
* Nonlinear resolution::
* Coupled formulations::
@end menu

@c .........................................................................
@c Static Resolution (Electrostatic Problem)
@c .........................................................................

@node Static resolution, Frequency domain resolution, Resolution examples, Resolution examples
@subsection Static resolution (electrostatic problem)

A static resolution, e.g., for the electrostatic formulation
(@pxref{Formulation examples}), can be defined by

@example
Resolution @{
  @{ Name Electrostatics_v;
    System @{
      @{ Name Sys_Ele; NameOfFormulation Electrostatics_v; @}
    @}
    Operation @{
      Generate[Sys_Ele]; Solve[Sys_Ele]; SaveSolution[Sys_Ele];
    @}
  @}
@}
@end example

@noindent
The generation (@code{Generate}) of the matrix of the system @code{Sys_Ele}
will be made with the formulation @code{Electrostatics_v}, followed by its
solving (@code{Solve}) and the saving of the solution (@code{SaveSolution}).

@c .........................................................................
@c Frequency Domain Resolution (Magnetodynamic Problem)
@c .........................................................................

@node Frequency domain resolution, Time domain resolution, Static resolution, Resolution examples
@subsection Frequency domain resolution (magnetodynamic problem)

A frequency domain resolution, e.g., for the magnetodynamic @var{h-phi}
formulation (@pxref{Formulation examples}), is given by

@example
Resolution @{
  @{ Name Magnetodynamics_hphi;
    System @{
      @{ Name Sys_Mag; NameOfFormulation Magnetodynamics_hphi;
        Frequency Freq; @}
    @}
    Operation @{
      Generate[Sys_Mag]; Solve[Sys_Mag]; SaveSolution[Sys_Mag];
    @}
  @}
@}
@end example

@noindent
preceded by the definition of constant @code{Freq}, e.g.,

@example
Function @{
  Freq = 50.;
@}
@end example

@c .........................................................................
@c Time Domain Resolution (Magnetodynamic Problem)
@c .........................................................................

@node Time domain resolution, Nonlinear resolution, Frequency domain resolution, Resolution examples
@subsection Time domain resolution (magnetodynamic problem)

A time domain resolution, e.g., for the same magnetodynamic @var{h-phi}
formulation (@pxref{Formulation examples}), is given by

@example
Resolution @{
  @{ Name Magnetodynamics_hphi_Time;
    System @{
      @{ Name Sys_Mag; NameOfFormulation Magnetodynamics_hphi; @}
    @}
    Operation @{
      InitSolution[Sys_Mag]; SaveSolution[Sys_Mag];
      TimeLoopTheta[Mag_Time0, Mag_TimeMax, Mag_DTime[], Mag_Theta[]] @{
        Generate[Sys_Mag]; Solve[Sys_Mag]; SaveSolution[Sys_Mag];
      @}
    @}
  @}
@}
@end example

@noindent
If, e.g., the @code{Resolution} above is preceded by the constant and function
definitions below

@example
Function @{
  Tc = 10.e-3;
  Mag_Time0 = 0.; Mag_TimeMax = 2.*Tc; Mag_DTime[] = Tc/20.;
  Mag_Theta[] = 1./2.;
@}
@end example

@noindent
the performed time domain analysis will be a Crank-Nicolson scheme
(theta-scheme with @code{Theta = 0.5}) with initial time 0 ms, end time
20 ms and time step 1 ms.

@c .........................................................................
@c Nonlinear Time Domain Resolution (Magnetodynamic Problem)
@c .........................................................................

@node Nonlinear resolution, Coupled formulations, Time domain resolution, Resolution examples
@subsection Nonlinear time domain resolution (magnetodynamic problem)

In case a nonlinear problem is solved, an iterative loop has to be defined
in an appropriate level of the recursive resolution operations, e.g., for
the magnetodynamic problem above,

@example
@dots{}
    Operation @{
      InitSolution[Sys_Mag]; SaveSolution[Sys_Mag];
      TimeLoopTheta[Mag_Time0, Mag_TimeMax, Mag_DTime[], Mag_Theta[]] @{
        IterativeLoop[NL_NbrMax, NL_Eps, NL_Relax] @{
          GenerateJac[Sys_Mag]; SolveJac[Sys_Mag];
        @}
        SaveSolution[Sys_Mag];
      @}
    @}
@dots{}
@end example

@noindent
preceded by constant definitions, e.g.,

@example
Function @{
  NL_Eps = 1.e-4; NL_Relax = 1.; NL_NbrMax = 80;
@}
@end example



@c .........................................................................
@c Coupled Formulations
@c .........................................................................

@node Coupled formulations,  , Nonlinear resolution, Resolution examples
@subsection Coupled formulations

A coupled problem, e.g., magnetodynamic (in frequency domain;
@code{Frequency Freq}) - thermal (in time domain) coupling, with temperature
dependent characteristics (e.g., @code{rho[@{T@}]}, @dots{}), can be defined by:

@example
Resolution @{
  @{ Name MagnetoThermalCoupling_hphi_T;
    System @{
      @{ Name Sys_Mag; NameOfFormulation Magnetodynamics_hphi;
        Frequency Freq; @}
      @{ Name Sys_The; NameOfFormulation Thermal_T; @}
    @}
    Operation @{
      InitSolution[Sys_Mag]; InitSolution[Sys_The];
      IterativeLoop[NL_NbrMax, NL_Eps, NL_Relax] @{
        GenerateJac[Sys_Mag]; SolveJac[Sys_Mag];
        GenerateJac[Sys_The]; SolveJac[Sys_The];
      @}
      SaveSolution[Sys_Mag]; SaveSolution[Sys_The];
    @}
  @}
@}
@end example

@noindent
Two systems of equations, @code{Sys_Mag} and @code{Sys_The}, will be solved
iteratively until convergence (@code{Criterion}), using a relaxation factor
(@code{RelaxationFactor}).


It can be seen through these examples that many resolutions can be linked or
nested directly by the user, which gives a great freedom for coupled problems.


@c -------------------------------------------------------------------------
@c PostProcessing Examples
@c -------------------------------------------------------------------------

@node PostProcessing examples, PostOperation examples, Resolution examples, Short examples
@section @code{PostProcessing} examples

@cindex Post-processing, examples

The quantities to be post-computed based on a solution of a resolution are
defined, e.g., for the electrostatic problem (@pxref{Formulation examples};
@pxref{Resolution examples}), for the solution associated with the
formulation @code{Electrostatics_v}, by

@example
PostProcessing @{
  @{ Name EleSta_v; NameOfFormulation Electrostatics_v;
    Quantity @{
      @{ Name v; Value @{ Local @{ [ @{v@} ]; In Domain; @} @} @}
      @{ Name e; Value @{ Local @{ [ -@{Grad v@} ]; In Domain; @} @} @}
      @{ Name d; Value @{ Local @{ [ -eps0*epsr[] *@{Grad v@} ];
                                  In Domain; @} @} @}
    @}
  @}
@}
@end example

@noindent
The electric scalar potential @var{v} (@code{v}), the electric field
@var{e} (@code{e}) and the electric flux density @var{d} (@code{d}) can
all be computed from the solution. They are all defined in the region
@code{Domain}.

The quantities for the solution associated with the formulation
@code{Electrostatics_v_float@-ing} are defined by

@example
PostProcessing @{
  @{ Name EleSta_vf; NameOfFormulation Electrostatics_v_floating;
    Quantity @{

      @dots{} @var{same as above} @dots{}

      @{ Name Q; Value @{ Local @{ [ @{Q@} ]; In SkinDomainC; @} @} @}
      @{ Name V; Value @{ Local @{ [ @{V@} ]; In SkinDomainC; @} @} @}
    @}
  @}
@}
@end example

@noindent
which points out the way to define post-quantities based on global quantities.


@c -------------------------------------------------------------------------
@c PostOperation Examples
@c -------------------------------------------------------------------------

@node PostOperation examples,  , PostProcessing examples, Short examples
@section @code{PostOperation} examples

@cindex Post-operation, examples

The simplest post-processing operation is the generation of maps of local
quantities, i.e., the display of the computed fields on the mesh. For
example, using the @code{PostProcessing} defined in @ref{PostProcessing
examples}, the maps of the electric scalar potential and of the electric
field on the elements of the region @code{Domain} are defined as:

@example
PostOperation @{
  @{ Name Map_v_e; NameOfPostProcessing EleSta_v ;
     Operation @{
       Print [ v, OnElementsOf Domain, File "map_v.pos" ];
       Print [ e, OnElementsOf Domain, File "map_e.pos" ];
     @}
  @}
@}
@end example

It is also possible to display local quantities on sections of the mesh,
here for example on the plane containing the points (0,0,1), (1,0,1) and
(0,1,1):

@example
Print [ v, OnSection @{ @{0,0,1@} @{1,0,1@} @{0,1,1@} @}, File "sec_v.pos" ];
@end example

Finally, local quantities can also be interpolated on another mesh than the
one on which they have been computed. Six types of grids can be specified
for this interpolation: a single point, a set of points evenly distributed
on a line, a set of points evenly distributed on a plane, a set of points
evenly distributed in a box, a set of points defined by a parametric
equation, and a set of elements belonging to a different mesh than the
original one:

@example
Print [ e, OnPoint @{0,0,1@} ];
Print [ e, OnLine @{ @{0,0,1@} @{1,0,1@} @} @{125@} ];
Print [ e, OnPlane @{ @{0,0,1@} @{1,0,1@} @{0,1,1@} @} @{125, 75@} ];
Print [ e, OnBox @{ @{0,0,1@} @{1,0,1@} @{0,1,1@} @{0,0,2@} @} @{125, 75, 85@} ];
Print [ e, OnGrid @{$A, $B, 1@} @{ 0:1:1/125, 0:1:1/75, 0 @} ];
Print [ e, OnGrid Domain2 ];
@end example

Many options can be used to modify the aspect of all these maps, as well as
the default behaviour of the @code{Print} commands. See @ref{Types for
PostOperation}, to get the list of all these options. For example, to obtain
a map of the scalar potential at the barycenters of the elements on the
boundary of the region @code{Domain}, in a table oriented format appended to
an already existing file @code{out.txt}, the operation would be:

@example
Print [ v, OnElementsOf Domain, Depth 0, Skin, Format Table,
        File >> "out.txt" ];
@end example

Global quantities, which are associated with regions (and not with the
elements of the mesh of these regions), are displayed thanks to the
@code{OnRegion} operation. For example, the global potential and charge on
the region @code{SkinDomainC} can be displayed with:

@example
PostOperation @{
  @{ Name Val_V_Q; NameOfPostProcessing EleSta_vf ;
     Operation @{
       Print [ V, OnRegion SkinDomainC ];
       Print [ Q, OnRegion SkinDomainC ];
     @}
  @}
@}
@end example


@c =========================================================================
@c Complete Examples
@c =========================================================================

@node Complete examples, File formats, Short examples, Top
@chapter Complete examples

@cindex Complete examples
@cindex Examples, complete
@cindex Wiki

This chapter presents complete examples that can be run ``as is'' with
GetDP (@pxref{Running GetDP}).

Many other ready-to-use examples are available on the website of the
ONELAB project: @url{http://onelab.info}.


@menu
* Electrostatic problem::
* Magnetostatic problem::
* Magnetodynamic problem::
@end menu

@c -------------------------------------------------------------------------
@c Electrostatic Problem
@c -------------------------------------------------------------------------

@node Electrostatic problem, Magnetostatic problem, Complete examples, Complete examples
@section Electrostatic problem

Let us first consider a simple electrostatic problem.  The formulation
used is an electric scalar potential formulation (file
@file{EleSta_v.pro}, including files @file{Jacobian_Lib.pro} and
@file{Integration_Lib.pro}).  It is applied to a microstrip line (file
@file{mStrip.pro}), whose geometry is defined in the file
@file{mStrip.geo} (@pxref{Gmsh examples}). The geometry is
two-dimensional and by symmetry only one half of the structure is
modeled.

@image{Strip,,}

Note that the structure of the following files points out the separation
of the data describing the particular problem and the method used to
solve it (@pxref{Numerical tools as objects}), and therefore how it is
possible to build black boxes adapted to well defined categories of
problems. The files are commented (@pxref{Comments}) and can be run
without any modification.

@sp 1

@verbatiminclude mStrip.pro

@sp 1

@verbatiminclude EleSta_v.pro

@sp 1

@verbatiminclude Jacobian_Lib.pro

@sp 1

@verbatiminclude Integration_Lib.pro

@page

@c -------------------------------------------------------------------------
@c Magnetostatic Problem
@c -------------------------------------------------------------------------

@node Magnetostatic problem, Magnetodynamic problem, Electrostatic problem, Complete examples
@section Magnetostatic problem

We now consider a magnetostatic problem.  The formulation used is a 2D
magnetic vector potential formulation (see file @file{MagSta_a_2D.pro}).
It is applied to a core-inductor system (file @file{CoreSta.pro}), whose
geometry is defined in theh file @file{Core.geo} (@pxref{Gmsh
examples}).  The geometry is two-dimensional and, by symmetry, one
fourth of the structure is modeled.

@image{Core,,}

The jacobian and integration methods used are the same as for the
electrostatic problem presented in @ref{Electrostatic problem}.

@sp 1

@verbatiminclude CoreSta.pro

@sp 1

@verbatiminclude MagSta_a_2D.pro

@page

@c -------------------------------------------------------------------------
@c Magnetodynamic Problem
@c -------------------------------------------------------------------------

@node Magnetodynamic problem,  , Magnetostatic problem, Complete examples
@section Magnetodynamic problem

As a third example we consider a magnetodynamic problem.  The
formulation is a two-dimensional a-v formulation (see file
@file{MagDyn_av_2D.pro}, which includes the same jacobian and
integration library files as in @ref{Electrostatic problem}).  It is
applied to a core-inductor system (defined in file
@file{CoreMassive.pro}), whose geometry has already been defined in file
@file{Core.geo}.

@sp 1

@verbatiminclude CoreMassive.pro

@sp 1

@verbatiminclude MagDyn_av_2D.pro


@c =========================================================================
@c File Formats
@c =========================================================================

@node File formats, Gmsh examples, Complete examples, Top
@appendix File formats

This chapter describes the file formats that cannot be modified by the
user. The format of the problem definition structure is explained in
@ref{Objects}, and @ref{Types for objects}. The format of the
post-processing files is explained in @ref{Types for PostOperation}.

@menu
* Input file format::
* Output file format::
@end menu

@c -------------------------------------------------------------------------
@c Input File Format
@c -------------------------------------------------------------------------

@node Input file format, Output file format, File formats, File formats
@section Input file format

@cindex Input file format
@cindex Gmsh, file format
@cindex Mesh, file format
@cindex File, mesh
@cindex File, @file{.msh}
@cindex @file{.msh} file

The native mesh format read by GetDP is the mesh file format produced by
Gmsh (@url{http://gmsh.info}). In its ``version 1'' incarnation, an
`msh' file is divided into two sections, defining the nodes and the
elements in the mesh.

@example
$NOD
@var{number-of-nodes}
@var{node-number} @var{x-coord} @var{y-coord} @var{z-coord}
@dots{}
$ENDNOD
$ELM
@var{number-of-elements}
@var{elm-number} @var{elm-type} @var{elm-region} @var{unused} @var{number-of-nodes} @var{node-numbers}
@dots{}
$ENDELM
@end example

@noindent
All the syntactic variables stand for integers except @var{x-coord},
@var{y-coord} and @var{z-coord} which stand for floating point values.
The @var{elm-type} value defines the geometrical type for the element:

@noindent
@var{elm-type}:

@table @code
@item 1
Line (2 nodes, 1 edge).
@item 2
Triangle (3 nodes, 3 edges).
@item 3
Quadrangle (4 nodes, 4 edges).
@item 4
Tetrahedron (4 nodes, 6 edges, 4 facets).
@item 5
Hexahedron (8 nodes, 12 edges, 6 facets).
@item 6
Prism (6 nodes, 9 edges, 5 facets).
@item 7
Pyramid (5 nodes, 8 edges, 5 facets).
@item 15
Point (1 node).
@end table

GetDP can also read more recent versions of the `msh' format (2.0 and
above), as well as binary meshes. See the Gmsh documentation for more
information about these formats.

@c -------------------------------------------------------------------------
@c Output File Format
@c -------------------------------------------------------------------------

@node Output file format,  , Input file format, File formats
@section Output file format

@cindex Output file format

@menu
* File pre::
* File res::
@end menu


@c .........................................................................
@c File .pre
@c .........................................................................

@node File pre, File res, Output file format, Output file format
@subsection File @file{.pre}

@cindex File, pre-processing
@cindex @file{.pre} file
@cindex File, @file{.pre}

The @file{.pre} file is generated by the pre-processing stage. It
contains all the information about the degrees of freedom to be
considered during the processing stage for a given resolution (i.e.,
unknowns, fixed values, initial values, etc.).

@example
$Resolution /* '@var{resolution-id}' */
@var{main-resolution-number} @var{number-of-dofdata}
$EndResolution
$DofData /* #@var{dofdata-number} */
@var{resolution-number} @var{system-number}
@var{number-of-function-spaces} @var{function-space-number} @dots{}
@var{number-of-time-functions} @var{time-function-number} @dots{}
@var{number-of-partitions} @var{partition-index} @dots{}
@var{number-of-any-dof} @var{number-of-dof}
@var{dof-basis-function-number} @var{dof-entity} @var{dof-harmonic} @var{dof-type} @var{dof-data}
@dots{}
$EndDofData
@dots{}
@end example

@noindent
with

@example
@var{dof-data}:
  @var{equation-number} @var{nnz}
    (@var{dof-type}: 1; @var{unknown}) |
  @var{dof-value} @var{dof-time-function-number}
    (@var{dof-type}: 2; @var{fixed value}) |
  @var{dof-associate-dof-number} @var{dof-value} @var{dof-time-function-number}
    (@var{dof-type}: 3; @var{associated degree of freedom}) |
  @var{equation-number} @var{dof-value}
    (@var{dof-type}: 5; @var{initial value for an unknown})

@end example


@noindent Notes:
@enumerate
@item
There is one @code{$DofData} field for each system of equations considered in
the resolution (including those considered in pre-resolutions).
@item
The @var{dofdata-number} of a @code{$DofData} field is determined by the order
of this field in the @file{.pre} file.
@item
@var{number-of-dof} is the dimension of the considered system of equations, while
@var{number-of-any-dof} is the total number of degrees of freedom before
the application of constraints.
@item
Each degree of freedom is coded with three integer values, which are the
associated basis function, entity and harmonic numbers, i.e.,
@var{dof-basis-function-number}, @var{dof-entity} and @var{dof-harmonic}.
@item
@var{nnz} is not used at the moment.
@end enumerate


@c .........................................................................
@c File .res
@c .........................................................................

@node File res,  , File pre, Output file format
@subsection File @file{.res}

@cindex File, result
@cindex @file{.res} file
@cindex File, @file{.res}

The @file{.res} file is generated by the processing stage. It contains
the solution of the problem (or a part of it in case of program
interruption).

@example
$ResFormat /* GetDP v@var{getdp-version-number}, @var{string-for-format} */
1.1 @var{file-res-format}
$EndResFormat
$Solution  /* DofData #@var{dofdata-number} */
@var{dofdata-number} @var{time-value} @var{time-imag-value} @var{time-step-number}
@var{solution-value}
@dots{}
$EndSolution
@dots{}
@end example


@noindent Notes:
@enumerate
@item
A @code{$Solution} field contains the solution associated with a
@code{$DofData} field.
@item
There is one @code{$Solution} field for each time step, of which the time is
@var{time-value} (0 for non time dependent or non modal analyses) and the
imaginary time is @var{time-imag-value} (0 for non time dependent or non
modal analyses).
@item
The order of the @var{solution-value}s in a @code{$Solution} field follows
the numbering of the equations given in the @file{.pre} file
(one floating point value for each degree of freedom).
@end enumerate

@c =========================================================================
@c Gmsh Examples
@c =========================================================================

@node Gmsh examples, Compiling the source code, File formats, Top
@appendix Gmsh examples

@cindex Gmsh, examples
@cindex Mesh, examples

Gmsh is a three-dimensional finite element mesh generator with simple CAD
and post-processing capabilities that can be used as a graphical front-end
for GetDP. Gmsh can be downloaded from @url{http://gmsh.info}.

This appendix reproduces verbatim the input files needed by Gmsh to produce
the mesh files @file{mStrip.msh} and @file{Core.msh} used in the examples of
@ref{Complete examples}.

@sp 1

@verbatiminclude mStrip.geo

@sp 1

@verbatiminclude Core.geo

@c =========================================================================
@c Compiling the source code
@c =========================================================================

@node Compiling the source code, Frequently asked questions, Gmsh examples, Top
@appendix Compiling the source code

Stable releases and source snapshots are available from
@uref{http://getdp.info/src/}. You can also access the Git repository
directly:

@enumerate
@item
The first time you want to download the latest full source, type:

@example
git clone @url{http://gitlab.onelab.info/getdp/getdp.git}
@end example

@item
To update your local version to the latest and greatest, go in the getdp
directory and type:

@example
git pull
@end example

@end enumerate

Once you have the source code, you need to run CMake to configure your
build (see the
@url{http://gitlab.onelab.info/getdp/getdp/tree/master/README.txt,README.txt}
file in the top-level source directory for detailed information on how
to run CMake).

Each build can be configured using a series of options, to selectively
enable optional modules or features. Here is the list of CMake options:

@ftable @code

@include cmake_options.texi

@end ftable

@c =========================================================================
@c Frequently asked questions
@c =========================================================================

@node Frequently asked questions, Tips and tricks, Compiling the source code, Top
@appendix Frequently asked questions

@cindex Frequently asked questions
@cindex Questions, frequently asked
@cindex FAQ

@c -------------------------------------------------------------------------
@c The basics
@c -------------------------------------------------------------------------

@menu
* The basics::
* Installation::
* Usage::
@end menu

@node The basics, Installation, Frequently asked questions, Frequently asked questions
@section The basics

@enumerate
@item What is GetDP?

GetDP is a scientific software environment for the numerical solution of
integro-differential equations, open to the coupling of physical
problems (electromagnetic, thermal, mechanical, etc) as well as of
numerical methods (finite element method, integral methods, etc). It can
deal with such problems of various dimensions (1D, 2D, 2D axisymmetric
or 3D) and time states (static, transient or harmonic). The main feature
of GetDP is the closeness between the organization of data defining
discrete problems (written by the user in ASCII data files) and the
symbolic mathematical expressions of these problems.

@item What are the terms and conditions of use?

GetDP is distributed under the terms of the GNU General Public
License. See @ref{License} for more information.

@item What does `GetDP' mean?

It's an acronym for a ``General environment for the treatment of
Discrete Problems''.

@item Where can I find more information?

@url{http://getdp.info} is the primary location to obtain information
about GetDP. There you will for example find the complete reference
manual and the @url{https://gitlab.onelab.info/getdp/getdp/issues,bug
tracking database}.
@end enumerate

@c -------------------------------------------------------------------------
@c Installation
@c -------------------------------------------------------------------------

@node Installation, Usage, The basics, Frequently asked questions
@section Installation

@enumerate
@item Which OSes does GetDP run on?

Gmsh runs on Windows, MacOS X, Linux and most Unix variants.

@item What do I need to compile GetDP from the sources?

You need a C++ and a Fortran compiler as well as the GSL (version 1.2
or higher; freely available from @url{http://sources.redhat.com/gsl}).

@item How do I compile GetDP?

You need cmake (@url{http://www.cmake.org}) and a C++ compiler (and a
Fortran compiler depending on the modules/solvers you want to
compile). See @ref{Compiling the source code} and the
@url{http://gitlab.onelab.info/getdp/getdp/tree/master/README.txt,README.txt}
file in the top-level source directory for more information.

@item GetDP [from a binary distribution] complains about missing libraries.

Try @code{ldd getdp} (or @code{otool -L getdp} on MacOS X) to check if
all the required shared libraries are installed on your system. If not,
install them. If it still doesn't work, recompile GetDP from the
sources.
@end enumerate

@c -------------------------------------------------------------------------
@c Usage
@c -------------------------------------------------------------------------

@node Usage,  , Installation, Frequently asked questions
@section Usage

@enumerate
@item How can I provide a mesh to GetDP?

The only meshing format accepted by this version of GetDP is the `msh'
format created by Gmsh @url{http://gmsh.info}. This format being
very simple (see the Gmsh reference manual for more details), it should
be straightforward to write a converter from your mesh format to the
`msh' format.

@item How can I visualize the results produced by GetDP?

You can specify a format in all post-processing operations. Available
formats include @code{Table}, @code{SimpleTable}, @code{TimeTable} and
@code{Gmsh}. @code{Table}, @code{SimpleTable} and @code{TimeTable}
output lists of numbers easily readable by Excel/gnuplot/Caleida
Graph/etc. @code{Gmsh} outputs post-processing views directly loadable
by Gmsh.

@item How do I change the linear solver used by GetDP?

It depends on which linear solver toolkit was enabled when GetDP was
compiled (PETSc or Sparskit).

With PETSc-based linear solvers you can either specify options on the
command line (e.g. with @code{-ksp_type gmres -pc_type ilu}), through a
specific option file (with @code{-solver file}), through the
@file{.petscrc} file located in your home directly, or directly in the
@code{Resolution} field using the @code{SetGlobalSolverOptions[]}
command.

With Sparskit-based linear solvers can either specify options directly
on command line (e.g. with @code{-Nb_Fill 200}), specify an option file
explicitly (with @code{-solver file}), or edit the @file{solver.par}
file in the current working directory. If no @file{solver.par} file
exists in the current directory, GetDP will give create it the next time
you perform a linear system solution.
@end enumerate

@c =========================================================================
@c Tips ans Tricks
@c =========================================================================

@node Tips and tricks, Version history, Frequently asked questions, Top
@appendix Tips and tricks

@cindex Tips
@cindex Tricks
@cindex Efficiency, tips

@itemize @bullet
@item
Install the 'info' version of this user's guide! On your (Unix) system, this
can be achieved by 1) copying all getdp.info* files to the place where your
info files live (usually /usr/info), and 2) issuing the command
'install-info /usr/info/getdp.info /usr/info/dir'. You will then be able to
access the documentation with the command 'info getdp'. Note that particular
sections ("nodes") can be accessed directly. For example, 'info getdp
functionspace' will take you directly to the definition of the FunctionSpace
object.
@item
Use emacs to edit your files, and load the C++ mode! This permits automatic
syntax highlighting and easy indentation. Automatic loading of the C++ mode
for @file{.pro} files can be achieved by adding the following command in
your @code{.emacs} file: @code{(setq auto-mode-alist (append '(("\\.pro$"
. c++-mode)) auto-mode-alist))}.
@item
Define integration and Jacobian method in separate files, reusable in all
your problem definition structures (@pxref{Includes}). Define meshes,
groups, functions and constraints in one file dependent of the geometrical
model, and function spaces, formulations, resolutions and post-processings
in files independent of the geometrical model.
@item
Use @code{All} as soon as possible in the definition of topological
entities used as @code{Entity} of @code{BasisFunction}s.
This will prevent GetDP from constructing unnecessary lists of entities.
@item
Intentionally misspelling an object type in the problem definition
structure will produce an error message listing all available types in
the particular context.
@item
If you don't specify the mandatory arguments on the command line, GetDP will
give you the available choices. For example, 'getdp test -pos' (the name of
the PostOperation is missing) will produce an error message listing all
available PostOperations.
@end itemize

@c =========================================================================
@c Version history
@c =========================================================================

@node Version history, Copyright and credits, Tips and tricks, Top
@appendix Version history

@cindex Versions
@cindex History, versions
@cindex Changelog

@verbatiminclude ../../CHANGELOG.txt

@c =========================================================================
@c Copyright and credits
@c =========================================================================

@node Copyright and credits, License, Version history, Top
@appendix Copyright and credits

@cindex Copyright
@cindex Acknowledgments
@cindex Contributors, list
@cindex Credits

@verbatiminclude ../../CREDITS.txt

@c =========================================================================
@c License
@c =========================================================================

@node License, Concept index, Copyright and credits, Top
@appendix License

@cindex License

@verbatiminclude ../../LICENSE.txt

@c =========================================================================
@c Concept Index (cindex)
@c =========================================================================

@node Concept index, Metasyntactic variable index, License, Top
@unnumbered Concept index

@cindex Index, concepts
@cindex Concepts, index

@printindex cp

@c =========================================================================
@c Variable Index (vindex)
@c =========================================================================

@node Metasyntactic variable index, Syntax index, Concept index, Top
@unnumbered Metasyntactic variable index

@cindex Index, metasyntactic variables
@cindex Variables, index
@cindex Metasyntactic variables, index

@printindex vr

@c =========================================================================
@c Syntax Index (tindex+findex)
@c =========================================================================

@node Syntax index,  , Metasyntactic variable index, Top
@unnumbered Syntax index

@cindex Index, syntax
@cindex Syntax, index
@cindex Keywords, index

@printindex tp

@bye
