START-INFO-DIR-ENTRY * GetDP: (getdp). General finite element solver END-INFO-DIR-ENTRY This is the `GetDP Reference Manual' for GetDP 1.2 (18 March 2006). Copyright (C) 1997-2006 Patrick Dular, Christophe Geuzaine. Short Contents ************** GetDP Copying conditions Introduction Overview Expressions Objects Types for objects Short examples Complete examples Running GetDP File formats Bugs, versions and credits Tips and tricks Frequently asked questions Gmsh examples License Concept index Metasyntactic variable index Syntax index Table of Contents ***************** GetDP Copying conditions Introduction Overview Numerical tools as objects Syntactic rules used in this document Comments Includes Which problems can GetDP actually solve? Expressions Definition Constants Operators Operator types Evaluation order Functions Current values Arguments Registers Fields Loops and conditionals Objects `Group': defining topological entities `Function': defining global and piecewise expressions `Constraint': specifying constraints on function spaces and formulations `FunctionSpace': building function spaces `Jacobian': defining jacobian methods `Integration': defining integration methods `Formulation': building equations `Resolution': solving systems of equations `PostProcessing': exploiting computational results `PostOperation': exporting results Types for objects Types for `Group' Types for `Function' Math functions Extended math functions Green functions Type manipulation functions Coordinate functions Miscellaneous functions Types for `Constraint' Types for `FunctionSpace' Types for `Jacobian' Types for `Integration' Types for `Formulation' Types for `Resolution' Types for `PostProcessing' Types for `PostOperation' Short examples Constant expression examples `Group' examples `Function' examples `Constraint' examples `FunctionSpace' examples Nodal finite element spaces High order nodal finite element space Nodal finite element space with floating potentials Edge finite element space Edge finite element space with gauge condition Coupled edge and nodal finite element spaces Coupled edge and nodal finite element spaces for multiply connected domains `Jacobian' examples `Integration' examples `Formulation' examples Electrostatic scalar potential formulation Electrostatic scalar potential formulation with floating potentials and electric charges Magnetostatic 3D vector potential formulation Magnetodynamic 3D or 2D magnetic field and magnetic scalar potential formulation Nonlinearities, Mixed formulations, ... `Resolution' examples Static resolution (electrostatic problem) Frequency domain resolution (magnetodynamic problem) Time domain resolution (magnetodynamic problem) Nonlinear time domain resolution (magnetodynamic problem) Coupled formulations `PostProcessing' examples `PostOperation' examples Complete examples Electrostatic problem Magnetostatic problem Magnetodynamic problem Running GetDP File formats Input file format Output file format File `.pre' File `.res' Bugs, versions and credits Bugs Versions Credits Tips and tricks Frequently asked questions Gmsh examples License Concept index Metasyntactic variable index Syntax index 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 the `GetDP Reference Manual' for GetDP 1.2 (18 March 2006). Copying conditions ****************** GetDP is "free software"; this means that everyone is free to use it and to redistribute it on a free basis. GetDP is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of GetDP that they might get from you. Specifically, we want to make sure that you have the right to give away copies of GetDP, that you receive source code or else can get it if you want it, that you can change GetDP or use pieces of GetDP in new free programs, and that you know you can do these things. To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of GetDP, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. Also, for our own protection, we must make certain that everyone finds out that there is no warranty for GetDP. If GetDP is modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation. The precise conditions of the license for GetDP are found in the General Public License that accompanies the source code (*note License::). Further information about this license is available from the GNU Project webpage `http://www.gnu.org/copyleft/gpl-faq.html'. Detailed copyright information can be found in *Note Credits::. The source code and various pre-compiled versions of GetDP (for Unix, Windows and Mac OS) can be downloaded from the web site `http://www.geuz.org/getdp/'. If you use GetDP, we would appreciate that you mention it in your work. References and the latest news about GetDP are always available on `http://www.geuz.org/getdp/'. Please send all GetDP-related questions to the public GetDP mailing list at . If you want to integrate GetDP into a closed-source software, or want to sell a modified closed-source version of GetDP, please contact one of the authors. You can purchase a version of GetDP under a different license, with "no strings attached" (for example allowing you to take parts of GetDP and integrate them into your own proprietary code). Introduction ************ GetDP (a "General environment for the treatment of Discrete Problems") is a scientific software environment for the numerical solution of integro-differential equations, open to the coupling of physical problems (electromagnetic, thermal, etc.) as well as of numerical methods (finite element method, integral methods, etc.). It can deal with such problems of various dimensions (1D, 2D or 3D) and time states (static, transient or harmonic). The main feature of GetDP is the closeness between its internal structure (written in C), the organization of data defining discrete problems (written by the user in ASCII data files) and the symbolic mathematical expressions of these problems. Its aim is to be welcoming and of easy use for both development and application levels: it consists of a working environment in which the definition of any problem makes use of a limited number of objects, which makes the environment structured and concise. It therefore gives researchers advanced developing tools and a large freedom in adding new functionalities. The modeling tools provided by GetDP can be tackled at various levels of complexity: this opens the software to a wide range of activities, such as research, collaboration, education, training and industrial studies. Research and collaboration activities ===================================== The internal structure of the software is very close to the structure used to define discrete problems in the input data files. As a result, a unicity and conciseness of both development and application levels is obtained without any interface between them, which facilitates work of any kind--particularly validations. GetDP permits to rapidly develop tools for the comparison of methods and the exchange of solutions between research teams, which is one of the main aims of collaboration. Moreover, after a short training, GetDP could be used by teams as a basis for their own developments, while allowing a large freedom in the latter. Education and training activities ================================= The software environment consists of modeling tools applicable to various physical problems. Education and training can therefore be offered in various domains and at different levels. The closeness between the definition of discrete problems and their symbolic mathematical expressions entails that the theory and mathematical bases of numerical methods, which are essential to anyone who wants to tackle the solving of discrete problems, can be directly followed by their practical applications. These applications can be evolutionary, in the sense that the offered tools are of various levels of complexity. Everyone can tackle, step by step, according to his apprenticeship level, the tools adapted to the solving of more and more complex problems, as well as various methods for the solving of the same problem. Industrial studies ================== The treatment of industrial problems can also be facilitated because GetDP is adapted to the study of a wide range of physical problems using various numerical methods. In particular, adapted made to measure and ready-to-use software could be rapidly developed for given problems. How to read this manual ======================= After reading *Note Overview::, which depicts the general philosophy of GetDP, you might want to skip *Note Expressions::, *Note Objects:: and *Note Types for objects:: and directly run the demo files bundled in the distribution on your computer (*note Running GetDP::). You should then open these examples with a text editor and compare their structure with the examples given in *Note Short examples:: and *Note Complete examples::. For each new syntax element that you fall onto, you can then go back to *Note Expressions::, *Note Objects::, and *Note Types for objects::, and find in these chapters the detailed description of the syntactic rules as well as all the available options. Indexes for many concepts (*note Concept index::) and for all the syntax elements (*note Syntax index::) are available at the end of this manual. Overview ******** Numerical tools as objects ========================== An assembly of computational tools (or objects) in GetDP leads to a problem definition structure, which is a transcription of the mathematical expression of the problem, and forms a text data file: the equations describing a phenomenon, written in a mathematical form adapted to a chosen numerical method, directly constitute data for GetDP. The resolution of a discrete problem with GetDP requires the definition, in a text data file, of the GetDP objects listed (together with their dependencies) in the following figure and table. ---------------------------------------------------------------------------- | | | -------------- | | -------->| Function |-------------------------------- | | | -------------- \ \ | | | | | --------------------------- \ | | | | \ | \ | | | \|/ ------------ | \ \|/ -------------- -------------- | | \ -------------- | Group |-->| Constraint |-------- | | \ |PostOperation | -------------- -------------- | | | \ -------------- | | | || | | | | \ /||\ *********************************************************************************************** * | | | || \|/ \|/\|/ \|/ _\| || * * | | | || -------------- -------------- -------------- -------------- * * | | | =====>|FunctionSpace |==>| Formulation |==>| Resolution |==>|PostProcessing| * * | | | -------------- -------------- -------------- -------------- * * | | | /|\/|\/|\ | /|\/|\/|\/|\ * * | | -------------------------------- | | | | | | | * * | | ----------------- | --------------------------- | | | * * | | | -------------- | | | * * | | | | Integration |---------------------------- | | * * | | | -------------- | | * * | | | | | * * | | -------------- | | * * | ----------->| Jacobian |-------------------------------------------------- | * * | -------------- | * * | | * * ------------------------------------------------------------------------------------ * * * *********************************************************************************************** Group -- Function Group Constraint Group, Function, (Resolution) FunctionSpace Group, Constraint, (Formulation), (Resolution) Jacobian Group Integration -- Formulation Group, Function, (Constraint), FunctionSpace, Jacobian, Integration Resolution Function, Formulation PostProcessing Group, Function, Jacobian, Integration, Formulation, Resolution PostOperation Group, PostProcessing The gathering of all these objects constitutes the problem definition structure, which is a copy of the formal mathematical formulation of the problem. Reading the first column of the table from top to bottom pictures the working philosophy and the linking of operations peculiar to GetDP, from group definition to results visualization. The decomposition highlighted in the figure points out the separation between the objects defining the method of resolution, which may be isolated in a "black box" (bottom) and those defining the data peculiar to a given problem (top). The computational tools which are in the center of a problem definition structure are formulations (`Formulation') and function spaces (`FunctionSpace'). Formulations define systems of equations that have to be built and solved, while function spaces contain all the quantities, i.e., functions, fields of vectors or covectors, known or not, involved in formulations. Each object of a problem definition structure must be defined before being referred to by others. A linking which always respects this property is the following: it first contains the objects defining particular data of a problem, such as geometry, physical characteristics and boundary conditions (i.e., `Group', `Function' and `Constraint') followed by those defining a resolution method, such as unknowns, equations and related objects (i.e., `Jacobian', `Integration', `FunctionSpace', `Formulation', `Resolution' and `PostProcessing'). The processing cycle ends with the presentation of the results (i.e., lists of numbers in various formats), defined in `PostOperation' fields. This decomposition points out the possibility of building black boxes, containing objects of the second group, adapted to treatment of general classes of problems that share the same resolution methods. Syntactic rules used in this document ===================================== Here are the rules we tried to follow when writing this user's guide. Note that metasyntactic variable definitions stay valid throughout all the manual (and not only in the sections where the definitions appear). See *Note Metasyntactic variable index::, for an index of all metasyntactic variables. 1. Keywords and literal symbols are printed like `this'. 2. Metasyntactic variables (i.e., text bits that are not part of the syntax, but stand for other text bits) are printed like THIS. 3. A colon (`:') after a metasyntactic variable separates the variable from its definition. 4. Optional rules are enclosed in `<' `>' pairs. 5. Multiple choices are separated by `|'. 6. Three dots (...) indicate a possible repetition of the preceding rule. 7. For conciseness, the notation `RULE <, RULE > ...' is replaced by `RULE <,...>'. 8. The ETC symbol replaces nonlisted rules. Comments ======== Both C and C++ style comments are supported and can be used in the input data files to comment selected text regions: 1. the text region comprised between `/*' and `*/' pairs is ignored; 2. the rest of a line after a double slash `//' is ignored. Comments cannot be used inside double quotes or inside GetDP keywords. Includes ======== An input data file can be included in another input data file by placing one of the following commands (EXPRESSION-CHAR represents a file name) on a separate line, outside the GetDP objects. Any text placed after an include command on the same line is ignored. `Include EXPRESSION-CHAR' `#include EXPRESSION-CHAR' See *Note Constants::, for the definition of the character expression EXPRESSION-CHAR. Which problems can GetDP actually solve? ======================================== The preceding explanations may seem very (too) general. Which are the problems that GetDP can actually solve? To answer this question, here is a list of methods that we have considered and coupled until now: Numerical methods finite element method boundary element method (experimental, undocumented) volume integral methods (experimental, undocumented) Geometrical models one-dimensional models (1D) two-dimensional models (2D), plane and axisymmetric three-dimensional models (3D) Time states static states sinusoidal and harmonic states transient states eigenvalue problems These methods have been successfully applied to build coupled physical models involving electromagnetic phenomena (magnetostatics, magnetodynamics, electrostatics, electrokinetics, electrodynamics, wave propagation, lumped electric circuits), acoustic phenomena, thermal phenomena and mechanical phenomena (elasticity, rigid body movement). As can be guessed from the preceding list, GetDP has been initially developed in the field of computational electromagnetics, which fully uses all the offered coupling features. We believe that this does not interfere with the expected generality of the software because a particular modeling forms a problem definition structure which is totally external to the software: GetDP offers computational tools; the user freely applies them to define and solve his problem. Nevertheless, specific numerical tools will _always_ need to be implemented to solve specific problems in areas other than those mentionned above. If you think the general phisosophy of GetDP is right for you and your problem, but you discover that GetDP lacks the tools necessary to handle it, let us know: we would love to discuss it with you. For example, at the time of this writing, many areas of GetDP would need to be improved to make GetDP as useful for computational mechanics or computational fluid dynamics as it is for computational electromagnetics... So if you have the skills and some free time, feel free to join the project: we gladly accept all code contributions! Expressions *********** This chapter and the next two describe in a rather formal way all the commands that can be used in the ASCII text input files. If you are just beginning to use GetDP, or just want to see what GetDP is all about, you should skip this chapter and the next two for now, have a quick look at *Note Running GetDP::, and run the demo problems bundled in the distribution on your computer. You should then open the `.pro' files in a text editor and compare their structure with the examples given in *Note Short examples:: and *Note Complete examples::. Once you have a general idea of how the files are organized, you might want to come back here to learn more about the specific syntax of all the objects, and all the available options. Definition ========== Expressions are the basic tool of GetDP. They cover a wide range of functional expressions, from constants to formal expressions containing functions (built-in or user-defined, depending on space and time, etc.), arguments, discrete quantities and their associated differential operators, etc. Note that `white space' (spaces, tabs, new line characters) is ignored inside expressions (as well as inside all GetDP objects). Expressions are denoted by the metasyntactic variable EXPRESSION (remember the definition of the syntactic rules in *Note Syntactic rules::): EXPRESSION: ( EXPRESSION ) | INTEGER | REAL | CONSTANT-ID | QUANTITY | ARGUMENT | CURRENT-VALUE | REGISTER-VALUE-SET | REGISTER-VALUE-GET | OPERATOR-UNARY EXPRESSION | EXPRESSION OPERATOR-BINARY EXPRESSION | EXPRESSION OPERATOR-TERNARY-LEFT EXPRESSION OPERATOR-TERNARY-RIGHT EXPRESSION | BUILT-IN-FUNCTION-ID [ < EXPRESSION-LIST > ] < { EXPRESSION-CST-LIST } > | FUNCTION-ID [ < EXPRESSION-LIST > ] | < Real | Complex > [ EXPRESSION ] | Dt [ EXPRESSION ] | AtAnteriorTimeStep [ EXPRESSION, INTEGER ] | Order [ QUANTITY ] | Trace [ EXPRESSION, GROUP-ID ] | EXPRESSION ##INTEGER The following sections introduce the quantities that can appear in expressions, i.e., constant terminals (INTEGER, REAL) and constant expression identifiers (CONSTANT-ID, EXPRESSION-CST-LIST), discretized fields (QUANTITY), arguments (ARGUMENT), current values (CURRENT-VALUE), register values (REGISTER-VALUE-SET, REGISTER-VALUE-GET), operators (OPERATOR-UNARY, OPERATOR-BINARY, OPERATOR-TERNARY-LEFT, OPERATOR-TERNARY-RIGHT) and built-in or user-defined functions (BUILT-IN-FUNCTION-ID, FUNCTION-ID). The last seven cases in this definition permit to cast an expression as real or complex, get the time derivative or evaluate an expression at an anterior time step, retrieve the interpolation order of a discretized quantity, evaluate the trace of an expression, and print the value of an expression for debugging purposes. List of expressions are defined as: EXPRESSION-LIST: EXPRESSION <,...> Constants ========= The three constant types used in GetDP are INTEGER, REAL and STRING. These types have the same meaning and syntax as in the C or C++ programming languages. Besides general expressions (EXPRESSION), purely constant expressions, denoted by the metasyntactic variable EXPRESSION-CST, are also used: EXPRESSION-CST: ( EXPRESSION-CST ) | INTEGER | REAL | CONSTANT-ID | OPERATOR-UNARY EXPRESSION-CST | EXPRESSION-CST OPERATOR-BINARY EXPRESSION-CST | EXPRESSION-CST OPERATOR-TERNARY-LEFT EXPRESSION-CST OPERATOR-TERNARY-RIGHT EXPRESSION-CST | MATH-FUNCTION-ID [ < EXPRESSION-CST-LIST > ] List of constant expressions are defined as: EXPRESSION-CST-LIST: EXPRESSION-CST-LIST-ITEM <,...> with EXPRESSION-CST-LIST-ITEM: EXPRESSION-CST | EXPRESSION-CST : EXPRESSION-CST | EXPRESSION-CST : EXPRESSION-CST : EXPRESSION-CST | CONSTANT-ID {} | CONSTANT-ID { EXPRESSION-CST-LIST } | List[ CONSTANT-ID ] | ListAlt[ CONSTANT-ID, CONSTANT-ID ] | LinSpace[ EXPRESSION-CST, EXPRESSION-CST, EXPRESSION-CST ] | LogSpace[ EXPRESSION-CST, EXPRESSION-CST, EXPRESSION-CST ] The second case in this last definition permits to create a list containing the range of numbers comprised between the two EXPRESSION-CST, with a unit incrementation step. The third case also permits to create a list containing the range of numbers comprised between the two EXPRESSION-CST, but with a positive or negative incrementation step equal to the third EXPRESSION-CST. The fourth and fifth cases permit to reference constant identifiers (CONSTANT-IDs) of lists of constants and constant identifiers of sublists of constants (see below for the definition of constant identifiers) . The sixth case is a synonym for the fourth. The seventh case permits to create alternate lists: the arguments of `ListAlt' must be CONSTANT-IDs of lists of constants of the same dimension. The result is an alternate list of these constants: first constant of argument 1, first constant of argument 2, second constant of argument 1, etc. These kinds of lists of constants are for example often used for function parameters (*note Functions::). The last two cases permit to create linear and logarithmic lists of numbers, respectively. Contrary to a general EXPRESSION which is evaluated at runtime (thanks to an internal stack mechanism), an EXPRESSION-CST is completely evaluated during the syntactic analysis of the problem (when GetDP reads the `.pro' file). The definition of such constants or lists of constants with identifiers can be made outside or inside any GetDP object. The syntax for the definition of constants is: AFFECTATION: DefineConstant [ CONSTANT-ID < = EXPRESSION-CST > STRING-ID < = "STRING" > <,...> ]; | CONSTANT-ID = CONSTANT-DEF; | STRING-ID = STRING-DEF; | Printf("STRING"); | Printf("STRING", EXPRESSION-CST-LIST); | Read(CONSTANT-ID); | Read(CONSTANT-ID)[EXPRESSION-CST]; with CONSTANT-ID: STRING | STRING ~ { EXPRESSION-CST } CONSTANT-DEF: EXPRESSION-CST-LIST-ITEM | { EXPRESSION-CST-LIST } | ListFromFile [ EXPRESSION-CHAR ] STRING-ID: STRING | STRING ~ { EXPRESSION-CST } STRING-DEF: "STRING" | Str[ EXPRESSION-CHAR ] | StrCat[ EXPRESSION-CHAR, EXPRESSION-CHAR ] Notes: 1. Five constants are predefined in GetDP: `Pi' (3.1415926535897932), `0D' (0), `1D' (1), `2D' (2) and `3D' (3). 2. When `~{EXPRESSION-CST}' is appended to a string STRING, the result is a new string formed by the concatenation of STRING, `_' (an underscore) and the value of the EXPRESSION-CST. This is most useful in loops (*note Loops and conditionals::), where it permits to define unique strings automatically. For example, For i In {1:3} x~{i} = i; EndFor is the same as x_1 = 1; x_2 = 2; x_3 = 3; 3. The assignment in `DefineConstant' (zero if no EXPRESSION-CST is given) is performed only if CONSTANT-ID has not yet been defined. This kind of explicit default definition mechanism is most useful in general problem definition structures making use of a large number of generic constants, functions or groups. When exploiting only a part of a complex problem definition structure, the default definition mechanism allows to define the quantities of interest only, the others being assigned a default value (that will not be used during the processing but that avoids the error messages produced when references to undefined quantities are made). See *Note Constant expression examples::, as well as *Note Function examples::, for some examples. Character expressions are defined as follows: EXPRESSION-CHAR: "STRING" | STRING-ID | StrCat[ EXPRESSION-CHAR , EXPRESSION-CHAR ] | Sprintf( EXPRESSION-CHAR ) | Sprintf( EXPRESSION-CHAR, EXPRESSION-CST-LIST ) | Date The third case in this definition permits to concatenate two character expressions; the next two cases permit to print the value of variables using standard C formatting; the last case permits to access the current date. Operators ========= Operator types -------------- The operators in GetDP are similar to the corresponding operators in the C or C++ programming languages. OPERATOR-UNARY: `-' Unary minus. `!' Logical not. OPERATOR-BINARY: `^' Exponentiation. The evaluation of the both arguments must result in a scalar value. `*' Multiplication or scalar product, depending on the type of the arguments. `/\' Cross product. The evaluation of both arguments must result in vectors. `/' Division. `%' Modulo. The evaluation of the second argument must result in a scalar value. `+' Addition. `-' Subtraction. `==' Equality. `!=' Inequality. `>' Greater. The evaluation of both arguments must result in scalar values. `>=' Greater or equality. The evaluation of both arguments must result in scalar values. `<' Less. The evaluation of both arguments must result in scalar values. `<=' Less or equality. The evaluation of both arguments must result in scalar values. `&&' Logical `and'. The evaluation of both arguments must result in scalar values. `||' Logical `or'. The evaluation of both arguments must result in floating point values. Warning: the logical `or' always (unlike in C or C++) implies the evaluation of both arguments. That is, the second operand of `||' is evaluated even if the first one is true. OPERATOR-TERNARY-LEFT: `?' OPERATOR-TERNARY-RIGHT: `:' The only ternary operator, formed by OPERATOR-TERNARY-LEFT and OPERATOR-TERNARY-RIGHT is defined as in the C or C++ programming languages. The ternary operator first evaluates its first argument (the EXPRESSION-CST located before the `?'), which must result in a scalar value. If it is true (non-zero) the second argument (located between `?' and `:') is evaluated and returned; otherwise the third argument (located after `:') is evaluated and returned. Evaluation order ---------------- The evaluation priorities are summarized below (from stronger to weaker, i.e., `^' has the highest evaluation priority). Parentheses `()' may be used anywhere to change the order of evaluation. `^' `- (unary), !' `/\' `*, /, %' `+, -' `<, >, <=, >=' `!=, ==' `&&, ||' `?:' Functions ========= Two types of functions coexist in GetDP: user-defined functions (FUNCTION-ID, see *Note Function::) and built-in functions (BUILT-IN-FUNCTION-ID, defined in this section). Both types of functions are always followed by a pair of brackets `[]' that can possibly contain arguments (*note Arguments::). This makes it simple to distinguish a FUNCTION-ID or a BUILT-IN-FUNCTION-ID from a CONSTANT-ID. As shown below, built-in functions might also have parameters, given between braces `{}', and which are completely evaluated during the analysis of the syntax (since they are of EXPRESSION-CST-LIST type): BUILT-IN-FUNCTION-ID [ < EXPRESSION-LIST > ] < { EXPRESSION-CST-LIST } > with BUILT-IN-FUNCTION-ID: MATH-FUNCTION-ID | EXTENDED-MATH-FUNCTION-ID | GREEN-FUNCTION-ID | TYPE-FUNCTION-ID | COORD-FUNCTION-ID | MISC-FUNCTION-ID Notes: 1. All possible values for BUILT-IN-FUNCTION-ID are listed in *Note Types for Function::. 2. Classical mathematical functions (*note Math functions::) are the only functions allowed in a constant definition (see the definition of EXPRESSION-CST in *Note Constants::). Current values ============== Current values are a special kind of arguments (*note Arguments::) which return the current integer or floating point value of an internal GetDP variable: `$Time' Value of the current time. This value is set to zero for non time dependent analyses. `$DTime' Value of the current time increment used in a time stepping algorithm. `$Theta' Current theta value in a theta time stepping algorithm. `$TimeStep' Number of the current time step in a time stepping algorithm. `$Iteration' Number of the current iteration in a nonlinear loop. `$EigenvalueReal' Real part of the current eigenvalue. `$EigenvalueImag' Imaginary part of the current eigenvalue. `$X, $XS' Value of the current (destination or source) X-coordinate. `$Y, $YS' Value of the current (destination or source) Y-coordinate. `$Z, $ZS' Value of the current (destination or source) Z-coordinate. `$A, $B, $C' Value of the current parametric coordinates used in the parametric `OnGrid' `PostOperation' (*note Types for PostOperation::). Note: 1. The current X, Y and Z coordinates refer to the `physical world' coordinates, i.e., coordinates in which the mesh is expressed. Arguments ========= Function arguments can be used in expressions and have the following syntax (INTEGER indicates the position of the argument in the EXPRESSION-LIST of the function, starting from 1): ARGUMENT: $INTEGER See *Note Function::, and *Note Function examples::, for more details. Registers ========= In many situations, identical parts of expressions are used more than once. If this is not a problem with constant expressions (since EXPRESSION-CSTs are evaluated only once during the analysis of the problem definition structure, cf. *Note Constants::), it may introduce some important overhead while evaluating complex EXPRESSIONs (which are evaluated at runtime, thanks to an internal stack mechanism). In order to circumvent this problem, the evaluation result of any part of an EXPRESSION can be saved in a register: a memory location where this partial result will be accessible without any costly reevaluation of the partial expression. Registers have the following syntax: REGISTER-VALUE-SET: EXPRESSION#INTEGER REGISTER-VALUE-GET: #INTEGER Thus, to store any part of an expression in the register 5, one should add `#5' directly after the expression. To reuse the value stored in this register, one simply uses `#5' instead of the expression it should replace. See *Note Function examples::, for an example. Fields ====== A discretized quantity (defined in a function space, cf. *Note FunctionSpace::) is represented between braces `{}', and can only appear in well-defined expressions in `Formulation' (*note Formulation::) and `PostProcessing' (*note PostProcessing::) objects: QUANTITY: < QUANTITY-DOF > { < QUANTITY-OPERATOR > QUANTITY-ID } | { < QUANTITY-OPERATOR > QUANTITY-ID } [ EXPRESSION-CST-LIST ] with QUANTITY-ID: STRING | STRING ~ { EXPRESSION-CST } and QUANTITY-DOF: `Dof' Defines a vector of discrete quantities (vector of `D'egrees `o'f `f'reedom), to be used only in `Equation' terms of formulations to define (elementary) matrices. Roughly said, the `Dof' symbol in front of a discrete quantity indicates that this quantity is an unknown quantity, and should therefore not be considered as already computed. `BF' Indicates that only a basis function will be used (only valid with basis functions associated with regions). QUANTITY-OPERATOR: `d' Exterior derivative (d): applied to a P-form, gives a (P+1)-form. `Grad' Gradient: applied to a scalar field, gives a vector. `Curl' `Rot' Curl: applied to a vector field, gives a vector. `Div' Divergence (div): applied to a vector field, gives a scalar. `dInv' d^(-1): applied to a p-form, gives a (p-1)-form. `GradInv' Inverse grad: applied to a gradient field, gives a scalar. `CurlInv' `RotInv' Inverse curl: applied to a curl field, gives a vector. `DivInv' Inverse div: applied to a divergence field. Notes: 1. While the operators `Grad', `Curl' and `Div' can be applied to 0, 1 and 2-forms respectively, the exterior derivative operator `d' is usually preferred with such fields. 2. The second case permits to evaluate a discretized quantity at a certain position X, Y, Z (when EXPRESSION-CST-LIST contains three items) or at a specific time, N time steps ago (when EXPRESSION-CST-LIST contains a single item). Loops and conditionals ====================== Loops and conditionals are defined as follows, and can be imbricated: LOOP: `For ( EXPRESSION-CST : EXPRESSION-CST )' Iterates from the value of the first EXPRESSION-CST to the value of the second EXPRESSION-CST, with a unit incrementation step. At each iteration, the commands comprised between ``For ( EXPRESSION-CST : EXPRESSION-CST )'' and the matching `EndFor' are executed. `For ( EXPRESSION-CST : EXPRESSION-CST : EXPRESSION-CST )' Iterates from the value of the first EXPRESSION-CST to the value of the second EXPRESSION-CST, with a positive or negative incrementation step equal to the third EXPRESSION-CST. At each iteration, the commands comprised between ``For ( EXPRESSION-CST : EXPRESSION-CST : EXPRESSION-CST )'' and the matching `EndFor' are executed. `For STRING In { EXPRESSION-CST : EXPRESSION-CST }' Iterates from the value of the first EXPRESSION-CST to the value of the second EXPRESSION-CST, with a unit incrementation step. At each iteration, the value of the iterate is affected to an expression named STRING, and the commands comprised between ``For STRING In { EXPRESSION-CST : EXPRESSION-CST }'' and the matching `EndFor' are executed. `For STRING In { EXPRESSION-CST : EXPRESSION-CST : EXPRESSION-CST }' Iterates from the value of the first EXPRESSION-CST to the value of the second EXPRESSION-CST, with a positive or negative incrementation step equal to the third EXPRESSION-CST. At each iteration, the value of the iterate is affected to an expression named STRING, and the commands comprised between ``For STRING In { EXPRESSION-CST : EXPRESSION-CST : EXPRESSION-CST }'' and the matching `EndFor' are executed. `EndFor' Ends a matching `For' command. `If ( EXPRESSION-CST )' The body enclosed between ``If ( EXPRESSION-CST )'' and the matching `Endif' is evaluated if EXPRESSION-CST is non-zero. `EndIf' Ends a matching `If' command. Loops and conditionals can be used in any of the following objects: Group, Function, Constraint (as well as in a contraint-case), FunctionSpace, Formulation (as well as in the quantity and equation defintions), Resolution (as well as resolution-term, system defintion and operations), PostProcessing (in the definition of the PostQuantities) and PostOperation (as well as in the operation list). Objects ******* This chapter presents the formal definition of the ten GetDP objects mentioned in *Note Overview::. To be concise, all the possible parameters for these objects are not given here (cf. the ETC syntactic rule defined in *Note Syntactic rules::). Please refer to *Note Types for objects::, for the list of all available options. `Group': defining topological entities ====================================== Meshes (grids) constitute the input data of GetDP. All that is needed by GetDP as a mesh is a file containing a list of nodes (with their coordinates) and a list of geometrical elements with, for each one, a number characterizing its geometrical type (i.e., line, triangle, quadrangle, tetrahedron, hexahedron, prism, etc.), a number characterizing the physical region to which it belongs and the list of its nodes. This minimal input set should be easy to extract from most of the classical mesh file formats (*note Input file format::, for a complete description of the mesh file format read by GetDP). Groups of geometrical entities of various types can be considered and are used in many objects. There are region groups, of which the entities are regions, and function groups, with nodes, edges, facets, volumes, groups of nodes, edges of tree, facets of tree, ... of regions. Amongst region groups, elementary and global groups can be distinguished: elementary groups are relative to single regions (e.g., physical regions in which piecewise defined functions or constraints can be defined) while global groups are relative to sets of regions for which given treatments have to be performed (e.g., domain of integration, support of a function space, etc.). Groups of function type contain lists of entities built on some region groups (e.g., nodes for nodal elements, edges for edge elements, edges of tree for gauge conditions, groups of nodes for floating potentials, elements on one side of a surface for cuts, etc.). A definition of initially empty groups can be obtained thanks to a `DefineGroup' command, so that their identifiers exist and can be referred to in other objects, even if these groups are not explicitly defined. This procedure is similar to the `DefineConstant' procedure introduced for constants in *Note Constants::. The syntax for the definition of groups is: Group { < DefineGroup [ GROUP-ID <{INTEGER}> <,...> ]; > ... < GROUP-ID = GROUP-DEF; > ... < GROUP-ID += GROUP-DEF; > ... < AFFECTATION > ... < LOOP > ... } with GROUP-ID: STRING | STRING ~ { EXPRESSION-CST } GROUP-DEF: GROUP-TYPE [ GROUP-LIST <, GROUP-SUB-TYPE GROUP-LIST > ] | GROUP-ID <{}> | #GROUP-LIST GROUP-TYPE: Region | Global | NodesOf | EdgesOf | ETC GROUP-LIST: All | GROUP-LIST-ITEM | { GROUP-LIST-ITEM <,...> } GROUP-LIST-ITEM: INTEGER | INTEGER : INTEGER | INTEGER : INTEGER : INTEGER | GROUP-ID <{}> GROUP-SUB-TYPE: Not | StartingOn | OnOneSideOf | ETC Notes: 1. INTEGER as a GROUP-LIST-ITEM is the only interface with the mesh; with each element is associated a region number, being this INTEGER, and a geometrical type (*note Input file format::). Ranges of integers can be specified in the same way as ranges of constant expressions in an EXPRESSION-CST-LIST-ITEM (*note Constants::). For example, `I:J' replaces the list of consecutive integers I, I+1, ..., J-1, J. 2. Array of groups: `DefineGroup[GROUP-ID{N}]' defines the empty groups `GROUP-ID{I}', I=1, ..., n. Such a definition is optional, i.e., each `GROUP-ID{I}' can be separately defined, in any order. 3. `#GROUP-LIST' is an abbreviation of `Region[GROUP-LIST]'. See *Note Types for Group::, for the complete list of options and *Note Group examples::, for some examples. `Function': defining global and piecewise expressions ===================================================== A user-defined function can be global in space or piecewise defined in region groups. A physical characteristic is an example of a piecewise defined function (e.g., magnetic permeability, electric conductivity, etc.) and can be simply a constant, for linear materials, or a function of one or several arguments for nonlinear materials. Such functions can of course depend on space coordinates or time, which can be needed to express complex constraints. A definition of initially empty functions can be made thanks to the `DefineFunction' command so that their identifiers exist and can be referred to (but cannot be used) in other objects. The syntax for the definition of functions is: Function { < DefineFunction [ FUNCTION-ID <,...> ]; > ... < FUNCTION-ID [ < GROUP-DEF > ] = EXPRESSION; > ... < AFFECTATION > ... < LOOP > ... } with FUNCTION-ID: STRING Note: 1. The optional GROUP-DEF in brackets must be of `Region' type, and indicates on which region the (piecewise) function is defined. Warning: it is incorrect to write `f[reg1]=1; g[reg2]=f[]+1;' since the domains of definition of `f[]' and `g[]' don't match. See *Note Types for Function::, for the complete list of built-in functions and *Note Function examples::, for some examples. `Constraint': specifying constraints on function spaces and formulations ======================================================================== Constraints can be referred to in `FunctionSpace' objects to be used for boundary conditions, to impose global quantities or to initialize quantities. These constraints can be expressed with functions or be imposed by the pre-resolution of another discrete problem. Other constraints can also be defined, e.g., constraints of network type for the definition of circuit connections, to be used in `Formulation' objects. The syntax for the definition of constraints is: Constraint { { Name CONSTRAINT-ID; Type CONSTRAINT-TYPE; Case { { Region GROUP-DEF; < Type CONSTRAINT-TYPE; > < SubRegion GROUP-DEF; > < TimeFunction EXPRESSION; > < RegionRef GROUP-DEF; > < SubRegionRef GROUP-DEF; > < Coefficient EXPRESSION; > < Function EXPRESSION; > < Filter EXPRESSION; > CONSTRAINT-VAL; } ... < LOOP > ... } | Case CONSTRAINT-CASE-ID { { Region GROUP-DEF; < Type CONSTRAINT-TYPE; > CONSTRAINT-CASE-VAL; } ... < LOOP > ... } ... } ... < AFFECTATION > ... < LOOP > ... } with CONSTRAINT-ID: CONSTRAINT-CASE-ID: STRING | STRING ~ { EXPRESSION-CST } CONSTRAINT-TYPE: Assign | Init | Network | Link | ETC CONSTRAINT-VAL: Value EXPRESSION | NameOfResolution RESOLUTION-ID | ETC CONSTRAINT-CASE-VAL: Branch { INTEGER, INTEGER } | ETC Notes: 1. The constraint type CONSTRAINT-TYPE defined outside the `Case' fields is applied to all the cases of the constraint, unless other types are explicitly given in these cases. The default type is `Assign'. 2. The region type `Region GROUP-DEF' will be the main GROUP-LIST argument of the GROUP-DEF to be built for the constraints of `FunctionSpace's. The optional region type `SubRegion GROUP-DEF' will be the argument of the associated GROUP-SUB-TYPE. 3. EXPRESSION in `Value' of CONSTRAINT-VAL cannot be time dependent (`$Time') because it is evaluated only once during the pre-processing (for efficiency reasons). Time dependences must be defined in `TimeFunction EXPRESSION'. See *Note Types for Constraint::, for the complete list of options and *Note Constraint examples::, for some examples. `FunctionSpace': building function spaces ========================================= A `FunctionSpace' is characterized by the type of its interpolated fields, one or several basis functions and optional constraints (in space and time). Subspaces of a function space can be defined (e.g., for the use with hierarchical elements), as well as direct associations of global quantities (e.g., floating potential, electric charge, current, voltage, magnetomotive force, etc.). A key point is that basis functions are defined by any number of subsets of functions, being added. Each subset is characterized by associated built-in functions for evaluation, a support of definition and a set of associated supporting geometrical entities (e.g., nodes, edges, facets, volumes, groups of nodes, edges incident to a node, etc.). The freedom in defining various kinds of basis functions associated with different geometrical entities to interpolate a field permits to build made-to-measure function spaces adapted to a wide variety of field approximations (*note FunctionSpace examples::). The syntax for the definition of function spaces is: FunctionSpace { { Name FUNCTION-SPACE-ID; Type FUNCTION-SPACE-TYPE; BasisFunction { { Name BASIS-FUNCTION-ID; NameOfCoef COEF-ID; Function BASIS-FUNCTION-TYPE < { Quantity QUANTITY-ID; Formulation FORMULATION-ID {#INTEGER}; Group GROUP-DEF; Resolution RESOLUTION-ID {} } >; Support GROUP-DEF; Entity GROUP-DEF; } ... } < SubSpace { { Name SUB-SPACE-ID; NameOfBasisFunction BASIS-FUNCTION-LIST; } ... } > < GlobalQuantity { { Name GLOBAL-QUANTITY-ID; Type GLOBAL-QUANTITY-TYPE; NameOfCoef COEF-ID; } ... } > < Constraint { { NameOfCoef COEF-ID; EntityType GROUP-TYPE; < EntitySubType GROUP-SUB-TYPE; > NameOfConstraint CONSTRAINT-ID <{}>; } ... } > } ... < AFFECTATION > ... < LOOP > ... } with FUNCTION-SPACE-ID: FORMULATION-ID: RESOLUTION-ID: STRING | STRING ~ { EXPRESSION-CST } BASIS-FUNCTION-ID: COEF-ID: SUB-SPACE-ID: GLOBAL-QUANTITY-ID: STRING FUNCTION-SPACE-TYPE: Scalar | Vector | Form0 | Form1 | ETC BASIS-FUNCTION-TYPE: BF_Node | BF_Edge | ETC BASIS-FUNCTION-LIST: BASIS-FUNCTION-ID | { BASIS-FUNCTION-ID <,...> } GLOBAL-QUANTITY-TYPE: AliasOf | AssociatedWith Notes: 1. When the definition region of a function type group used as an `Entity' of a `BasisFunction' is the same as that of the associated `Support', it is replaced by `All' for more efficient treatments during the computation process (this prevents the construction and the analysis of a list of geometrical entities). 2. Piecewise defined basis functions: the same `Name' for several `BasisFunction' fields permits to define piecewise basis functions; separate `NameOfCoef's must be defined for those fields. 3. Constraint: a constraint is associated with geometrical entities defined by an automatically created `Group' of type GROUP-TYPE, using the `Region' defined in a `Constraint' object as its main argument, and the optional `SubRegion' in the same object as a GROUP-SUB-TYPE argument. 4. Function: a global basis function (`BF_Global' or `BF_dGlobal') needs parameters, i.e., it is given by the quantity (QUANTITY-ID) pre-computed from multiresolutions performed on multiformulations. See *Note Types for FunctionSpace::, for the complete list of options and *Note FunctionSpace examples::, for some examples. `Jacobian': defining jacobian methods ===================================== Jacobian methods can be referred to in `Formulation' and `PostProcessing' objects to be used in the computation of integral terms and for changes of coordinates. They are based on `Group' objects and define the geometrical transformations applied to the reference elements (i.e., lines, triangles, quadrangles, tetrahedra, prisms, hexahedra, etc.). Besides the classical lineic, surfacic and volume Jacobians, the `Jacobian' object allows the construction of various transformation methods (e.g., infinite transformations for unbounded domains) thanks to dedicated jacobian methods. The syntax for the definition of Jacobian methods is: Jacobian { { Name JACOBIAN-ID; Case { { Region GROUP-DEF | All; Jacobian JACOBIAN-TYPE < { EXPRESSION-CST-LIST } >; } ... } } ... } with JACOBIAN-ID: STRING JACOBIAN-TYPE: Vol | Sur | VolAxi | ETC Note: 1. The default case of a `Jacobian' object is defined by `Region All' and must follow all the other cases. See *Note Types for Jacobian::, for the complete list of options and *Note Jacobian examples::, for some examples. `Integration': defining integration methods =========================================== Various numerical or analytical integration methods can be referred to in `Formulation' and `PostProcessing' objects to be used in the computation of integral terms, each with a set of particular options (number of integration points for quadrature methods--which can be linked to an error criterion for adaptative methods, definition of transformations for singular integrations, etc.). Moreover, a choice can be made between several integration methods according to a criterion (e.g., on the proximity between the source and computation points in integral formulations). The syntax for the definition of integration methods is: Integration { { Name INTEGRATION-ID; < Criterion EXPRESSION; > Case { < { Type INTEGRATION-TYPE; Case { { GeoElement ELEMENT-TYPE; NumberOfPoints EXPRESSION-CST } ... } } ... > < { Type Analytic; } ... > } } ... } with INTEGRATION-ID: STRING INTEGRATION-TYPE: Gauss | ETC ELEMENT-TYPE: Line | Triangle | Tetrahedron ETC See *Note Types for Integration::, for the complete list of options and *Note Integration examples::, for some examples. `Formulation': building equations ================================= The `Formulation' tool permits to deal with volume, surface and line integrals with many kinds of densities to integrate, written in a form that is similar to their symbolic expressions (it uses the same EXPRESSION syntax as elsewhere in GetDP), which therefore permits to directly take into account various kinds of elementary matrices (e.g., with scalar or cross products, anisotropies, nonlinearities, time derivatives, various test functions, etc.). In case nonlinear physical characteristics are considered, arguments are used for associated functions. In that way, many formulations can be directly written in the data file, as they are written symbolically. Fields involved in each formulation are declared as belonging to beforehand defined function spaces. The uncoupling between formulations and function spaces allows to maintain a generality in both their definitions. A `Formulation' is characterized by its type, the involved quantities (of local, global or integral type) and a list of equation terms. Global equations can also be considered, e.g., for the coupling with network relations. The syntax for the definition of formulations is: Formulation { { Name FORMULATION-ID; Type FORMULATION-TYPE; Quantity { { Name QUANTITY-ID; Type QUANTITY-TYPE; NameOfSpace FUNCTION-SPACE-ID <{}> < [ SUB-SPACE-ID | GLOBAL-QUANTITY-ID ] >; < Symmetry EXPRESSION-CST; > < [ EXPRESSION ]; In GROUP-DEF; Jacobian JACOBIAN-ID; Integration INTEGRATION-ID; > < IndexOfSystem INTEGER; > } ... } Equation { < LOCAL-TERM-TYPE { < TERM-OP-TYPE > [ EXPRESSION, EXPRESSION ]; In GROUP-DEF; Jacobian JACOBIAN-ID; Integration INTEGRATION-ID; } > ... < GlobalTerm { < TERM-OP-TYPE > [ EXPRESSION, EXPRESSION ]; In GROUP-DEF; } > ... < GlobalEquation { Type Network; NameOfConstraint CONSTRAINT-ID; { Node EXPRESSION; Loop EXPRESSION; Equation EXPRESSION; In GROUP-DEF; } ... } > ... < AFFECTATION > ... < LOOP > ... } } ... < AFFECTATION > ... < LOOP > ... } with FORMULATION-ID: STRING | STRING ~ { EXPRESSION-CST } FORMULATION-TYPE: FemEquation | ETC LOCAL-TERM-TYPE: Galerkin | deRham QUANTITY-TYPE: Local | Global | Integral TERM-OP-TYPE: Dt | DtDt | JacNL | ETC Note: 1. `IndexOfSystem' permits to resolve ambiguous cases when several quantities belong to the same function space, but to different systems of equations. The INTEGER parameter then specifies the index in the list of an `OriginSystem' command (*note Resolution::). 2. A `GlobalTerm' defines a term to be assembled in an equation associated with a global quantity. This equation is a finite element equation if that global quantity is linked with local quantities. 3. A `GlobalEquation' defines a global equation to be assembled in the matrix of the system. See *Note Types for Formulation::, for the complete list of options and *Note Formulation examples::, for some examples. `Resolution': solving systems of equations ========================================== The operations available in a `Resolution' include: the generation of a linear system, its solving with various kinds of linear solvers, the saving of the solution or its transfer to another system, the definition of various time stepping methods, the construction of iterative loops for nonlinear problems (Newton-Raphson and fixed point methods), etc. Multi-harmonic resolutions, coupled problems (e.g., magneto-thermal) or linked problems (e.g., pre-computations of source fields) are thus easily defined in GetDP. The `Resolution' object is characterized by a list of systems to build and their associated formulations, using time or frequency domain, and a list of elementary operations: Resolution { { Name RESOLUTION-ID; System { { Name SYSTEM-ID; NameOfFormulation FORMULATION-LIST; < Type SYSTEM-TYPE; > < Frequency EXPRESSION-CST-LIST-ITEM | Frequency { EXPRESSION-CST-LIST }; > < DestinationSystem SYSTEM-ID; > < OriginSystem SYSTEM-ID; | OriginSystem { SYSTEM-ID <,...> }; > < NameOfMesh EXPRESSION-CHAR > < Solver EXPRESSION-CHAR > < LOOP > } ... < LOOP > ... } Operation { < RESOLUTION-OP; > ... < LOOP > ... } } ... < AFFECTATION > ... < LOOP > ... } with RESOLUTION-ID: SYSTEM-ID: STRING | STRING ~ { EXPRESSION-CST } FORMULATION-LIST: FORMULATION-ID <{}> | { FORMULATION-ID <{}> <,...> } SYSTEM-TYPE: Real | Complex RESOLUTION-OP: Generate[SYSTEM-ID] | Solve[SYSTEM-ID] | ETC Notes: 1. The default type for a system of equations is `Real'. A frequency domain analysis is defined through the definition of one or several frequencies (`Frequency EXPRESSION-CST-LIST-ITEM | Frequency { EXPRESSION-CST-LIST }'). Complex systems of equations with no predefined list of frequencies (e.g., in modal analyses) can be explicitely defined with `Type Complex'. 2. `NameOfMesh' permits to explicitely specify the mesh to be used for the construction of the system of equations. 3. `Solver' permits to explicitely specify the name of the solver parameter file to use for the solving of the system of equations. This is ony valid if GetDP was compiled against the default solver library (it is the case if you downloaded a pre-compiled copy of GetDP from the internet). 4. `DestinationSystem' permits to specify the destination system of a `TransferSolution' operation (*note Types for Resolution::). 5. `OriginSystem' permits to specify the systems from which ambiguous quantity definitions can be solved (*note Formulation::). See *Note Types for Resolution::, for the complete list of options and *Note Resolution examples::, for some examples. `PostProcessing': exploiting computational results ================================================== The `PostProcessing' object is based on the quantities defined in a `Formulation' and permits the construction (thanks to the EXPRESSION syntax) of any useful piecewise defined quantity of interest: PostProcessing { { Name POST-PROCESSING-ID; NameOfFormulation FORMULATION-ID <{}>; < NameOfSystem SYSTEM-ID; > Quantity { { Name POST-QUANTITY-ID; Value { POST-VALUE ... } } ... < LOOP > ... } } ... < AFFECTATION > ... < LOOP > ... } with POST-PROCESSING-ID: POST-QUANTITY-ID: STRING | STRING ~ { EXPRESSION-CST } POST-VALUE: Local { LOCAL-VALUE } | Integral { INTEGRAL-VALUE } LOCAL-VALUE: [ EXPRESSION ]; In GROUP-DEF; Jacobian JACOBIAN-ID; INTEGRAL-VALUE: [ EXPRESSION ]; In GROUP-DEF; Integration INTEGRATION-ID; Jacobian JACOBIAN-ID; Notes: 1. The quantity defined with INTEGRAL-VALUE is piecewise defined over the elements of the mesh of GROUP-DEF, and takes, in each element, the value of the integration of EXPRESSION over this element. The global integral of EXPRESSION over a whole region (being either GROUP-DEF or a subset of GROUP-DEF) has to be defined in the `PostOperation' with the `POST-QUANTITY-ID[GROUP-DEF]' command (*note PostOperation::). 2. If `NameOfSystem SYSTEM-ID' is not given, the system is automatically selected as the one to which the first quantity listed in the `Quantity' field of FORMULATION-ID is associated. See *Note Types for PostProcessing::, for the complete list of options and *Note PostProcessing examples::, for some examples. `PostOperation': exporting results ================================== The `PostOperation' is the bridge between results obtained with GetDP and the external world. It defines several elementary operations on `PostProcessing' quantities (e.g., plot on a region, section on a user-defined plane, etc.), and outputs the results in several file formats. PostOperation { { Name POST-OPERATION-ID; NameOfPostProcessing POST-PROCESSING-ID; < Format POST-OPERATION-FMT; > < Append EXPRESSION-CHAR; > Operation { < POST-OPERATION-OP; > ... } } ... < AFFECTATION > ... < LOOP > ... } | PostOperation POST-OPERATION-ID UsingPost POST-PROCESSING-ID { < POST-OPERATION-OP; > ... } ... with POST-OPERATION-ID: STRING | STRING ~ { EXPRESSION-CST } POST-OPERATION-OP: Print[ POST-QUANTITY-TERM, PRINT-SUPPORT <,PRINT-OPTION> ... ] | Print[ "STRING", EXPRESSION <,PRINT-OPTION> ... ] | Print[ "STRING", Str[ EXPRESSION-CHAR ] <,PRINT-OPTION> ... ] | Echo[ "STRING" <,PRINT-OPTION> ... ] | PrintGroup[ GROUP-ID, PRINT-SUPPORT <,PRINT-OPTION> ... ] | < LOOP > ... ETC POST-QUANTITY-TERM: POST-QUANTITY-ID <[GROUP-DEF]> | POST-QUANTITY-ID POST-QUANTITY-OP POST-QUANTITY-ID[GROUP-DEF] | POST-QUANTITY-ID[GROUP-DEF] POST-QUANTITY-OP POST-QUANTITY-ID POST-QUANTITY-OP: + | - | * | / PRINT-SUPPORT: OnElementsOf GROUP-DEF | OnRegion GROUP-DEF | OnGlobal | ETC PRINT-OPTION: File EXPRESSION-CHAR | Format POST-OPERATION-FMT | ETC POST-OPERATION-FMT: Table | TimeTable | ETC Notes: 1. Both `PostOperation' syntaxes are equivalent. The first one conforms to the overall interface, but the second one is more concise. 2. The format POST-OPERATION-FMT defined outside the `Operation' field is applied to all the post-processing operations, unless other formats are explicitly given in these operations with the `Format' option (*note Types for PostOperation::). The default format is `Gmsh'. 3. The optional argument `[GROUP-DEF]' of the POST-QUANTITY-ID can only be used when this quantity has been defined as an INTEGRAL-VALUE (*note PostProcessing::). In this case, the sum of all elementary integrals is performed over the region GROUP-DEF. 4. The POST-QUANTITY-OP allows the simple combination of space-dependent quantities (POST-QUANTITY-ID) with global integral quantities (`POST-QUANTITY-ID[GROUP-DEF]'). See *Note Types for PostOperation::, for the complete list of options and *Note PostOperation examples::, for some examples. Types for objects ***************** This chapter presents the complete list of choices associated with metasyntactic variables introduced for the ten GetDP objects. Types for `Group' ================= Types in GROUP-TYPE [ R1 <, GROUP-SUB-TYPE R2 > ] `GROUP-TYPE < GROUP-SUB-TYPE >': `Region' Regions in R1. `Global' Regions in R1 (variant of `Region' used with global `BasisFunction's `BF_Global' and `BF_dGlobal'). `NodesOf' Nodes of elements of R1 < `Not': but not those of R2 >. `EdgesOf' Edges of elements of R1 < `Not': but not those of R2 >. `FacetsOf' Facets of elements of R1 < `Not': but not those of R2 >. `VolumesOf' Volumes of elements of R1 < `Not': but not those of R2 >. `ElementsOf' Elements of regions in R1 < `OnOneSideOf': only elements on one side of R2) >. `GroupsOfNodesOf' Groups of nodes of elements of R1 (a group is associated with each region). `GroupsOfEdgesOf' Groups of edges of elements of R1 (a group is associated with each region). < `InSupport': in a support R2 being a group of type `ElementOf', i.e., containing elements >. `GroupsOfEdgesOnNodesOf' Groups of edges incident to nodes of elements of R1 (a group is associated with each node). < `Not': but not those of R2) >. `EdgesOfTreeIn' Edges of a tree of edges of R1 < `StartingOn': a complete tree is first built on R2 >. `FacetsOfTreeIn' Facets of a tree of facets of R1 < `StartingOn': a complete tree is first built on R2 >. `DualNodesOf' Dual nodes of elements of R1. `DualEdgesOf' Dual edges of elements of R1. `DualFacetsOf' Dual facets of elements of R1. `DualVolumesOf' Dual volumes of elements of R1. Types for `Function' ==================== Math functions -------------- 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 (EXPRESSION-CST, see *Note Constants::). MATH-FUNCTION-ID: `Exp' `[EXPRESSION]' Exponential function: e^EXPRESSION. `Log' `[EXPRESSION]' Natural logarithm: ln(EXPRESSION), EXPRESSION>0. `Log10' `[EXPRESSION]' Base 10 logarithm: log10(EXPRESSION), EXPRESSION>0. `Sqrt' `[EXPRESSION]' Square root, EXPRESSION>=0. `Sin' `[EXPRESSION]' Sine of EXPRESSION. `Asin' `[EXPRESSION]' Arc sine (inverse sine) of EXPRESSION in [-Pi/2,Pi/2], EXPRESSION in [-1,1]. `Cos' `[EXPRESSION]' Cosine of EXPRESSION. `Acos' `[EXPRESSION]' Arc cosine (inverse cosine) of EXPRESSION in [0,Pi], EXPRESSION in [-1,1]. `Tan' `[EXPRESSION]' Tangent of EXPRESSION. `Atan' `[EXPRESSION]' Arc tangent (inverse tangent) of EXPRESSION in [-Pi/2,Pi/2]. `Atan2' `[EXPRESSION,EXPRESSION]' Arc tangent (inverse tangent) of the first EXPRESSION divided by the second, in [-Pi,Pi]. `Sinh' `[EXPRESSION]' Hyperbolic sine of EXPRESSION. `Cosh' `[EXPRESSION]' Hyperbolic cosine of EXPRESSION. `Tanh' `[EXPRESSION]' Hyperbolic tangent of EXPRESSION. `Fabs' `[EXPRESSION]' Absolute value of EXPRESSION. `Fmod' `[EXPRESSION,EXPRESSION]' Remainder of the division of the first EXPRESSION by the second, with the sign of the first. Extended math functions ----------------------- EXTENDED-MATH-FUNCTION-ID: `Cross' `[EXPRESSION,EXPRESSION]' Cross product of the two arguments; EXPRESSION must be a vector. `Hypot' `[EXPRESSION,EXPRESSION]' Square root of the sum of the squares of its arguments. `Norm' `[EXPRESSION]' Absolute value if EXPRESSION is a scalar; euclidian norm if EXPRESSION is a vector. `SquNorm' `[EXPRESSION]' Square norm: `Norm[EXPRESSION]^2'. `Unit' `[EXPRESSION]' Normalization: `EXPRESSION/Norm[EXPRESSION]'. Returns 0 if the norm is smaller than 1.e-30. `Transpose' `[EXPRESSION]' Transposition; EXPRESSION must be a tensor. `TTrace' `[EXPRESSION]' Trace; EXPRESSION must be a tensor. `F_Cos_wt_p' `[]{EXPRESSION-CST,EXPRESSION-CST}' The first parameter represents the angular frequency and the second represents the phase. If the type of the current system is `Real', `F_Cos_wt_p[]{w,p}' is identical to `Cos[w*$Time+p]'. If the type of the current system is `Complex', it is identical to `Complex[Cos[w],Sin[w]]'. `F_Sin_wt_p' `[]{EXPRESSION-CST,EXPRESSION-CST}' The first parameter represents the angular frequency and the second represents the phase. If the type of the current system is `Real', `F_Sin_wt_p[]{w,p}' is identical to `Sin[w*$Time+p]'. If the type of the current system is `Complex', it is identical to `Complex[Sin[w],-Cos[w]]'. `F_Period' `[EXPRESSION]{EXPRESSION-CST}' `Fmod[EXPRESSION,EXPRESSION-CST]' `+' `(EXPRESSION<0 ? EXPRESSION-CST : 0)'; the result is always in [0,EXPRESSION-CST[. Green functions --------------- The Green functions are only used in integral quantities (*note Formulation::). The first parameter represents the dimension of the problem: * `1D': `r = Fabs[$X-$XS]' * `2D': `r = Sqrt[($X-$XS)^2+($Y-$YS)^2]' * `3D': `r = Sqrt[($X-$XS)^2+($Y-$YS)^2+($Z-$ZS)^2]' The triplets of values given in the definitions below correspond to the `1D', `2D' and `3D' cases. GREEN-FUNCTION-ID: `Laplace' `[]{EXPRESSION-CST}' `r/2', `1/(2*Pi)*ln(1/r)', `1/(4*Pi*r)'. `GradLaplace' `[]{EXPRESSION-CST}' Gradient of `Laplace' relative to the destination point (`$X', `$Y', `$Z'). `Helmholtz' `[]{EXPRESSION-CST, EXPRESSION-CST}' `exp(j*k0*r)/(4*Pi*r)', where `k0' is given by the second parameter. `GradHelmholtz' `[]{EXPRESSION-CST, EXPRESSION-CST}' Gradient of `Helmholtz' relative to the destination point (`$X', `$Y', `$Z'). Type manipulation functions --------------------------- TYPE-FUNCTION-ID: `Complex' `[EXPRESSION-LIST]' Creates a (multi-harmonic) complex expression from an number of real-valued expressions. The number of expressions in EXPRESSION-LIST must be even. `Re' `[EXPRESSION]' Takes the real part of a complex-valued expression. `Im' `[EXPRESSION]' Takes the imaginary part of a complex-valued expression. `Vector' `[EXPRESSION,EXPRESSION,EXPRESSION]' Creates a vector from 3 scalars. `Tensor' `[EXPRESSION,EXPRESSION,EXPRESSION,EXPRESSION,EXPRESSION,EXPRESSION,' `EXPRESSION,EXPRESSION,EXPRESSION]' Creates a second-rank tensor of order 3 from 9 scalars. `TensorV' `[EXPRESSION,EXPRESSION,EXPRESSION]' Creates a second-rank tensor of order 3 from 3 vectors. `TensorSym' `[EXPRESSION,EXPRESSION,EXPRESSION,EXPRESSION,EXPRESSION,EXPRESSION]' Creates a symmetrical second-rank tensor of order 3 from 6 scalars. `TensorDiag' `[EXPRESSION,EXPRESSION,EXPRESSION]' Creates a diagonal second-rank tensor of order 3 from 3 scalars. `CompX' `[EXPRESSION]' Gets the X component of a vector. `CompY' `[EXPRESSION]' Gets the Y component of a vector. `CompZ' `[EXPRESSION]' Gets the Z component of a vector. `CompXX' `[EXPRESSION]' Gets the XX component of a tensor. `CompXY' `[EXPRESSION]' Gets the XY component of a tensor. `CompXZ' `[EXPRESSION]' Gets the XZ component of a tensor. `CompYX' `[EXPRESSION]' Gets the YX component of a tensor. `CompYY' `[EXPRESSION]' Gets the YY component of a tensor. `CompYZ' `[EXPRESSION]' Gets the YZ component of a tensor. `CompZX' `[EXPRESSION]' Gets the ZX component of a tensor. `CompZY' `[EXPRESSION]' Gets the ZY component of a tensor. `CompZZ' `[EXPRESSION]' Gets the ZZ component of a tensor. Coordinate functions -------------------- COORD-FUNCTION-ID: `X' `[]' Gets the X coordinate. `Y' `[]' Gets the Y coordinate. `Z' `[]' Gets the Z coordinate. `XYZ' `[]' Gets X, Y and Z in a vector. Miscellaneous functions ----------------------- MISC-FUNCTION-ID: `Printf' `[EXPRESSION]' Prints the value of EXPRESSION when evaluated. `Normal' `[]' Computes the normal to the element. `NormalSource' `[]' Computes the normal to the source element (only valid in a quantity of Integral type). `F_CompElementNum' `[]' Returns 0 if the current element and the current source element are identical. `InterpolationLinear' `[]{EXPRESSION-CST-LIST}' Linear interpolation of points. The number of constant expressions in EXPRESSION-CST-LIST must be even. `dInterpolationLinear' `[]{EXPRESSION-CST-LIST}' Derivative of linear interpolation of points. The number of constant expressions in EXPRESSION-CST-LIST must be even. `InterpolationAkima' `[]{EXPRESSION-CST-LIST}' Akima interpolation of points. The number of constant expressions in EXPRESSION-CST-LIST must be even. `dInterpolationAkima' `[]{EXPRESSION-CST-LIST}' Derivative of Akima interpolation of points. The number of constant expressions in EXPRESSION-CST-LIST must be even. `Order' `[QUANTITY]' Returns the interpolation order of the QUANTITY. Types for `Constraint' ====================== CONSTRAINT-TYPE: `Assign' To assign a value (e.g., for boundary condition). `Init' To give an initial value (e.g., initial value in a time analysis). `AssignFromResolution' To assign a value to be computed by a pre-resolution. `InitFromResolution' To give an initial value to be computed by a pre-resolution. `Network' To describe the node connections of branches in a network. `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 `Left' with the degrees of freedom in the reference region `Right', located 1 unit to the right of the region `Left' along the X-axis, with the coeficient `-1', one could write: { Name periodic; Case { { Region Left; Type Link ; RegionRef Right; Coefficient -1; Function Vector[$X+Pi,$Y,$Z] ; } } } In this example, `Function' defines the mapping that translates the geometrical elements in the region `Left' by 1 along the X-axis, so that they correspond with the elements in the region `Right'. For this mapping to work, the meshes of `Left' and `Right' must be identical. `LinkCplx' To define complex-valued links between degrees of freedom. The syntax is the same as for constraints of type `Link', but `Coeficient' can be complex. Types for `FunctionSpace' ========================= FUNCTION-SPACE-TYPE: `Form0' 0-form, i.e., scalar field of potential type. `Form1' 1-form, i.e., curl-conform field (associated with a curl). `Form2' 2-form, i.e., div-conform field (associated with a divergence). `Form3' 3-form, i.e., scalar field of density type. `Form1P' 1-form perpendicular to the Z=0 plane, i.e., perpendicular curl-conform field (associated with a curl). `Form2P' 2-form in the Z=0 plane, i.e., parallel div-conform field (associated with a divergence). `Scalar' Scalar field. `Vector' Vector field. BASIS-FUNCTION-TYPE: `BF_Node' Nodal function (on `NodesOf', value `Form0'). `BF_Edge' Edge function (on `EdgesOf', value `Form1'). `BF_Facet' Facet function (on `FacetsOf', value `Form2'). `BF_Volume' Volume function (on `VolumesOf', value `Form3'). `BF_GradNode' Gradient of nodal function (on `NodesOf', value `Form1'). `BF_CurlEdge' Curl of edge function (on `EdgesOf', value `Form2'). `BF_DivFacet' Divergence of facet function (on `FacetsOf', value `Form3'). `BF_GroupOfNodes' Sum of nodal functions (on `GroupsOfNodesOf', value `Form0'). `BF_GradGroupOfNodes' Gradient of sum of nodal functions (on `GroupsOfNodesOf', value `Form1'). `BF_GroupOfEdges' Sum of edge functions (on `GroupsOfEdgesOf', value `Form1'). `BF_CurlGroupOfEdges' Curl of sum of edge functions (on `GroupsOfEdgesOf', value `Form2'). `BF_PerpendicularEdge' 1-form (0, 0, `BF_Node') (on `NodesOf', value `Form1P'). `BF_CurlPerpendicularEdge' Curl of 1-form (0, 0, `BF_Node') (on `NodesOf', value `Form2P'). `BF_GroupOfPerpendicularEdge' Sum of 1-forms (0, 0, `BF_Node') (on `NodesOf', value `Form1P'). `BF_CurlGroupOfPerpendicularEdge' Curl of sum of 1-forms (0, 0, `BF_Node') (on `NodesOf', value `Form2P'). `BF_PerpendicularFacet' 2-form (90 degree rotation of `BF_Edge') (on `EdgesOf', value `Form2P'). `BF_DivPerpendicularFacet' Div of 2-form (90 degree rotation of `BF_Edge') (on `EdgesOf', value `Form3'). `BF_Region' Unit value 1 (on `Region', value `Scalar'). `BF_RegionX' Unit vector (1, 0, 0) (on `Region', value `Vector'). `BF_RegionY' Unit vector (0, 1, 0) (on `Region', value `Vector'). `BF_RegionZ' Unit vector (0, 0, 1) (on `Region', value `Vector'). `BF_Global' Global pre-computed quantity (on `Global', value depends on parameters). `BF_dGlobal' Exterior derivative of global pre-computed quantity (on `Global', value depends on parameters). `BF_NodeX' Vector (`BF_Node', 0, 0) (on `NodesOf', value `Vector'). `BF_NodeY' Vector (0, `BF_Node', 0) (on `NodesOf', value `Vector'). `BF_NodeZ' Vector (0, 0, `BF_Node') (on `NodesOf', value `Vector'). `BF_Zero' Zero value 0 (on all regions, value `Scalar'). `BF_One' Unit value 1 (on all regions, value `Scalar'). GLOBAL-QUANTITY-TYPE: `AliasOf' Another name for a name of coefficient of basis function. `AssociatedWith' A global quantity associated with a name of coefficient of basis function, and therefore with this basis function. Types for `Jacobian' ==================== JACOBIAN-TYPE: `Vol' Volume Jacobian, for N-D regions in N-D geometries, N = 1, 2 or 3. `Sur' Surface Jacobian, for (N-1)-D regions in N-D geometries, N = 1, 2 or 3. `Lin' Line Jacobian, for (N-2)-D regions in N-D geometries, N = 2 or 3. `VolAxi' Axisymmetrical volume Jacobian (1st type: r), for 2-D regions in axisymmetrical geometries. `SurAxi' Axisymmetrical surface Jacobian (1st type: r), for 1-D regions in axisymmetrical geometries. `VolAxiSqu' Axisymmetrical volume Jacobian (2nd type: r^2), for 2-D regions in axisymmetrical geometries. `VolSphShell' Volume Jacobian with spherical shell transformation, for N-D regions in N-D geometries, N = 2 or 3. Parameters: RADIUS-INTERNAL, RADIUS-EXTERNAL <, CENTER-X, CENTER-Y, CENTER-Z, POWER, 1/INFINITY >. `VolAxiSphShell' Same as `VolAxi', but with spherical shell transformation. Parameters: RADIUS-INTERNAL, RADIUS-EXTERNAL <, CENTER-X, CENTER-Y, CENTER-Z, POWER, 1/INFINITY >. `VolAxiSquSphShell' Same as `VolAxiSqu', but with spherical shell transformation. Parameters: RADIUS-INTERNAL, RADIUS-EXTERNAL <, CENTER-X, CENTER-Y, CENTER-Z, POWER, 1/INFINITY >. `VolRectShell' Volume Jacobian with rectangular shell transformation, for N-D regions in N-D geometries, N = 2 or 3. Parameters: RADIUS-INTERNAL, RADIUS-EXTERNAL <, DIRECTION, CENTER-X, CENTER-Y, CENTER-Z, POWER, 1/INFINITY >. `VolAxiRectShell' Same as `VolAxi', but with rectangular shell transformation. Parameters: RADIUS-INTERNAL, RADIUS-EXTERNAL <, DIRECTION, CENTER-X, CENTER-Y, CENTER-Z, POWER, 1/INFINITY >. `VolAxiSquRectShell' Same as `VolAxiSqu', but with rectangular shell transformation. Parameters: RADIUS-INTERNAL, RADIUS-EXTERNAL <, DIRECTION, CENTER-X, CENTER-Y, CENTER-Z, POWER, 1/INFINITY >. Types for `Integration' ======================= INTEGRATION-TYPE: `Gauss' Numerical Gauss integration. `GaussLegendre' Numerical Gauss integration obtained by application of a multiplicative rule on the one-dimensional Gauss integration. ELEMENT-TYPE: `Line' Line (2 nodes, 1 edge, 1 volume) (#1). `Triangle' Triangle (3 nodes, 3 edges, 1 facet, 1 volume) (#2). `Quadrangle' Quadrangle (4 nodes, 4 edges, 1 facet, 1 volume) (#3). `Tetrahedron' Tetrahedron (4 nodes, 6 edges, 4 facets, 1 volume) (#4). `Hexahedron' Hexahedron (8 nodes, 12 edges, 6 facets, 1 volume) (#5). `Prism' Prism (6 nodes, 9 edges, 5 facets, 1 volume) (#6). `Pyramid' Pyramid (5 nodes, 8 edges, 5 facets, 1 volume) (#7). `Point' Point (1 node) (#15). Note: 1. N in (#N) is the type number of the element (*note Input file format::). Types for `Formulation' ======================= FORMULATION-TYPE: `FemEquation' Finite element method formulation (all methods of moments, integral methods). LOCAL-TERM-TYPE: `Galerkin' Integral of Galerkin type. `deRham' deRham projection (collocation). QUANTITY-TYPE: `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 `NameOfSpace FUNCTION-SPACE-ID'. `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 `NameOfSpace FUNCTION-SPACE-ID'. `Integral' Integral quantity obtained by the integration of a `LocalQuantity' before its use in an `Equation' term. TERM-OP-TYPE: `Dt' Time derivative applied to the whole term of the equation. `DtDof' Time derivative applied only to the `Dof{}' term of the equation. `DtDt' Time derivative of 2nd order applied to the whole term of the equation. `DtDtDof' Time derivative of 2nd order applied only to the `Dof{}' term of the equation. `JacNL' Jacobian term to be assembled in the Jacobian matrix for nonlinear analysis. `NeverDt' No time scheme applied to the term (e.g., Theta is always 1 even if a theta scheme is applied). Types for `Resolution' ====================== RESOLUTION-OP: `Generate' `[SYSTEM-ID]' Generate the system of equations SYSTEM-ID. `Solve' `[SYSTEM-ID]' Solve the system of equations SYSTEM-ID. `GenerateJac' `[SYSTEM-ID]' Generate the system of equations SYSTEM-ID using a jacobian matrix (of which the unknowns are corrections DX of the current solution X). `SolveJac' `[SYSTEM-ID]' Solve the system of equations SYSTEM-ID using a jacobian matrix (of which the unknowns are corrections DX of the current solution X). Then, Increment the solution (X=X+DX) and compute the relative error DX/X. `GenerateSeparate' `[SYSTEM-ID]' Generate iteration matrices separately for system SYSTEM-ID. It is destined to be used with `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 `EigenSolve' in order to generate the matrices of a (generalized) eigenvalue problem. `GenerateOnly' `[SYSTEM-ID, EXPRESSION-CST-LIST]' Not documented yet. `GenerateOnlyJac' `[SYSTEM-ID, EXPRESSION-CST-LIST]' Not documented yet. `Update' `[SYSTEM-ID, EXPRESSION]' Update the system of equations SYSTEM-ID (built from iteration matrices generated separately with `GenerateSeparate') with EXPRESSION `UpdateConstraint' `[SYSTEM-ID, GROUP-ID, CONSTRAINT-TYPE]' Not documented yet. `InitSolution' `[SYSTEM-ID]' Initialize the solution of SYSTEM-ID to zero (default) or to the values given in a `Constraint' of `Init' type. `SaveSolution' `[SYSTEM-ID]' Save the solution of the system of equations SYSTEM-ID. `SaveSolutions' `[SYSTEM-ID]' Save all the solutions available for the system of equations SYSTEM-ID. This should be used with algorithms that generate more than one solution at once, e.g., `EigenSolve' or `FourierTransform'. `TransferSolution' `[SYSTEM-ID]' Transfer the solution of system SYSTEM-ID, as an `Assign' constraint, to the system of equations defined with a `DestinationSystem' command. This is used with the `AssignFromResolution' constraint type (*note Types for Constraint::). `TransferInitSolution' `[SYSTEM-ID]' Transfer the solution of system SYSTEM-ID, as an `Init' constraint, to the system of equations defined with a `DestinationSystem' command. This is used with the `InitFromResolution' constraint type (*note Types for Constraint::). `Evaluate' `[EXPRESSION]' Evaluate EXPRESSION. `SetTime' `[EXPRESSION]' Change the current time. `SetFrequency' `[SYSTEM-ID, EXPRESSION]' Change the frequency of system SYSTEM-ID. `SystemCommand' `[EXPRESSION-CHAR]' Execute the system command given by EXPRESSION-CHAR. `If' `[EXPRESSION] { RESOLUTION-OP }' If EXPRESSION is true (nonzero), perform the operations in RESOLUTION-OP. `If' `[EXPRESSION] { RESOLUTION-OP }' `Else' `{ RESOLUTION-OP }' If EXPRESSION is true (nonzero), perform the operations in the first RESOLUTION-OP, else perform the operations in the second RESOLUTION-OP. `Break' Not implemented yet. `Print' `[ { EXPRESSION-LIST }, < File EXPRESSION-CHAR > ]' Print the expressions listed in EXPRESSION-LIST. `Print' `[ SYSTEM-ID <, File EXPRESSION-CHAR > <, { EXPRESSION-CST-LIST } >' `<, TimeStep { EXPRESSION-CST-LIST } >]' Print the system SYSTEM-ID. If the EXPRESSION-CST-LIST is given, print only the values of the degrees of freedom given in that list. If the `TimeStep' option is present, limit the printing to the selected time steps. `EigenSolve' `[SYSTEM-ID, EXPRESSION-CST, EXPRESSION-CST, EXPRESSION-CST]' Eigenvalue/eigenvector computation using Arpack. The parameters are: the system (which has to be generated with `GenerateSeparate[]'), the number of eigenvalues/eigenvectors to compute and the real and imaginary spectral shift (around which to look for eigenvalues). `Lanczos' `[SYSTEM-ID, EXPRESSION-CST, { EXPRESSION-CST-LIST } , EXPRESSION-CST]' Eigenvalue/eigenvector computation using the Lanczos algorithm. The parameters are: the system (which has to be generated with `GenerateSeparate[]'), the size of the Lanczos space, the indices of the eigenvalues/eigenvectors to store, the spectral shift. This routine is deprecated: use `EigenSolve' instead. `FourierTransform' `[SYSTEM-ID, SYSTEM-ID, { 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 `Type Complex'), the list of frequencies to consider in the discrete Fourier transform. `TimeLoopTheta' `[EXPRESSION-CST,EXPRESSION-CST,EXPRESSION,EXPRESSION-CST]' `{ 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). `TimeLoopNewmark' `[EXPRESSION-CST,EXPRESSION-CST,EXPRESSION,EXPRESSION-CST,EXPRESSION-CST]' { 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. `IterativeLoop' `[EXPRESSION-CST,EXPRESSION,EXPRESSION-CST<,EXPRESSION-CST>]' { 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 DX) and the relative error to achieve. The optional parameter is a flag for testing purposes. `PostOperation' `[POST-OPERATION-ID]' Perform the specified `PostOperation'. Types for `PostProcessing' ========================== POST-VALUE: `Local' { LOCAL-VALUE } To compute a local quantity. `Integral' { INTEGRAL-VALUE } To integrate the expression over each element. Types for `PostOperation' ========================= PRINT-SUPPORT: `OnElementsOf' GROUP-DEF To compute a quantity on the elements belonging to the region GROUP-DEF, where the solution was computed during the processing stage. `OnRegion' GROUP-DEF To compute a global quantity associated with the region GROUP-DEF. `OnGlobal' To compute a global integral quantity, with no associated region. `OnSection' { { EXPRESSION-CST-LIST } { EXPRESSION-CST-LIST } { 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 EXPRESSION-CST-LIST must contain exactly three elements (the coordinates of the points). `OnGrid' GROUP-DEF To compute a quantity in elements of a mesh which differs from the real support of the solution. `OnGrid GROUP-DEF' differs from `OnElementsOf GROUP-DEF' by the reinterpolation that must be performed. `OnGrid' `{ EXPRESSION, EXPRESSION, EXPRESSION }' `{ EXPRESSION-CST-LIST-ITEM | { EXPRESSION-CST-LIST } ,' ` EXPRESSION-CST-LIST-ITEM | { EXPRESSION-CST-LIST } ,' ` EXPRESSION-CST-LIST-ITEM | { EXPRESSION-CST-LIST } }' To compute a quantity on a parametric grid. The three EXPRESSIONs represent the three cartesian coordinates X, Y and Z, and can be functions of the current values `$A', `$B' and `$C'. The values for `$A', `$B' and `$C' are specified by each EXPRESSION-CST-LIST-ITEM or EXPRESSION-CST-LIST. For example, `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. `OnPoint' { EXPRESSION-CST-LIST } To compute a quantity at a point. The EXPRESSION-CST-LIST must contain exactly three elements (the coordinates of the point). `OnLine' { { EXPRESSION-CST-LIST } { EXPRESSION-CST-LIST } } { EXPRESSION-CST } To compute a quantity along a line (given by its two end points), with an associated number of divisions equal to EXPRESSION-CST. The interpolation points on the line are equidistant. Each EXPRESSION-CST-LIST must contain exactly three elements (the coordinates of the points). `OnPlane' { { EXPRESSION-CST-LIST } { EXPRESSION-CST-LIST } { EXPRESSION-CST-LIST } } `{ EXPRESSION-CST, EXPRESSION-CST }' To compute a quantity on a plane (specified by three points), with an associated number of divisions equal to each EXPRESSION-CST along both generating directions. Each EXPRESSION-CST-LIST must contain exactly three elements (the coordinates of the points). `OnBox' { { EXPRESSION-CST-LIST } { EXPRESSION-CST-LIST } { EXPRESSION-CST-LIST } ` { EXPRESSION-CST-LIST } } { EXPRESSION-CST, EXPRESSION-CST, EXPRESSION-CST }' To compute a quantity in a box (specified by four points), with an associated number of divisions equal to each EXPRESSION-CST along the three generating directions. Each EXPRESSION-CST-LIST must contain exactly three elements (the coordinates of the points). PRINT-OPTION: `File' `EXPRESSION-CHAR' Outputs the result in a file named EXPRESSION-CHAR. `File' `> EXPRESSION-CHAR' Same as `File EXPRESSION-CHAR', except that, if several `File > EXPRESSION-CHAR' options appear in the same `PostOperation', the results are concatenated in the file EXPRESSION-CHAR. `File' `>> EXPRESSION-CHAR' Appends the result to a file named EXPRESSION-CHAR. `Depth' EXPRESSION-CST Recursive division of the elements if EXPRESSION-CST is greater than zero, derefinement if EXPRESSION-CST is smaller than zero. If EXPRESSION-CST is equal to zero, evaluation at the barycenter of the elements. `Skin' Computes the result on the boundary of the region. `Smoothing' Smoothes the solution at the nodes. `HarmonicToTime' EXPRESSION-CST Converts a harmonic solution into a time-dependent one (with EXPRESSION-CST steps). `Dimension' 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). `TimeStep' `EXPRESSION-CST-LIST-ITEM | { EXPRESSION-CST-LIST }' Outputs results for the specified time steps only. `LastTimeStepOnly' Outputs results for the last time step only (useful when calling a `PostOperation' directly in a `Resolution', for example). `Frequency' `EXPRESSION-CST-LIST-ITEM | { EXPRESSION-CST-LIST }' Outputs results for the specified frequencies only. `Format' POST-OPERATION-FMT Outputs results in the specified format. `Adapt' `P1 | H1 | H2' Performs p- or h-refinement on the post-processing result, considered as an error map. `Target' EXPRESSION-CST Specifies the target for the optimizer during adaptation (error for `P1|H1', number of elements for `H2'). `Value' `EXPRESSION-CST-LIST-ITEM | { EXPRESSION-CST-LIST }' Specifies acceptable output values for discrete optimization (e.g. the available interpolation orders with `Adapt P1'). `Sort' `Position | Connection' Sorts the output by position (x, y, z) or by connection (for `LINE' elements only). `Iso' EXPRESSION-CST Outputs directly contour prints (with EXPRESSION-CST values) instead of elementary values. `Iso' `{ EXPRESSION-CST-LIST }' Outputs directly contour prints for the values specified in the EXPRESSION-CST-LIST instead of elementary values. `NoNewLine' Suppresses the new lines in the output when printing global quantities (i.e., with `Print OnRegion' or `Print OnGlobal'). `ChangeOfCoordinates' `{ EXPRESSION, EXPRESSION, EXPRESSION }' Changes the coordinates of the results according to the three expressions given in argument. The three EXPRESSIONs represent the three new cartesian coordinates X, Y and Z, and can be functions of the current values of the cartesian coordinates `$X', `$Y' and `$Z'. `ChangeOfValues' `{ EXPRESSION-LIST }' Changes the values of the results according to the expressions given in argument. The EXPRESSIONs represent the new values (X-compoment, Y-component, etc.), and can be functions of the current values of the solution ($VAL0, $VAL1, etc.). `DecomposeInSimplex' Decomposes all output elements in simplices (points, lines, triangles or tetrahedra). `Store' `EXPRESSION-CST' Stores the result of an `OnRegion' post-processing operation in the register EXPRESSION-CST. `TimeLegend' `< { EXPRESSION, EXPRESSION, 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. `FrequencyLegend' `< { EXPRESSION, EXPRESSION, 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. `EigenvalueLegend' `< { EXPRESSION, EXPRESSION, 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. POST-OPERATION-FMT: `Gmsh' `GmshParsed' Gmsh output. See the documentation of Gmsh (`http://www.geuz.org/gmsh/') for a description of the file formats. `Table' Space oriented column output, e.g., suitable for Gnuplot, Excel, Caleida Graph, etc. The columns are: ELEMENT-TYPE ELEMENT-INDEX X-COORD Y-COORD Z-COORD ... REAL REAL REAL VALUES. The three REAL numbers preceding the VALUES contain context-dependent information, depending on the type of plot: curvilinear abscissa for `OnLine' plots, normal to the plane for `OnPlane' plots, parametric coordinates for parametric `OnGrid' plots, etc. `TimeTable' Time oriented column output, e.g., suitable for Gnuplot, Excel, Caleida Graph, etc. The columns are: TIME-STEP TIME X-COORD Y-COORD Z-COORD ... VALUE. `Gnuplot' Space oriented column output similar to the `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: ELEMENT-TYPE ELEMENT-INDEX X-COORD Y-COORD Z-COORD REAL REAL REAL VALUES. The three REAL numbers preceding the VALUES contain context-dependent information, depending on the type of plot: curvilinear abscissa for `OnLine' plots, normal to the plane for `OnPlane' plots, parametric coordinates for parametric `OnGrid' plots, etc. `Adaptation' Adaptation map, suitable for the GetDP `-adapt' command line option. Short examples ************** Constant expression examples ============================ The simplest constant expression consists of an INTEGER or a REAL number as in 21 -3 or -3.1415 27e3 -290.53e-12 Using operators and the classic math functions, CONSTANT-IDs can be defined: c1 = Sin[2/3*3.1415] * 5000^2; c2 = -1/c1; `Group' examples ================ Let us assume that some elements in the input mesh have the region numbers 1000, 2000 and 3000. In the definitions Group { Air = Region[1000]; Core = Region[2000]; Inductor = Region[3000]; NonConductingDomain = Region[{Air, Core}]; ConductingDomain = Region[{Inductor}]; } `Air', `Core', `Inductor' are identifiers of elementary region groups while `NonConductingDomain' and `ConductingDomain' are global region groups. Groups of function type contain lists of entities built on the region groups appearing in their arguments. For example, NodesOf[NonConductingDomain] represents the group of nodes of geometrical elements belonging to the regions in `NonConductingDomain' and EdgesOf[DomainC, Not SkinDomainC] represents the group of edges of geometrical elements belonging to the regions in `DomainC' but not to those of `SkinDomainC'. `Function' examples =================== A physical characteristic is a piecewise defined function. The magnetic permeability `mu[]' can for example be defined in the considered regions by Function { mu[Air] = 4.e-7*Pi; mu[Core] = 1000.*4.e-7*Pi; } A nonlinear characteristic can be defined through an EXPRESSION with arguments, e.g., Function { mu0 = 4.e-7*Pi; a1 = 1000.; b1 = 100.; // Constants mu[NonlinearCore] = mu0 + 1./(a1+b1*Norm[$1]^6); } where function `mu[]' in region `NonLinearCore' has one argument `$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 `mu[{Curl a}]' instead of `mu[]' in `Equation' terms (*note Formulation examples::). Multiple arguments can be specified in a similar way: writing `mu[{Curl a},{T}]' in an `Equation' term will provide the function `mu[]' with two usable arguments, `$1' (the magnetic flux density) and `$2' (the temperature). It is also possible to directly interpolate one-dimensional functions from tabulated data. In the following example, the function F(X) as well as its derivative F'(X) are interpolated from the (X,F(X)) couples (0,0.65), (1,0.72), (2,0.98) and (3,1.12): Function { couples = {0, 0.65 , 1, 0.72 , 2, 0.98 , 3, 1.12}; f[] = InterpolationLinear[$1]{List[couples]}; dfdx[] = dInterpolationLinear[$1]{List[couples]}; } The function `f[]' may then be called in an `Equation' term of a `Formulation' with one argument, X. Notice how the list of constants `List[couples]' is supplied as a list of parameters to the built-in function `InterpolationLinear' (*note Constants::, as well as *Note 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 `ListAlt' command (*note Constants::): 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]}; } In order to optimize the evaluation time of complex expressions, registers may be used (*note Registers::). For example, the evaluation of `g[] = f[$1]*Sin[f[$1]^2]' would require two (costly) linear interpolations. But the result of the evaluation of `f[]' may be stored in a register (for example the register 0) with g[] = f[$1]#0 * Sin[#0^2]; thus reducing the number of evaluations of `f[]' (and of the argument `$1') to one. A function can also be time dependent, e.g., 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}; } Note that `TimeFct_ExtSin[]' is identical to `TimeFct_Sin[]' in a time domain analysis, but also permits to define phasors implicitely in the case of harmonic analyses. `Constraint' examples ===================== Constraints are referred to in `FunctionSpace's and are usually used for boundary conditions (`Assign' type). For example, essential conditions on two surface regions, `Surf0' and `Surf1', will be first defined by Constraint { { Name DirichletBoundaryCondition1; Type Assign; Case { { Region Surf0; Value 0.; } { Region Surf1; Value 1.; } } } } The way the `Value's are associated with `Region's (with their nodes, their edges, their global regions, ...) is defined in the `FunctionSpace's which use the `Constraint'. In other words, a `Constraint' defines data but does not define the method to process them. A time dependent essential boundary condition on `Surf1' would be introduced as (cf. *Note Function examples:: for the definition of `TimeFct_Exp[]'): { Region Surf1; Value 1.; TimeFunction 3*TimeFct_Exp[] } It is important to notice that the time dependence cannot be introduced in the `Value' field, since the `Value' is only evaluated once during the pre-processing. Other constraints can be referred to in `Formulation's. It is the case of those defining electrical circuit connections (`Network' type), e.g., 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}; } } } } which defines two non-connected circuits (`Circuit1' and `Circuit2'), with an independent numbering of nodes: region `VoltageSource' is connected in parallel with region `PrimaryCoil', and region `SecondaryCoil' is connected in parallel with region `Charge'. `FunctionSpace' examples ======================== Various discrete function spaces can be defined in the frame of the finite element method. Nodal finite element spaces --------------------------- The most elementary function space is the nodal finite element space, defined on a mesh of a domain W and denoted 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: V = Sum [ VN * SN, for all N in N ], V in S0(W) where N is the set of nodes of W, SN is the nodal basis function associated with node N and VN is the value of V at node N. It is defined by 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; } } } } Function `sn' is the built-in basis function BF_Node associated with all nodes (`NodesOf') in the mesh of W (`Domain'). Previously defined `Constraint DirichletBoundaryCondition1' (*note Constraint examples::) is used as boundary condition. In the example above, `Entity NodesOf[All]' is preferred to `Entity NodesOf[Domain]'. In this way, the list of all the nodes of `Domain' will not have to be generated. All the nodes of each geometrical element in `Support Domain' will be directly taken into account. High order nodal finite element space ------------------------------------- Higher order finite elements can be directly taken into account by `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 `BasisFunction', e.g., ... 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]; } } ... Nodal finite element space with floating potentials --------------------------------------------------- A scalar potential with floating values VF on certain boundaries GF, F in CF, e.g., for electrostatic problems, can be expressed as V = Sum [ VN * SN, for all N in NV ] + Sum [ VF * SF, for all F in CF ], V in S0(W) where NV is the set of inner nodes of W and each function SF is associated with the group of nodes of boundary GF, F in CF (`SkinDomainC'); SF is the sum of the nodal basis functions of all the nodes of CF. Its function space is defined by 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 { ... } } } Two global quantities have been associated with this space: the electric potential `GlobalElectricPotential', being an alias of coefficient `vf', and the electric charge `GlobalElectricCharge', being associated with coefficient `vf'. Edge finite element space ------------------------- Another space is the edge finite element space, denoted S1(W), containing 1-forms, i.e., curl-conform fields: H = Sum [ HE * SE, for all E in E ], H in S1(W) where E is the set of edges of W, SE is the edge basis function for edge E and HE is the circulation of H along edge E. It is defined by FunctionSpace { { Name Hcurl_h; Type Form1; BasisFunction { { Name se; NameOfCoef he; Function BF_Edge; Support Domain; Entity EdgesOf[All]; } } Constraint { ... } } } 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 (`EdgesOfTreeIn') built in the mesh (`Domain'), having to be complete on certain boundaries (`StartingOn Surf'): 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; } ... } } } Coupled edge and nodal finite element spaces -------------------------------------------- A 1-form function space, containing curl free fields in certain regions WCC (`DomainCC') of W, which are the complementary part of WC (`DomainC') in W, can be explicitly characterized by H = Sum [ HK * SK, for all E in EC ] + Sum [ PHIN * VN, for all N in NCC ], H in S1(W) where EC is the set of inner edges of W, NCC is the set of nodes inside WCC and on its boundary DWCC, SK is an edge basis function and VN is a vector nodal function. Such a space, coupling a vector field with a scalar potential, can be defined by 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; } } } } This example points out the definition of a piecewise defined basis function, e.g., function `vn' being defined with `BF_GradNode' in `DomainCC' and `BF_GroupOfEdges' in `DomainC'. This leads to an easy coupling between these regions. Coupled edge and nodal finite element spaces for multiply connected domains --------------------------------------------------------------------------- In case a multiply connected domain WCC is considered, basis functions associated with cuts (`SurfaceCut') have to be added to the previous basis functions, which gives the function space below: Group { _TransitionLayer_SkinDomainC_ = ElementsOf[SkinDomainC, OnOneSideOf SurfaceCut]; } FunctionSpace { { Name Hcurl_hphi; Type Form1; BasisFunction { ... SAME AS ABOVE ... { 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 { ... SAME AS ABOVE ... { NameOfCoef Ic; EntityType GroupsOfNodesOf; NameOfConstraint Current; } { NameOfCoef Icc; EntityType GroupsOfNodesOf; NameOfConstraint Current; } { NameOfCoef U; EntityType GroupsOfNodesOf; NameOfConstraint Voltage; } } } } Global quantities associated with the cuts, i.e., currents and voltages if H is the magnetic field, have also been defined. `Jacobian' examples =================== A simple Jacobian method is for volume transformations (of N-D regions in N-D geometries; N = 1, 2 or 3), e.g., in region `Domain', Jacobian { { Name Vol; Case { { Region Domain; Jacobian Vol; } } } } `Jacobian VolAxi' would define a volume Jacobian for axisymmetrical problems. A Jacobian method can also be piecewise defined, in `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 (`All', being the default); in each case, a volume Jacobian is used. This method is defined by: Jacobian { { Name Vol; Case { { Region DomainInf; Jacobian VolSphShell {Val_Rint, Val_Rext}; } { Region All; Jacobian Vol; } } } } `Integration' examples ====================== A commonly used numerical integration method is the `Gauss' integration, with a number of integration points (`NumberOfPoints') depending on geometrical element types (`GeoElement'), i.e. 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; } } } } } } The method above is valid for both 2D and 3D problems, for different kinds of elements. `Formulation' examples ====================== Electrostatic scalar potential formulation ------------------------------------------ An electrostatic formulation using an electric scalar potential V, i.e. ( epsr grad V, grad VP ) W = 0, for all VP in S0(W), is expressed by 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; } } } } The density of the `Galerkin' term is a copy of the symbolic form of the formulation, i.e., the product of a relative permittivity function `epsr[]' by a vector of degrees of freedom (`Dof{.}'); the scalar product of this with the gradient of test function `v' results in a symmetrical matrix. Note that another `Quantity' could be defined for test functions, e.g., `vp' defined by `{ 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. Electrostatic scalar potential formulation with floating potentials and electric charges ---------------------------------------------------------------------------------------- An extension of the formulation above can be made to take floating potentials and electrical charges into account (the latter being defined in `FunctionSpace Hgrad_v_floating'), i.e. 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; } } } } with the predefinition `Function { eps0 = 8.854187818e-12; }'. Magnetostatic 3D vector potential formulation --------------------------------------------- A magnetostatic 3D vector potential formulation ( NU curl A , curl AP ) W - ( JS , AP ) WS = 0, for all AP in S1(W) with gauge condition, with a source current density JS in inductors WS, is expressed by 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; } } } } Note that JS is here given by a function `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). Magnetodynamic 3D or 2D magnetic field and magnetic scalar potential formulation -------------------------------------------------------------------------------- A magnetodynamic 3D or 2D H-PHI formulation, i.e., coupling the magnetic field H with a magnetic scalar potential PHI, Dt ( MU H , HP ) W + ( RO curl H , curl HP ) WC = 0, for all HP in S1(W), can be expressed by 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; } } } } Nonlinearities, Mixed formulations, ... --------------------------------------- In case nonlinear physical characteristics are considered, arguments are used for associated functions, e.g., `mu[{h}]'. Several test functions can be considered in an `Equation' field. Consequently, mixed formulations can be defined. `Resolution' examples ===================== Static resolution (electrostatic problem) ----------------------------------------- A static resolution, e.g., for the electrostatic formulation (*note Formulation examples::), can be defined by Resolution { { Name Electrostatics_v; System { { Name Sys_Ele; NameOfFormulation Electrostatics_v; } } Operation { Generate[Sys_Ele]; Solve[Sys_Ele]; SaveSolution[Sys_Ele]; } } } The generation (`Generate') of the matrix of the system `Sys_Ele' will be made with the formulation `Electrostatics_v', followed by its solving (`Solve') and the saving of the solution (`SaveSolution'). Frequency domain resolution (magnetodynamic problem) ---------------------------------------------------- A frequency domain resolution, e.g., for the magnetodynamic H-PHI formulation (*note Formulation examples::), is given by Resolution { { Name Magnetodynamics_hphi; System { { Name Sys_Mag; NameOfFormulation Magnetodynamics_hphi; Frequency Freq; } } Operation { Generate[Sys_Mag]; Solve[Sys_Mag]; SaveSolution[Sys_Mag]; } } } preceded by the definition of constant `Freq', e.g., Function { Freq = 50.; } Time domain resolution (magnetodynamic problem) ----------------------------------------------- A time domain resolution, e.g., for the same magnetodynamic H-PHI formulation (*note Formulation examples::), is given by 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]; } } } } If, e.g., the `Resolution' above is preceded by the constant and function definitions below Function { Tc = 10.e-3; Mag_Time0 = 0.; Mag_TimeMax = 2.*Tc; Mag_DTime[] = Tc/20.; Mag_Theta[] = 1./2.; } the performed time analysis will be a Crank-Nicolson scheme (theta-scheme with `Theta = 0.5') with initial time 0 ms, end time 20 ms and time step 1 ms. 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, ... 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]; } } ... preceded by constant definitions, e.g., Function { NL_Eps = 1.e-4; NL_Relax = 1.; NL_NbrMax = 80; } Coupled formulations -------------------- A coupled problem, e.g., magnetodynamic (in frequency domain; `Frequency Freq') - thermal (in time domain) coupling, with temperature dependent characteristics (e.g., `rho[{T}]', ...), can be defined by: 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]; } } } Two systems of equations, `Sys_Mag' and `Sys_The', will be solved iteratively until convergence (`Criterion'), using a relaxation factor (`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. `PostProcessing' examples ========================= The quantities to be post-computed based on a solution of a resolution are defined, e.g., for the electrostatic problem (*note Formulation examples::; *note Resolution examples::), for the solution associated with the formulation `Electrostatics_v', by 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; } } } } } } The electric scalar potential V (`v'), the electric field E (`e') and the electric flux density D (`d') can all be computed from the solution. They are all defined in the region `Domain'. The quantities for the solution associated with the formulation `Electrostatics_v_floating' are defined by PostProcessing { { Name EleSta_vf; NameOfFormulation Electrostatics_v_floating; Quantity { ... SAME AS ABOVE ... { Name Q; Value { Local { [ {Q} ]; In SkinDomainC; } } } { Name V; Value { Local { [ {V} ]; In SkinDomainC; } } } } } } which points out the way to define post-quantities based on global quantities. `PostOperation' 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 `PostProcessing' defined in *Note PostProcessing examples::, the maps of the electric scalar potential and of the electric field on the elements of the region `Domain' are defined as: 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" ]; } } } 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): Print [ v, OnSection { {0,0,1} {1,0,1} {0,1,1} }, File "sec_v.pos" ]; 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: 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 ]; Many options can be used to modify the aspect of all these maps, as well as the default behaviour of the `Print' commands. See *Note 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 `Domain', in a table oriented format appended to an already existing file `out.txt', the operation would be: Print [ v, OnElementsOf Domain, Depth 0, Skin, Format Table, File >> "out.txt" ]; Global quantities, which are associated with regions (and not with the elements of the mesh of these regions), are displayed thanks to the `OnRegion' operation. For example, the global potential and charge on the region `SkinDomainC' can be displayed with: PostOperation { { Name Val_V_Q; NameOfPostProcessing EleSta_vf ; Operation { Print [ V, OnRegion SkinDomainC ]; Print [ Q, OnRegion SkinDomainC ]; } } } Complete examples ***************** This chapter presents complete examples that can be run "as is" with GetDP (*note Running GetDP::). Many other ready-to-use examples are available in the GetDP wiki at the following address: `http://www.geuz.org/getdp/wiki/FrontPage' (username=getdp; password=wiki). Electrostatic problem ===================== Let us first consider a simple electrostatic problem. The formulation used is an electric scalar potential formulation (file `EleSta_v.pro', including files `Jacobian_Lib.pro' and `Integration_Lib.pro'). It is applied to a microstrip line (file `mStrip.pro'), whose geometry is defined in the file `mStrip.geo' (*note Gmsh examples::). The geometry is two-dimensional and by symmetry only one half of the structure is modeled. SurfInf / / +------------------------------------+ / | | / | Air |/ | | | Line | | / / / | 2D elements in: +-------/---+ / | Air, Diel1 / |- | +-----------+------------------------+ 1D elements in: | Diel1 | Line, Ground, SurfInf | | +------------------------------------+ \ Ground Note that the structure of the following files points out the separation of the data describing the particular problem and the method used to solve it (*note Numerical tools as objects::), and therefore how it is possible to build black boxes adapted to well defined categories of problems. The files are commented (*note Comments::) and can be run without any modification. /* ------------------------------------------------------------------- File "mStrip.pro" This file defines the problem dependent data structures for the microstrip problem. To compute the solution: getdp mStrip -solve EleSta_v To compute post-results: getdp mStrip -pos Map or get