\input texinfo.tex @c -*-texinfo-*-
@c $Id: getdp.texi,v 1.79 2005/08/06 08:30:57 geuzaine Exp $
@c
@c Copyright (C) 1997-2005 P. Dular, C. Geuzaine
@c
@c This program is free software; you can redistribute it and/or modify
@c it under the terms of the GNU General Public License as published by
@c the Free Software Foundation; either version 2 of the License, or
@c (at your option) any later version.
@c
@c This program is distributed in the hope that it will be useful,
@c but WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with this program; if not, write to the Free Software
@c Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
@c USA.
@c 
@c Please report all bugs and problems to <getdp@geuz.org>.
@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
@set EDITION        4.2
@set GETDP-VERSION  1.1
@set GETDP-WEB      @uref{http://www.geuz.org/getdp/}
@set GMSH-WEB       @uref{http://www.geuz.org/gmsh/}
@set COPYRIGHT      @copyright{} 1997-2005 Patrick Dular, Christophe Geuzaine
@c
@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 edition @value{EDITION} (@today{}) of the @cite{GetDP Reference
Manual}, for GetDP @value{GETDP-VERSION}.
@noindent
Copyright @value{COPYRIGHT}
@noindent
University of Li@`ege @*
Department of Electrical Engineering @*
Institut d'@'Electricit@'e Montefiore @*
Sart Tilman Campus, Building B28 @*
B-4000 Li@`ege @*
BELGIUM @*
@end ifinfo

@c =========================================================================
@c TeX directives
@c =========================================================================

@iftex
@global@let@sl=@it
@global@setfont@indit@itshape{9}{1000}
@end iftex

@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 Edition @value{EDITION} (@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 =========================================================================

@summarycontents
@contents

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

@ifnottex
@node Top, Copying conditions, (dir), (dir)
@top GetDP

Patrick Dular and Christophe Geuzaine

GetDP is a scientific computation software for the numerical solution of
integro-differential equations, using finite element and integral type
methods. This is edition @value{EDITION} (@today{}) of the @cite{GetDP
Reference Manual}, for GetDP @value{GETDP-VERSION}.
@end ifnottex

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

@menu
* Copying conditions::          Terms and conditions of use.
* Introduction::                What is GetDP?
* Overview::                    Quick overview of the general philosophy of GetDP.
* 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.
* Running GetDP::               How to run GetDP on your operating system.
* File formats::                Input and output file formats.
* Bugs and versions::           Contact information and ChangeLog
* Tips and tricks::             Some tips to make your life easier with GetDP.
* Frequently asked questions::  The GetDP FAQ
* Gmsh examples::               Sample Gmsh input files.
* 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.

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

Introduction

* Research::                    
* Education::                   
* Industry::                    
* How to Read this Manual::     

Overview

* Numerical tools as objects::  
* Syntactic rules::             
* Comments::                    
* Includes::                    
* Which problems can GetDP actually solve?::  

Expressions 

* Expression definition::       
* Constants::                   
* Operators::                   
* Functions::                   
* Current values::              
* Arguments::                   
* Registers::                   
* Fields::                      
* Loops and conditionals::      

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

Bugs, versions and credits

* Bugs::                        
* Versions::                    
* Credits::                     

@end detailmenu
@end menu

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

@node Copying conditions, Introduction, Top, Top
@unnumbered Copying conditions

@cindex Copyright
@cindex License

@include copying.texi

@c =========================================================================
@c Introduction
@c =========================================================================

@node Introduction, Overview, Copying conditions, Top
@unnumbered Introduction

@cindex Introduction

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

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

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

@menu
* Research::                    
* Education::                   
* Industry::                    
* How to Read this Manual::     
@end menu

@c -------------------------------------------------------------------------
@c Research and Collaboration Activities
@c -------------------------------------------------------------------------

@node Research, Education, Introduction, Introduction
@heading Research and collaboration activities

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

@c -------------------------------------------------------------------------
@c Education and Training Activities
@c -------------------------------------------------------------------------

@node Education, Industry, Research, Introduction
@heading Education and training activities

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

@c -------------------------------------------------------------------------
@c Industrial studies
@c -------------------------------------------------------------------------

@node Industry, How to Read this Manual, Education, Introduction
@heading Industrial studies

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


@c -------------------------------------------------------------------------
@c How to Read this Manual
@c -------------------------------------------------------------------------

@node How to Read this Manual,  , Industry, Introduction
@heading How to read this manual

@cindex Reading, guidelines

After reading @ref{Overview}, and @ref{Expressions}, which depict the
general concepts and the way to construct simple expressions in GetDP, you
can safely (during a first reading) skip @ref{Objects} and @ref{Types for
objects} and directly go to @ref{Short examples}. This chapter gives simple
examples of the problem definition syntax used to define the discrete
problems. For each example, you should then go back to @ref{Objects}, and
@ref{Types for objects}, and have a detailed view of the syntax of the
objects appearing in it. Note that indexes for many concepts and for all the
syntax elements are available at the end of this manual.

Once the examples presented in @ref{Short examples}, are understood, you may
start to use GetDP on your computer (@pxref{Running GetDP}), for example by
solving the complete examples presented in @ref{Complete examples}. Other
ready-to-use example files can be downloaded from the web site.

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

@node Overview, Expressions, Introduction, Top
@chapter Overview

@cindex Overview
@cindex Objects, overview
@cindex Tools, overview
@cindex Numerical tools, overview

@menu
* Numerical tools as objects::  
* Syntactic rules::             
* Comments::                    
* Includes::                    
* Which problems can GetDP actually solve?::  
@end menu

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

@node Numerical tools as objects, Syntactic rules, 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 treatments of defined problems.


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

@node Syntactic rules, Comments, Numerical tools as objects, Overview
@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 Comments
@c -------------------------------------------------------------------------

@node Comments, Includes, Syntactic rules, Overview
@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 file 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

These commands won't have the described effects inside double quotes or
inside GetDP keywords.

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

@node Includes, Which problems can GetDP actually solve?, Comments, Overview
@section Includes

@cindex Includes
@cindex File, include

@tindex Include
@tindex #include

Files can be included by placing one of the following commands
(@var{expression-char} represents a file name) on a separate line, and
outside any GetDP object.  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 Which Problems can GetDP actually solve?
@c -------------------------------------------------------------------------

@node Which problems can GetDP actually solve?,  , Includes, 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.


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

@node Expressions, Objects, Overview, Top
@chapter Expressions 

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

@menu
* Expression definition::       
* Constants::                   
* Operators::                   
* Functions::                   
* Current values::              
* Arguments::                   
* Registers::                   
* Fields::                      
* Loops and conditionals::      
@end menu

@node Expression definition, Constants, Expressions, Expressions
@section 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{register-value-set} |
  @var{register-value-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-value-set}, @var{register-value-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 =

@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} > ]
@end example

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} ] |
  ListAlt[ @var{constant-id}, @var{constant-id} ] |
  LinSpace[ @var{expression-cst}, @var{expression-cst}, @var{expression-cst} ] |
  LogSpace[ @var{expression-cst}, @var{expression-cst}, @var{expression-cst} ]
@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 last two cases permit
to create linear and logarithmic lists of numbers, respectively.

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} > 
                   @var{string-id} < = "@var{string}" > <,@dots{}> ]; |
  @var{constant-id} = @var{constant-def}; |
  @var{string-id} = @var{string-def}; |
  Printf("@var{string}"); |
  Printf("@var{string}", @var{expression-cst-list}); |
  Read(@var{constant-id}); |
  Read(@var{constant-id})[@var{expression-cst}];
@end example

@noindent with

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

@var{constant-def}:
  @var{expression-cst-list-item} |
  @{ @var{expression-cst-list} @} |
  ListFromFile [ @var{expression-char} ]

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

@var{string-def}:
  "@var{string}" |
  Str[ @var{expression-char} ] |
  StrCat[ @var{expression-char}, @var{expression-char} ]
@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
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).
@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} , @var{expression-char} ] |
  Sprintf( @var{expression-char} ) |
  Sprintf( @var{expression-char}, @var{expression-cst-list} ) |
  Date
@end example

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

@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 ?:


@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.
@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 ?:
@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 $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 are a special kind of arguments (@pxref{Arguments}) which
return the current integer or 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 $Iteration
Number of the current iteration 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}).
@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


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

@node Arguments, 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 Registers
@c -------------------------------------------------------------------------

@node Registers, Fields, Arguments, Expressions
@section Registers

@cindex Registers, definition

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

@tindex #@var{integer}

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

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

@var{register-value-get}:
  #@var{integer}
@end example

@noindent Thus, to store any part of an 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, Loops and conditionals, 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.

@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 dInv
d^(-1): applied to a p-form, gives a (p-1)-form.

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

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

@item DivInv
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 Loops and conditionals
@c -------------------------------------------------------------------------

@node Loops and conditionals,  , Fields, Expressions
@section Loops and conditionals

@cindex Loops
@cindex Conditionals

@vindex @var{loop}

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

@var{loop}:

@ftable @code
@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{Endif} is evaluated if @var{expression-cst} is non-zero.

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

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

@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
this.


@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 =

@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{integer}@}> = @var{group-def}; > @dots{}
  < @var{group-id} <@{<#>@var{integer}@}> += @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 | OnOneSideOf | @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
Multidefinition: @code{@var{group-id}@{#@var{n}@} = @var{group-def}}
defines the groups @code{@var{group-id}@{@var{i}@}},
@var{i}=1, @dots{}, @var{n}, by replacing for each @var{i} any
@code{@var{group-id}@{@}} in @var{group-def} with
@code{@var{group-id}@{@var{i}@}}.
@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{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 optional @var{group-def} in brackets must be of @code{Region} type, and
indicates on which region the (piecewise) function is defined. 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.
@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 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 @{
  @{ Name @var{constraint-id} <@{#@var{integer}@}>; 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
Multidefinition: @code{Name @var{constraint-id}@{#@var{n}@}} defines
the constraints @code{@var{constraint-id}@{@var{i}@}},
@var{i}=1, @dots{}, @var{n}, replacing for each @var{i} any
@code{@var{group-id}@{@}} in @var{group-def}s of @code{Case}
fields with @var{group-id}@{@var{i}@}.
@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 Name
@tindex Type
@tindex BasisFunction
@tindex NameOfCoef
@tindex Function
@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 @{
  @{ Name @var{function-space-id} <@{#@var{integer}@}>;
    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{integer}@}; 
             Group @var{group-def}; Resolution @var{resolution-id} @{@} @} >;
       Support @var{group-def}; Entity @var{group-def}; @} @dots{}
    @}
  < SubSpace @{ 
     @{ 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 @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
Multidefinition: @code{Name @var{function-space-id}@{#@var{n}@}} defines
the function spaces @code{@var{function-space-id}@{@var{i}@}},
@var{i}=1, @dots{}, @var{n}, replacing for each @var{i} any @code{@{@}} in
@var{group-def}s of @code{BasisFunction} field and in 
@var{constraint-id}@code{@{@}} of @code{Constraint} field with @{@var{i}@}.
@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
Piecewise defined basis functions: 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
Constraint: a constraint is associated with geometrical entities defined by 
an automatically created @code{Group} of type @var{group-type}, 
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
Function: 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.
@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 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 @{
  @{ 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 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 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 @{
  @{ 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

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 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 @{
  @{ Name @var{formulation-id} <@{#@var{integer}@}>; 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}; @} > @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}:
  Galerkin | deRham

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

@var{term-op-type}:
  Dt | DtDt | JacNL | @var{etc}
@end example

@noindent Note:
@enumerate
@item
Multidefinition: @code{Name @var{formulation-id}@{#@var{n}@}} defines
the formulations @code{@var{formulation-id}@{@var{i}@}},
@var{i}=1, @dots{}, @var{n}, replacing for each @var{i} any @code{@{@}} in
@var{function-space-id}@code{@{@}} of @code{Quantity} field and in
@var{group-def}s of @code{Equation} field with @{@var{i}@}.
@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.
@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 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 @{
  @{ Name @var{resolution-id} <@{#@var{integer}@}>; 
    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
Multidefinition: @code{Name @var{resolution-id}@{#@var{n}@}} defines the
resolutions @code{@var{resolution-id}@{@var{i}@}}, @var{i}=1, @dots{},
@var{n}, replacing for each @var{i} any @code{@{@}} in
@var{formulation-id}@code{@{@}} of @code{System} field with @{@var{i}@}.
@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 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 @{
  @{ Name @var{post-processing-id} <@{#@var{integer}@}>; 
    NameOfFormulation @var{formulation-id} <@{@}>; < NameOfSystem @var{system-id}; >
    Quantity @{
      @{ Name @var{post-quantity-id}; Value @{ @var{post-value} @dots{} @} @} @dots{}
      < @var{loop} > @dots{}
    @}
  @} @dots{}
  < @var{affectation} > @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
Multidefinition: @code{Name @var{post-processing-id}@{#@var{n}@}}
defines the post-processings @code{@var{post-proces@-sing-id}@{@var{i}@}},
@var{i}=1, @dots{}, @var{n}, replacing for each @var{i} any @code{@{@}} in
@var{formulation-id}@code{@{@}} with @{@var{i}@}.
@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 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 @{
  @{ Name @var{post-operation-id}; NameOfPostProcessing @var{post-processing-id}; 
    < Format @var{post-operation-fmt}; > < Append @var{expression-char}; >
    Operation @{ 
      < @var{post-operation-op}; > @dots{} 
    @}
  @} @dots{}
  < @var{affectation} > @dots{}
  < @var{loop} > @dots{}
@} |
PostOperation @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-term}, @var{print-support} <,@var{print-option}> @dots{} ] |
  Print[ "@var{string}", @var{expression} <,@var{print-option}> @dots{} ] |
  Print[ "@var{string}", Str[ @var{expression-char} ] <,@var{print-option}> @dots{} ] |
  Echo[ "@var{string}" <,@var{print-option}> @dots{} ] |
  PrintGroup[ @var{group-id}, @var{print-support} <,@var{print-option}> @dots{} ] |
  < @var{loop} > @dots{}
  @var{etc}

@var{post-quantity-term}:
  @var{post-quantity-id} <[@var{group-def}]> |
  @var{post-quantity-id} @var{post-quantity-op} @var{post-quantity-id}[@var{group-def}] |
  @var{post-quantity-id}[@var{group-def}] @var{post-quantity-op} @var{post-quantity-id}

@var{post-quantity-op}:
  + | - | * | /

@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
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 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}.
@item
The @var{post-quantity-op} allows the simple combination of space-dependent
quantities (@var{post-quantity-id}) with global integral quantities
(@code{@var{post-quantity-id}[@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} > ]
@end example

@noindent
@code{@var{group-type} < @var{group-sub-type} >}:
@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}) >.

@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 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 math
library, and always return real-valued expressions. These are the only
functions allowed in constant expressions (@var{expression-cst}, see
@ref{Constants}).

@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].

@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].

@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].

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

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

@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 @var{expression}.

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

Absolute value of @var{expression}.

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

@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 TTrace
@code{[@var{expression}]}

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

@item F_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[w],Sin[w]]}.

@item F_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[w],-Cos[w]]}.

@item F_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}[.

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

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

Creates a second-rank tensor of order 3 from 3 vectors.

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

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

@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 F_CompElementNum
@code{[]}

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

@item InterpolationLinear
@code{[]@{@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-cst-list}@}}

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

@item InterpolationAkima
@code{[]@{@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-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}.

@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 analysis).

@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 1
unit 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] ;
    @}
  @}
@}
@end example

In this example, @code{Function} defines the mapping that translates the
geometrical elements in the region @code{Left} by 1 along the X-axis, so
that they correspond with the elements in the region @code{Right}. For this
mapping to work, the meshes of @code{Left} and @code{Right} must be
identical.

@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}, 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 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 Galerkin
Integral of 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.

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

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

@item JacNL
Jacobian term to be assembled in the Jacobian matrix 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 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}).

@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}.

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

Generate iteration matrices separately for system @var{system-id}. It is
destined to be used with @code{Update} in order to create more efficiently
the actual system to solve (this is only useful in linear transient problems
with one single excitation) or with @code{EigenSolve} in order to generate
the matrices of a (generalized) eigenvalue problem.

@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 Update
@code{[@var{system-id}, @var{expression}]}

Update the system of equations @var{system-id} (built from iteration
matrices generated separately with @code{GenerateSeparate}) with
@var{expression}

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

Not documented yet.
@c Update the constraint of type @var{constraint-type} acting on @var{group-id}
@c during the processing.

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

Initialize the solution of @var{system-id} to zero (default) or to the
values given in a @code{Constraint} of @code{Init} type.

@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 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 TransferInitSolution
@code{[@var{system-id}]}

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

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

Evaluate @var{expression}.

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

Change the current time.

@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 If
@code{[@var{expression}] @{ @var{resolution-op} @}} 

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

@item If
@code{[@var{expression}] @{ @var{resolution-op} @}} 
@itemx Else
@code{@{ @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 Break

Not implemented yet.

@item Print
@code{[ @{ @var{expression-list} @}, < File @var{expression-char} > ]}

Print the expressions listed in @var{expression-list}.

@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}]}

Eigenvalue/eigenvector computation using Arpack. 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).

@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 computation of a discrete 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}), the list of frequencies to consider in the discrete Fourier
transform. 

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

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

@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 relaxation factor (multiplies
the iterative correction @var{dx}) and the relative error to achieve. The
optional parameter is a flag for testing purposes.

@item PostOperation
@code{[@var{post-operation-id}]}

Perform the specified @code{PostOperation}.

@c todo:

@c @item Perturbation 

@c @item ChangeOfCoordinates

@c @item SaveMesh

@c @item DeformeMesh

@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 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 Skin
Computes the result on the boundary of the region. 

@item Smoothing
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 LastTimeStepOnly

Outputs results for the last time step only (useful when calling a
@code{PostOperation} directly in a @code{Resolution}, for example).

@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 Store
@code{@var{expression-cst}}

Stores the result of an @code{OnRegion} post-processing operation in the
register @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 the documentation of Gmsh (@value{GMSH-WEB}) 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 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 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{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.

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[] = F_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 @{ 
      Galerkin @{ [ epsr[] * Dof@{Grad v@} , @{Grad v@} ];
                 In Domain; Jacobian Vol; Integration Int_1; @}
    @}
  @}
@}
@end example

@noindent
The density of the @code{Galerkin} 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 @{ 
      Galerkin @{ [ 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 @{ 
      Galerkin @{ [ nu[] * Dof@{Curl a@} , @{Curl a@} ];
                 In Domain; Jacobian Vol; Integration Int_1; @}
      Galerkin @{ [ - 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 @{ 
      Galerkin @{ Dt [ mu[] * Dof@{h@} , @{h@} ];
                 In Domain; Jacobian Vol; Integration Int_1; @}
      Galerkin @{ [ 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 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, Running GetDP, Short examples, Top
@chapter Complete examples

@cindex Complete examples
@cindex Examples, complete

@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


An elementary electrostatic problem is first considered.  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}), of which the geometry is defined in the file
@file{mStrip.geo}: see @ref{Gmsh examples}. The geometry is two-dimensional;
one half of the structure is considered by symmetry.

@image{Strip,,}

The structure of the following files points out the separation of the
data describing the particular problem and the method used to solve it,
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

A magnetostatic problem is considered.  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}), of
which the geometry is defined in file @file{Core.geo} (@pxref{Gmsh
examples}).  The geometry is two-dimensional; one fourth of the
structure is considered by symmetry.

@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


A magnetodynamic problem is considered.  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 the previous
section).  It is applied to a core-inductor system (defined in file
@file{CoreMassive.pro}), of which the geometry has already been defined in
file @file{Core.geo} (giving file @file{Core.msh} with Gmsh; @pxref{Input
file format}).

The jacobian and integration methods used are defined in the same file
as in the electrostatic problem in @ref{Electrostatic problem}.

@sp 1

@verbatiminclude CoreMassive.pro

@sp 1

@verbatiminclude MagDyn_av_2D.pro

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

@node Running GetDP, File formats, Complete examples, 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
@value{GMSH-WEB}). 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 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 an 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 @var{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 -ipos
@var{post-processing-id} @dots{}

Enters an interactive post-processing mode, permetting to manually type
@code{PostOperation}-like commands. These commands are based on the
@var{PostProcessing} object(s) selected by the @var{post-processing-id}(s).
If @var{post-processing-id} is omitted, the list of available choices is
displayed.

@item -msh
@var{filename}

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

@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 transient problem interrupted before being complete.

@item -solve
@var{resolution-id}

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

@item -adapt
@var{file}

Reads adaptation constraints from file.

@item -order
@var{real}

Specifies the maximum interpolation order.

@item -bin 

Selects binary format for output files.

@item -log

Saves all processing history in a log file (the input file name with an
appended @code{.log} extension).

@item -socket
@var{string}

Communicates through socket @var{string}.

@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 -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 -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 File Formats
@c =========================================================================

@node File formats, Bugs and versions, Running GetDP, Top
@chapter 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 (@value{GMSH-WEB}). The 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

@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 Bugs, versions and credits
@c =========================================================================

@node Bugs and versions, Tips and tricks, File formats, Top
@chapter Bugs, versions and credits

@menu
* Bugs::                        
* Versions::                    
* Credits::                     
@end menu

@c -------------------------------------------------------------------------
@c Bugs
@c -------------------------------------------------------------------------

@node Bugs, Versions, Bugs and versions, Bugs and versions
@section Bugs

@cindex Known bugs
@cindex Bugs, known
@cindex Bugs, reporting
@cindex Reporting bugs
@cindex Authors, e-mail
@cindex E-mail, authors

If you think you have found a bug in GetDP, you can report it by electronic
mail to the GetDP mailing list at @email{getdp@@geuz.org}.  Please send as
precise a description of the problem as you can, including sample input
files that produce the bug (problem definition and mesh files). 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 the @file{TODO} file in the distribution to check the problems we
already know about.

@c -------------------------------------------------------------------------
@c Versions
@c -------------------------------------------------------------------------

@node Versions, Credits, Bugs, Bugs and versions
@section Versions

@cindex Versions
@cindex History, versions
@cindex Changelog

@verbatiminclude ../VERSIONS

@c -------------------------------------------------------------------------
@c Credits
@c -------------------------------------------------------------------------

@node Credits,  , Versions, Bugs and versions
@section Credits

@cindex Acknowledgments
@cindex Contributors, list
@cindex Credits 

@verbatiminclude ../CREDITS

@c =========================================================================
@c Tips ans Tricks
@c =========================================================================

@node Tips and tricks, Frequently asked questions, Bugs and versions, 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 Frequently asked questions
@c =========================================================================

@node Frequently asked questions, Gmsh examples, Tips and tricks, Top
@appendix Frequently asked questions

@cindex Frequently asked questions
@cindex Questions, frequently asked
@cindex FAQ

@verbatiminclude ../FAQ

@c =========================================================================
@c Gmsh Examples
@c =========================================================================

@node Gmsh examples, License, Frequently asked questions, 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 @value{GMSH-WEB}.

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 License
@c =========================================================================

@node  License, Concept index, Gmsh examples, Top
@appendix License

@cindex License

@include license.texi

@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
