EDF R&D Guide to programming in the Telemac system version 6.

0 H-P74-2009-00801-EN

Version 1.0

Synthèse

Ce guide est une partie de la documentation du système Telemac. Il détaille dans une première partie
l’utilisation de la bibliothèque d’éléments finis BIEF, à l’intention d’un développeur de module du
système, et dans une deuxième partie la structuration interne de la bibliothèque elle-même.

ACCESSIBILITE : FREE Page 1/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Executive Summary

This guide is part of the documentation of the TELEMAC system. It details the way to use the finite
element library BIEF version 6.0 and its implementation.

ACCESSIBILITE : FREE Page 2/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Sommaire / Summary
Synthèse ................................................................................................................................1
Executive Summary.............................................................................................................2
Sommaire / Summary..........................................................................................................3
FOREWORD .......................................................................................................................5
STRUCTURE OF THIS GUIDE .......................................................................................5
INTRODUCTION ..........................................................................................................6
WHY A FINITE ELEMENT LIBRARY?........................................................................6
BRIEF DESCRIPTION OF BIEF ....................................................................................6
FORTRAN 90: REASONS FOR THE CHANGE ...........................................................7
PROGRAMMING WITH BIEF 6.0 ........................................................................8
FEATURES OF FORTRAN 90 USED IN BIEF: ............................................................8
Structures.............................................................................................................8
Pointers................................................................................................................8
Modules...............................................................................................................9
Interfaces .............................................................................................................9
Interface operator ..............................................................................................10
Optional parameters ..........................................................................................10
STRUCTURES IN BIEF: ...............................................................................................11
A short description ............................................................................................11
Reference description of the structures .............................................................13
Allocation of structures .....................................................................................21
Operations on structures....................................................................................25
BUILDING MATRICES AND VECTORS ...................................................................29
CONSTRUCTION OF MATRICES.................................................................29
CONSTRUCTION OF VECTORS...................................................................36
OPERATIONS ON MATRICES AND VECTORS.......................................................42
OPERATIONS ON VECTORS ........................................................................42
OPERATIONS ON MATRICES ......................................................................46
MATRIX x VECTOR PRODUCTS .................................................................47
SOLVING LINEAR SYSTEMS ....................................................................................49
PARALLELISM .............................................................................................................51
Partition of the domain......................................................................................52
Data structure specific to parallelism................................................................53
Communication between processors.................................................................54
Adaptation of the algorithms.............................................................................55
UTILITIES......................................................................................................................59
FUNCTIONS ....................................................................................................59
BASIC SUBROUTINES...................................................................................61
SUBROUTINES DEALING WITH THE SELAFIN FORMAT FILE ............64
SUBROUTINES DEALING WITH ALL FORMATS.....................................67

ACCESSIBILITE : FREE Page 3/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

SCIENTIFIC LIBRARY...................................................................................70
HIGHER ORDER SUBROUTINES IN BIEF..................................................71
USER SUBROUTINES IN BIEF .....................................................................71
DESIGNING A NEW PROGRAMME ..........................................................................72
Global data ........................................................................................................73
General structure of a programme based on BIEF 6.0......................................74
INTERNAL STRUCTURE OF BIEF ...................................................................83
BIEF DATA STRUCTURE ...........................................................................................84
DESCRIPTION OF FINITE ELEMENTS .......................................................84
DESCRIPTION OF MESH...............................................................................89
STORAGE OF MATRICES .............................................................................93
CONSTRUCTION OF MATRICES : ............................................................................99
EXAMPLE OF A MASS-MATRIX CALCULATION....................................99
MATRICES WITH A QUASI-BUBBLE ELEMENT ...................................102
MATRIX OPERATIONS:............................................................................................106
ASSEMBLY OF AN ELEMENTARY VECTOR..........................................107
PRODUCT NON SYMMETRICAL MATRIX BY VECTOR ......................110
PRODUCT SYMMETRICAL MATRIX BY VECTOR................................111
PRODUCT TRANSPOSED MATRIX BY VECTOR ...................................112
DIRICHLET-TYPE BOUNDARY CONDITIONS .......................................112
PRODUCTS BETWEEN DIAGONAL MATRIX AND MATRIX...............114
MATRIX-VECTOR PRODUCT WITH EDGE-BASED STORAGE ...........115
SOLVERS AND PRECONDITIONING OPERATIONS............................................115
THE VARIOUS SOLVERS............................................................................116
DIAGONAL PRECONDITIONING ..............................................................123
BLOCK-DIAGONAL PRECONDITIONING ...............................................123
LU PRECONDITIONING ..............................................................................130
CROUT PRECONDITIONING......................................................................130
GAUSS-SEIDEL EBE PRECONDITIONING...............................................134
BIBLIOGRAPHY............................................................................................................136
APPENDIX 1: MATRIX STORAGE CONVENTIONS .............................................137
APPENDIX 2: THE SELAFIN FORMAT....................................................................142
APPENDIX 3: PROGRAMMING RULES ..................................................................144
Subroutine header: ........................................................................................................144
Programming rules........................................................................................................145
General rules ...................................................................................................145
Defensive programming..................................................................................146
Use of modules................................................................................................146
APPENDIX 4: INDEX ....................................................................................................147

ACCESSIBILITE : FREE Page 4/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

FOREWORD

This is the fourth release of a programming guide to the TELEMAC system, based on
FORTRAN 90. It has been written to help the numerous people who have to develop or to
understand the "ins" and "outs" of this system, namely research engineers and technicians at
EDF, students and researchers in universities, research institutes and laboratories, or users
willing to write specific user subroutines. It will probably not meet all the expectations:
giving fully detailed explanations on all the system would take thousands of pages, and would
probably never be read! With this guide we only hope to establish a closer relationship
between developers, and we shall enhance the guide progressively, as new questions arise.
This document will be a success if you consider it yours. We thus beg you to report on errors,
misprints and mistakes, and to ask for more explanations on parts that would not be clear
enough. It will be a commitment for us to take into account all your remarks in next releases.

STRUCTURE OF THIS GUIDE

This guide is made of two main parts and a number of appendices. Part A should be the only
useful one for developers of programs based on the BIEF library. Part B give details on the
very structure of BIEF and is a priori meant for BIEF developers themselves. The appendices
include an index.

ACCESSIBILITE : FREE Page 5/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

INTRODUCTION

WHY A FINITE ELEMENT LIBRARY?

A great many finite element software programs have been developed over the last few
years at the Laboratoire National d'Hydraulique et Environnement. These have been based
on a single data structure, initiated by the development of TELEMAC-2D. Algorithms
used by one program, for example to process a diffusion operator, can also be used by
another. It was therefore felt to be quite natural to group together all the numerical
developments of the various codes in a single library, distinguishing them from the
physical aspects.

This finite element library (called BIEF in the rest of this document. BIEF stands for the
French expression BIbliothèque d'Elements Finis, meaning Finite Element Library, but
“bief” in French is a river reach in English) is designed so that it can be used as a toolbox
in the simplest possible way. It is possible, for example, to solve a classic fluid mechanics
equation by calling the BIEF ad hoc modules, without having to worry about the details of
the solution. This simplifies and considerably speeds up the calculation code development
phase. In addition, BIEF continually includes new developments, thereby making them
available to users immediately.

The development of BIEF is closely linked to that of the TELEMAC system codes, most of
which are the subject of a Quality Control procedure. In the case of the software programs
of the EDF's Research and Development, this procedure involves designing and then
checking the quality of the product throughout the different phases in its life. In particular,
a software program subjected to Quality Control is accompanied by a validation document
which describes a series of test cases. This document can be used to evaluate the qualities
and limitations of the product and identify its field of application. These test cases are also
used for developing the software and are checked each time a modification is made.
Consequently, the BIEF algorithms also benefit from this strict quality control procedure.

BRIEF DESCRIPTION OF BIEF

The data structure and programming of BIEF is described in detail in Part B of this
document. One of the important features of this structure is that matrices are stored either
in elementary form or in an edge-by-edge storage. Compared with compact storage, this
type of storage saves on memory space for numerous types of elements and also enables
resolution algorithms to be obtained quickly and efficiently. In fact, one of the essential
features of BIEF is to offer methods with very low computing costs.

BIEF offers a whole range of subroutines. They include methods for solving advection
equations, diffusion equations, linear system inversion methods with different types of

ACCESSIBILITE : FREE Page 6/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

preconditioning. The user is also provided with subroutines for calculating matrices: mass
matrices, diffusion matrices, boundary matrices, etc. BIEF can be used to carry out all the
conventional operations on vectors (norms, dot products, etc.), on the products of one
matrix by a vector or of two matrices. By simply calling a subroutine, the user can
calculate the divergence of a vector, the gradient of a function, and so on. It should be
remembered that this description is not exhaustive and that the content of BIEF will
change depending on the requirements of its users.
The language used is FORTRAN 90 (see explanations below), and, to facilitate the
diffusion of the TELEMAC system, portability is checked on a wide range of hardware,
including both super-computers and workstations, Linux and Windows machines.

FORTRAN 90: REASONS FOR THE CHANGE

TELEMAC was written in FORTRAN 77 up to version 3.2. There are a number of reasons
for the choice of FORTRAN 90 for BIEF:

- Structured programming. Structures were prepared in version 3.2 of BIEF in FORTRAN

77, at the price of non-standard features, for example the use of negative indices in arrays.
The structures are now normal structures in FORTRAN 90, and they are much easier to
use.

- Dynamic allocation of memory.

- The increasing number of modules based on BIEF meant that it was taking longer and
longer to complete each update. One of the aim of structured programming is to simplify
updating.

- The increasing number of arguments in the subroutines, and changes of arguments in the
user subroutines. This will is suppressed as far as possible by the use of FORTRAN 90
modules.

The principal objectives of structured programming are therefore:

- To enable dynamic allocation of memory.

- To facilitate update and development of the system elements.

- To facilitate the future development and maintenance of BIEF.

- To get a safer implementation, with many error checking done by the compiler itself.

- To enable a better compatibility between subsequent versions of BIEF.

ACCESSIBILITE : FREE Page 7/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

PROGRAMMING WITH BIEF 6.0

FEATURES OF FORTRAN 90 USED IN BIEF:

We briefly explain hereafter features of FORTRAN 90 that are used in BIEF. For
more detailed explanations please refer to a real Fortran 90 book, such as ref. [5].

Structures

FORTRAN 77 only recognises integers, real numbers, Boolean and character strings.
FORTRAN 90 can be used to create structures. The following is an example of the creation
of a 'point' type structure composed of two real numbers, and a circle structure, composed of
a centre and a radius:

TYPE point
REAL :: x,y
END TYPE

TYPE circle
TYPE(point) :: centre
REAL :: radius
END TYPE

It can be observed that the centre is itself a structure of a type previously defined. Once the
structure has been defined, objects of this type can be declared:

TYPE(circle) :: ROND

ROND will be a circle with its centre and radius; the latter are obtained thanks to the %
"component selector". Thus the radius of ROND will be the real ROND%radius.
Pointers

Pointers are well known in C language, but are notably different in Fortran 90. Pointers in
Fortran 90 may be used as pointers as in C but also as aliases. Unlike C, they are not mere
addresses pointing to somewhere in the computer memory. The target must be defined
precisely, for example the line:

REAL, POINTER, DIMENSION(:) :: X

will define a pointer to a one-dimensional real array, and it will be impossible to have it
pointing to an integer nor even to a 2-dimensional array. This pointer X will have then to be
pointed to a target by the statement:

X => Y

ACCESSIBILITE : FREE Page 8/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

were Y is an already existing one-dimensional real array. Then X can be used as if it were
Y, it is thus an alias.

X can be also directly allocated as a normal array by the statement:

ALLOCATE(X(100))

to have (for example) an array of 100 values. In this case X and its target have the same
name.

A well known problem in Fortran 90 is the fact that arrays of pointers do not exist. To
overcome this problem, one has to create a new structure which is itself a pointer, and to
declare an array of this new structure. This is done for blocks, which are lists of pointers to
BIEF_OBJ structures.

Modules

Modules are like INCLUDE statements, but are more clever, so that INCLUDE should now
always be avoided. As a matter of fact, modules can be used to define global variables that
will be accessible to all routines. With the following module:

MODULE EXAMPLE
INTEGER EX1,EX2,EX3,EX4
END MODULE EXAMPLE

all the subroutines beginning with the statement: USE EXAMPLE will have access to the
same numbers EX1, ... EX4. With INCLUDE statements, it would be only local variables
without link to EX1,...declared in other subroutines.

Modules will thus be used to define global variables that will be accessed via a USE
statement. If only one or several objects must be accessed, the ONLY statement may be
used, as in the example below:

USE EXAMPLE, ONLY : EX1,EX2

This will enable to avoid name conflicts and secures programming.

Modules are also used to store interfaces that will be shared between several subroutines
(see paragraph below)

Interfaces

ACCESSIBILITE : FREE Page 9/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Interfaces are a mean given to the compiler to check arguments of subroutines even if it has
no access to them. For example, the following interface:

INTERFACE
LOGICAL FUNCTION EOF(LUNIT)
INTEGER, INTENT(IN) :: LUNIT
END FUNCTION
END INTERFACE

says that function EOF has one integer argument. INTENT(IN) indicates that argument
LUNIT is not changed. Interfaces of all BIEF subroutines have been put in a single module
called BIEF. a USE BIEF statement at the beginning of a subroutine will prompt the
compiler to check the arguments and also do some optimisations in view of the INTENT
information (which can be IN, OUT, or INOUT depending on the use of the argument). If a
function is declared in an interface, it must not be declared as an EXTERNAL FUNCTION

Interface operator

New operations on structures could also be defined with the INTERFACE OPERATOR
statement. For example a sum of two vectors as stored in BIEF could be defined so that the
line:

CALL OS('X=Y ',U,V,V,0.D0)

could be replaced by:

U=V

Such interface operators have not been done in version 6.0, because operations like
U=A+B+C would probably not be optimised and would trigger a number of unnecessary
copies.

Optional parameters

Subroutines may now have optional parameters. Thanks to this new feature, subroutines OS
and OSD of previous releases have been grouped in a single one. Hereafter is given the
interface of new subroutine OS:

INTERFACE
SUBROUTINE OS( OP, X , Y , Z , C , IOPT , INFINI , ZERO )
USE BIEF_DEF
INTEGER, INTENT(IN), OPTIONAL :: IOPT
DOUBLE PRECISION, INTENT(IN), OPTIONAL, INFINI, ZERO
TYPE(BIEF_OBJ), INTENT(INOUT), OPTIONAL :: X

ACCESSIBILITE : FREE Page 10/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

TYPE(BIEF_OBJ), INTENT(IN), OPTIONAL :: Y,Z

DOUBLE PRECISION, INTENT(IN), OPTIONAL :: C
CHARACTER(LEN=8), INTENT(IN) :: OP
END SUBROUTINE
END INTERFACE

Subroutine OS performs on structure X the operation given in OP, e.g.

CALL OS(‘X=0 ‘,X=TRA01)

Or:

CALL OS(‘X=Y ‘,X=TAB1,Y=TAB2)

Parameters Y,Z and C are used only for specific operations and otherwise are not necessary.
When a parameter is missing and to avoid ambiguity, the parameters must be named, hence
the X=TRA01 in the example above.

Parameters IOPT, INFINI and ZERO stem from the old subroutine OSD and are used only
when a division is implied in the operation asked, for example if OP = 'X=Y/Z '. These 3
parameters are now optional. When they are present, it is better to name them as is done in
the following line:

CALL OS('X=Y/Z ',U,V,W,0.D0,IOPT=2,INFINI=1.D0,ZERO=1.D-10)

The use of optional parameters will enable a better compatibility between different versions
because it will be possible to add a new parameter as an optional one.

Optional arguments will be written between brackets [] in argument lists in the rest of the
document.

STRUCTURES IN BIEF:

A short description

In BIEF 6.0, structures will be composed of integer and real numbers, of pointers to other
structures or to integer and real arrays. The structures defined in this way are, for the time
being, as follows:

* BIEF_OBJ (may be a vector, a matrix or a block)

* BIEF_MESH (information on a mesh)
* SLVCFG (Solver Configuration)
* BIEF_FILE (Description of a data file)

ACCESSIBILITE : FREE Page 11/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The notions of VECTOR, MATRIX and BLOCK that were pre-programmed in BIEF 6.0
have been gathered in a single structure called BIEF_OBJ. This will enable what is called
"polymorphism" in Object Oriented Languages, i.e. the fact that arguments of subroutines
may be of different types. As a matter of fact, many subroutines in BIEF are able to treat in
the same way vectors or blocks of vectors (see for example OS), matrices or blocks of
matrices (see e.g. SOLVE and DIRICH). Polymorphism is possible in FORTRAN 90 with
the use of interfaces, however it requires the writing of one subroutine per combination of
types, and thus leads to a lot of duplication. The use of a single structure BIEF_OBJ was
thus more elegant, the only drawback being that the misuse of a matrix as a vector, for
example, cannot be checked by the compiler but only by the subroutines dealing with such
structures.

Information on the structures can be simply retrieved by the component selector.

We shall also refer to BIEF_OBJ structures as VECTOR, MATRIX or BLOCK, depending

on their use, as is done below:

VECTOR

This may be any vector (a simple array) or a vector defined on the mesh, with values for
every point of the mesh. In the latter case, there is a corresponding discretisation type and
numbering system (global or boundary numbering of nodes or numbering of elements). For
example, a vector defined on all the mesh with a discretisation P0 will be implicitly given
according to the element numbers. In certain conditions, a vector may change discretisation
while the calculations are being carried out.
A vector has a first dimension which corresponds to the number of nodes to which it applies.
There is also a second dimension (for example, the off-diagonal terms of a matrix).

Any vector is in fact an array with 2 dimensions which the user can process as he wishes.

MATRIX

Matrices are also linked to the mesh. Different storage methods are possible. These matrices
can be multiplied by the vectors mentioned above.

BLOCK

A block is a set of structures. This notion has proved of particular importance for:

- Writing general solvers for linear systems, with the possibility of the matrix being a block
of several matrices.

ACCESSIBILITE : FREE Page 12/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

- Using simple orders to group together and process sets of vectors or matrices, for example
the arrays of variables which are advected by the method of characteristics.
- Eliminate the need for certain arrays to follow one another in the memory.

BIEF_MESH structure

This structure includes all information concerning the mesh (connectivity tables, boundary
points, point coordinates, etc.). It replaces a large number of arrays used in releases of BIEF
prior to 3.2

SLVCFG

It stands for "SoLVer ConFiGuration). This is a simple structure to store all the information
needed by the subroutine SOLVE for solving linear systems (choice of the method,
accuracy, preconditioning, etc).

Reference description of the structures

Module BIEF_DEF of the library is given hereafter, with the list of components for every
structure and a short description.

POINTER_TO_BIEF_OBJ
C
C=======================================================================
C
C STRUCTURE OF POINTER TO A BIEF_OBJ, TO HAVE ARRAYS OF POINTERS
C IN THE BIEF_OBJ STRUCTURE FOR BLOCKS
C
C BIEF VERSION 6.0
C
C=======================================================================
C
C THIS IS NECESSARY IN FORTRAN 90 TO HAVE ARRAYS OF POINTERS
C LIKE THE COMPONENT ADR BELOW, WHICH ENABLES TO BUILD BLOCKS
C WHICH ARE ARRAYS OF POINTERS TO BIEF_OBJ STRUCTURES
C
TYPE POINTER_TO_BIEF_OBJ
SEQUENCE
TYPE(BIEF_OBJ), POINTER :: P
END TYPE POINTER_TO_BIEF_OBJ
C
BIEF_OBJ
TYPE BIEF_OBJ
C
C-----------------------------------------------------------------------
C
C HEADER COMMON TO ALL OBJECTS
C
C KEY : ALWAYS 123456 TO CHECK MEMORY OVERWRITING
INTEGER KEY
C
C TYPE: 2: VECTOR, 3: MATRIX, 4: BLOCK

ACCESSIBILITE : FREE Page 13/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

INTEGER TYPE
C
C NAME: FORTRAN NAME OF OBJECT IN 6 CHARACTERS
CHARACTER(LEN=6) NAME
C
C-----------------------------------------------------------------------
C
C FOR VECTORS
C
C
C NAT: NATURE (1:DOUBLE PRECISION 2:INTEGER)
INTEGER NAT
C
C ELM: TYPE OF ELEMENT
INTEGER ELM
C
C DIM1: FIRST DIMENSION OF VECTOR
INTEGER DIM1
C
C MAXDIM1: MAXIMUM SIZE PER DIMENSION
INTEGER MAXDIM1
C
C DIM2: SECOND DIMENSION OF VECTOR
INTEGER DIM2
C
C MAXDIM2: MAXIMUM SECOND DIMENSION OF VECTOR
INTEGER MAXDIM2
C
C DIMDISC: TYPE OF ELEMENT IF VECTOR IS DISCONTINUOUS AT
C THE BORDER BETWEEN ELEMENTS, OR 0 IF NOT
INTEGER DIMDISC
C
C STATUS:
C 0: ANY ARRAY
C 1: VECTOR DEFINED ON A MESH, NO CHANGE OF DISCRETISATION
C 2: VECTOR DEFINED ON A MESH, CHANGE OF DISCRETISATION ALLOWED
INTEGER STATUS
C
C TYPR: TYPE OF VECTOR OF REALS
C '0' : NIL '1' : EQUAL TO 1 'Q' : NO SPECIFIC PROPERTY
CHARACTER*1 TYPR
C
C TYPR: TYPE OF VECTOR OF REALS
C '0' : NIL '1' : EQUAL TO 1 'Q' : NO SPECIFIC PROPERTY
CHARACTER*1 TYPI
C
C POINTER TO DOUBLE PRECISION 1-DIMENSION ARRAY
C DATA ARE STORED HERE FOR A DOUBLE PRECISION VECTOR
DOUBLE PRECISION, POINTER,DIMENSION(:)::R
C
C POINTER TO INTEGER 1-DIMENSION ARRAY
C DATA ARE STORED HERE FOR AN INTEGER VECTOR
INTEGER, POINTER,DIMENSION(:)::I
C
C-----------------------------------------------------------------------
C
C FOR MATRICES
C
C STO: TYPE OF STORAGE 1: CLASSICAL EBE 3: EDGE-BASED STORAGE
INTEGER STO
C
C ELMLIN: TYPE OF ELEMENT OF LINE
INTEGER ELMLIN
C
C ELMCOL: TYPE OF ELEMENT OF COLON
INTEGER ELMCOL
C
C TYPDIA: TYPE OF DIAGONAL
C '0' : NIL 'I' : IDENTITY 'Q' : NO SPECIFIC PROPERTY

ACCESSIBILITE : FREE Page 14/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

CHARACTER*1 TYPDIA
C
C TYPEXT: TYPE OF EXTRA-DIAGONAL TERMS
C '0' : NIL 'S' : SYMMETRY 'Q' : NO SPECIFIC PROPERTY
CHARACTER*1 TYPEXT
C
C POINTER TO A BIEF_OBJ FOR DIAGONAL
TYPE(BIEF_OBJ), POINTER :: D
C
C POINTER TO A BIEF_OBJ FOR EXTRA-DIAGONAL TERMS
TYPE(BIEF_OBJ), POINTER :: X
C
C PRO: TYPE OF MATRIX-VECTOR PRODUCT
INTEGER PRO
C
C-----------------------------------------------------------------------
C
C FOR BLOCKS
C
C BLOCKS ARE IN FACT ARRAYS OF POINTERS TO BIEF_OBJ STRUCTURES
C ADR(I)%P WILL BE THE I-TH BIEF_OBJ OBJECT
C
C N: NUMBER OF OBJECTS IN THE BLOCK
INTEGER N
C MAXBLOCK: MAXIMUM NUMBER OF OBJECTS IN THE BLOCK
INTEGER MAXBLOCK
C ADR: ARRAY OF POINTERS TO OBJECTS (WILL BE OF SIZE MAXBLOCK)
TYPE(POINTER_TO_BIEF_OBJ), POINTER, DIMENSION(:) :: ADR
C
C-----------------------------------------------------------------------
C
END TYPE BIEF_OBJC
C
C=======================================================================
C
BIEF_MESH
C
C=======================================================================
C
C STRUCTURE OF MESH : BIEF_MESH
C
C=======================================================================
C
TYPE BIEF_MESH
C
C 1) A HEADER
C
C NAME: NAME OF MESH IN 6 CHARACTERS
CHARACTER(LEN=6) NAME
C
C 2) A SERIES OF INTEGER VALUES (DECLARED AS POINTERS TO ENABLE
C ALIASES)
C
C NELEM: NUMBER OF ELEMENTS IN MESH
INTEGER, POINTER :: NELEM
C
C NELMAX: MAXIMUM NUMBER OF ELEMENTS ENVISAGED
INTEGER, POINTER :: NELMAX
C
C NPTFR: NUMBER OF 1D BOUNDARY NODES, EVEN IN 3D
INTEGER, POINTER :: NPTFR
C
C NPTFRX: NUMBER OF 1D BOUNDARY NODES, EVEN IN 3D
INTEGER, POINTER :: NPTFRX
C
C NELEB: NUMBER OF BOUNDARY ELEMENTS (SEGMENTS IN 2D)
C IN 3D WITH PRISMS:
C number of LATERAL boundary elements for sigma mesh
INTEGER, POINTER :: NELEB

ACCESSIBILITE : FREE Page 15/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

C
C NELEBX: MAXIMUM NELEB
INTEGER, POINTER :: NELEBX
C
C NSEG: NUMBER OF SEGMENTS IN THE MESH
INTEGER, POINTER :: NSEG
C
C DIM: DIMENSION OF DOMAIN (2 OR 3)
INTEGER, POINTER :: DIM
C
C TYPELM: TYPE OF ELEMENT (10 FOR TRIANGLES, 40 FOR PRISMS)
INTEGER, POINTER :: TYPELM
C
C NPOIN: NUMBER OF VERTICES (OR LINEAR NODES) IN THE MESH
INTEGER, POINTER :: NPOIN
C
C NPMAX: MAXIMUM NUMBER OF VERTICES IN THE MESH
INTEGER, POINTER :: NPMAX
C
C MXPTVS: MAXIMUM NUMBER OF POINTS ADJACENT TO 1 POINT
INTEGER, POINTER :: MXPTVS
C
C MXELVS: MAXIMUM NUMBER OF ELEMENTS ADJACENT TO 1 POINT
INTEGER, POINTER :: MXELVS
C
C LV: MAXIMUM VECTOR LENGTH ALLOWED ON VECTOR COMPUTERS,
C DUE TO ELEMENT NUMBERING
INTEGER, POINTER :: LV
C
C
C 3) A SERIES OF BIEF_OBJ FOR STORING INTEGER ARRAYS
C
C IKLE: CONNECTIVITY TABLE IKLE(NELMAX,NDP) AND KLEI(NDP,NELMAX)
TYPE(BIEF_OBJ), POINTER :: IKLE,KLEI
C
C IFABOR: TABLE GIVING ELEMENTS BEHIND FACES OF A TRIANGLE
TYPE(BIEF_OBJ), POINTER :: IFABOR
C
C NELBOR: ELEMENTS OF THE BORDER
TYPE(BIEF_OBJ), POINTER :: NELBOR
C
C NULONE: LOCAL NUMBER OF BOUNDARY POINTS FOR BORDER ELEMENTS
TYPE(BIEF_OBJ), POINTER :: NULONE
C
C KP1BOR: POINTS FOLLOWING AND PRECEDING A BOUNDARY POINT
TYPE(BIEF_OBJ), POINTER :: KP1BOR
C
C NBOR: GLOBAL NUMBER OF BOUNDARY POINTS
TYPE(BIEF_OBJ), POINTER :: NBOR
C
C IKLBOR: CONNECTIVITY TABLE FOR BOUNDARY POINTS
TYPE(BIEF_OBJ), POINTER :: IKLBOR
C
C IFANUM: FOR STORAGE 2, NUMBER OF SEGMENT IN ADJACENT ELEMENT
C OF A TRIANGLE
TYPE(BIEF_OBJ), POINTER :: IFANUM
C
C IKLEM1: ADRESSES OF NEIGHBOURS OF POINTS FOR FRONTAL
C MATRIX-VECTOR PRODUCT
TYPE(BIEF_OBJ), POINTER :: IKLEM1
C
C LIMVOI: FOR FRONTAL MATRIX-VECTOR PRODUCT. ADDRESSES OF POINTS
C WITH A GIVEN NUMBER OF NEIGHBOURS.
TYPE(BIEF_OBJ), POINTER :: LIMVOI
C
C NUBO: FOR FINITE VOLUMES, GLOBAL NUMBERS OF VERTICES OF SEGMENTS
TYPE(BIEF_OBJ), POINTER :: NUBO
C
C FOR SEGMENT-BASED STORAGE

ACCESSIBILITE : FREE Page 16/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

C
C GLOSEG: GLOBAL NUMBERS OF VERTICES OF SEGMENTS
TYPE(BIEF_OBJ), POINTER :: GLOSEG
C ELTSEG: SEGMENTS FORMING AN ELEMENT
TYPE(BIEF_OBJ), POINTER :: ELTSEG
C ORISEG: ORIENTATION OF SEGMENTS FORMING AN ELEMENT 1:TRIGO 2:CLOCKWISE
TYPE(BIEF_OBJ), POINTER :: ORISEG
C
C
C SERIES OF ARRAYS FOR PARALLELISM
C HERE GLOBAL MEANS NUMBER IN THE WHOLE DOMAIN
C LOCAL MEANS NUMBER IN THE SUB-DOMAIN
C
C KNOLG: GIVES THE INITIAL GLOBAL NUMBER OF A LOCAL POINT
TYPE(BIEF_OBJ), POINTER :: KNOLG
C NACHB: NUMBERS OF PROCESSORS CONTAINING A GIVEN POINT
TYPE(BIEF_OBJ), POINTER :: NACHB
C ISEG: GLOBAL NUMBER OF FOLLOWING OR PRECEDING POINT IN THE BOUNDARY
C IF IT IS IN ANOTHER SUB-DOMAIN.
TYPE(BIEF_OBJ), POINTER :: ISEG
C KNOGL: INVERSE OF KNOLG, KNOGL(KNOLG(I))=I. LOCAL NUMBER OF A
C POINT WITH GIVEN GLOBAL NUMBER
TYPE(BIEF_OBJ), POINTER :: KNOGL
C ADDRESSES IN ARRAYS SENT BETWEEN PROCESSORS
TYPE(BIEF_OBJ), POINTER :: INDPU
C
C DIMENSION NHP(NBMAXNSHARE,NPTIR). NHP(IZH,IR) IS THE GLOBAL NUMBER
C IN THE SUB-DOMAIN OF A POINT WHOSE NUMBER IS IR IN THE INTERFACE
C WITH THE IZ-TH HIGHER RANK PROCESSOR
TYPE(BIEF_OBJ), POINTER :: NHP
C NHM IS LIKE NHP, BUT WITH LOWER RANK PROCESSORS
TYPE(BIEF_OBJ), POINTER :: NHM
C
C FOR FINITE VOLUMES AND KINETIC SCHEMES
TYPE(BIEF_OBJ), POINTER :: JMI
C ELEMENTAL HALO NEIGHBOURHOOD DESCRIPTION IN PARALLEL
C IFAPAR(6,NELEM2)
C IFAPAR(1:3,IELEM): PROCESSOR NUMBERS BEHIND THE 3 ELEMENT EDGES
C NUMBER FROM 0 TO NCSIZE-1
C IFAPAR(4:6,IELEM): -LOCAL- ELEMENT NUMBERS BEHIND THE 3 EDGES
C IN THE NUMBERING OF PARTITIONS THEY BELONG TO
TYPE(BIEF_OBJ), POINTER :: IFAPAR
C
C 4) A SERIES OF BIEF_OBJ FOR STORING REAL ARRAYS
C
C XEL: COORDONNEES X PAR ELEMENTS
TYPE(BIEF_OBJ), POINTER :: XEL
C
C YEL: COORDONNEES Y PAR ELEMENTS
TYPE(BIEF_OBJ), POINTER :: YEL
C
C ZEL: COORDONNEES Z PAR ELEMENTS
TYPE(BIEF_OBJ), POINTER :: ZEL
C
C SURFAC: AREAS OF ELEMENTS
TYPE(BIEF_OBJ), POINTER :: SURFAC
C
C SURDET: 1/DET OF ISOPARAMETRIC TRANSFORMATION
TYPE(BIEF_OBJ), POINTER :: SURDET
C
C LGSEG: LENGTH OF 2D BOUNDARY SEGMENTS
TYPE(BIEF_OBJ), POINTER :: LGSEG
C
C XSGBOR: NORMAL X TO 1D BOUNDARY SEGMENTS
TYPE(BIEF_OBJ), POINTER :: XSGBOR
C
C YSGBOR: NORMAL Y TO 1D BOUNDARY SEGMENTS
TYPE(BIEF_OBJ), POINTER :: YSGBOR
C

ACCESSIBILITE : FREE Page 17/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

C ZSGBOR: NORMAL Z TO 1D BOUNDARY SEGMENTS

TYPE(BIEF_OBJ), POINTER :: ZSGBOR
C
C XNEBOR: NORMAL X TO 1D BOUNDARY POINTS
TYPE(BIEF_OBJ), POINTER :: XNEBOR
C
C YNEBOR: NORMAL Y TO 1D BOUNDARY POINTS
TYPE(BIEF_OBJ), POINTER :: YNEBOR
C
C ZNEBOR: NORMAL Z TO 1D BOUNDARY POINTS
TYPE(BIEF_OBJ), POINTER :: ZNEBOR
C
C X: COORDINATES OF POINTS
TYPE(BIEF_OBJ), POINTER :: X
C
C Y: COORDINATES OF POINTS
TYPE(BIEF_OBJ), POINTER :: Y
C
C Z: COORDINATES OF POINTS
TYPE(BIEF_OBJ), POINTER :: Z
C
C COSLAT: LATITUDE COSINE
TYPE(BIEF_OBJ), POINTER :: COSLAT
C
C SINLAT: LATITUDE SINE
TYPE(BIEF_OBJ), POINTER :: SINLAT
C
C DISBOR: DISTANCE TO 1D BOUNDARIES
TYPE(BIEF_OBJ), POINTER :: DISBOR
C
C M: WORKING MATRIX
TYPE(BIEF_OBJ), POINTER :: M
C
C MSEG: WORKING MATRIX FOR SEGMENT-BASED STORAGE
TYPE(BIEF_OBJ), POINTER :: MSEG
C
C W: WORKING ARRAY FOR A NON-ASSEMBLED VECTOR
TYPE(BIEF_OBJ), POINTER :: W
C
C T: WORKING ARRAY FOR AN ASSEMBLED VECTOR
TYPE(BIEF_OBJ), POINTER :: T
C
C VNOIN: FOR FINITE VOLUMES
TYPE(BIEF_OBJ), POINTER :: VNOIN
C
C XSEG: X COORDINATE OF FOLLOWING OR PRECEDING POINT IN THE BOUNDARY
C IF IT IS IN ANOTHER SUB-DOMAIN.
TYPE(BIEF_OBJ), POINTER :: XSEG
C
C YSEG: Y COORDINATE OF FOLLOWING OR PRECEDING POINT IN THE BOUNDARY
C IF IT IS IN ANOTHER SUB-DOMAIN.
TYPE(BIEF_OBJ), POINTER :: YSEG
C
C FAC: MULTIPLICATION FACTOR FOR POINTS IN THE BOUNDARY FOR
C DOT PRODUCT.
TYPE(BIEF_OBJ), POINTER :: FAC
C
C FOR PARALLELISM AND NON BLOCKING COMMUNICATION (SEE PARINI.F)
C
C NUMBER OF NEIGHBOURING PROCESSORS (SEEN BY POINTS)
INTEGER , POINTER :: NB_NEIGHB
C FOR ANY NEIGHBOURING PROCESSOR, NUMBER OF POINTS
C SHARED WITH IT
TYPE(BIEF_OBJ), POINTER :: NB_NEIGHB_PT
C RANK OF PROCESSORS WITH WHICH TO COMMUNICATE FOR POINTS
TYPE(BIEF_OBJ), POINTER :: LIST_SEND
C NH_COM(DIM1NHCOM,NB_NEIGHB)
C WITH DIM1NHCOM IS THE MAXIMUM NUMBER OF POINTS SHARED
C WITH ANOTHER PROCESSOR (OR SLIGHTLY MORE FOR 16 BYTES ALIGNMENT)

ACCESSIBILITE : FREE Page 18/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

C NH_COM(I,J) IS THE GLOBAL NUMBER IN THE SUB-DOMAIN OF I-TH

C POINT SHARED WITH J-TH NEIGHBOURING PROCESSOR
TYPE(BIEF_OBJ), POINTER :: NH_COM
C
C NUMBER OF NEIGHBOURING PROCESSORS (SEEN BY EDGES)
INTEGER , POINTER :: NB_NEIGHB_SEG
C FOR ANY NEIGHBOURING PROCESSOR, NUMBER OF EDGES
C SHARED WITH IT
TYPE(BIEF_OBJ), POINTER :: NB_NEIGHB_PT_SEG
C RANK OF PROCESSORS WITH WHICH TO COMMUNICATE FOR EDGES
TYPE(BIEF_OBJ), POINTER :: LIST_SEND_SEG
C LIKE NH_COM BUT FOR EDGES
TYPE(BIEF_OBJ), POINTER :: NH_COM_SEG
C
C WILL BE USED AS BUFFER BY MPI IN PARALLEL
C
TYPE(BIEF_OBJ), POINTER :: BUF_SEND
TYPE(BIEF_OBJ), POINTER :: BUF_RECVC
C FOR FINITE VOLUMES AND KINETIC SCHEMES
C
TYPE(BIEF_OBJ), POINTER :: CMI,DPX,DPY
TYPE(BIEF_OBJ), POINTER :: DTHAUT,AIRST
C
END TYPE BIEF_MESH
C
C=======================================================================
C
SLVCFG
C
C=======================================================================
C
C STRUCTURE OF SOLVER CONFIGURATION
C
C=======================================================================
C
TYPE SLVCFG
C
C SLV: CHOICE OF SOLVER
INTEGER SLV
C
C NITMAX: MAXIMUM NUMBER OF ITERATIONS
INTEGER NITMAX
C
C PRECON: TYPE OF PRECONDITIONING
INTEGER PRECON
C
C KRYLOV: DIMENSION OF KRYLOV SPACE FOR GMRES SOLVER
INTEGER KRYLOV
C
C EPS: ACCURACY
DOUBLE PRECISION EPS
C
C ZERO: FOR CHECKING DIVISIONS BY ZERO
DOUBLE PRECISION ZERO
C
C OK: IF PRECISION EPS HAS BEEN REACHED
LOGICAL OK
C
C NIT: NUMBER OF ITERATIONS IF PRECISION REACHED
INTEGER NIT
C
END TYPE SLVCFG
C
C=======================================================================
C
BIEF_FILE
C
C=======================================================================
C

ACCESSIBILITE : FREE Page 19/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

C STRUCTURE OF FILE
C
C=======================================================================
C
TYPE BIEF_FILE
C
C LU: LOGICAL UNIT TO OPEN THE FILE
INTEGER LU
C
C NAME: NAME OF FILE
CHARACTER(LEN=144) NAME
C
C TELNAME: NAME OF FILE IN TEMPORARY DIRECTORY
CHARACTER(LEN=6) TELNAME
C
C FMT: FORMAT (SERAFIN, MED, ETC.)
CHARACTER(LEN=8) FMT
C
C ACTION: READ, WRITE OR READWRITE
CHARACTER(LEN=9) ACTION
C
C BINASC: ASC FOR ASCII OR BIN FOR BINARY
CHARACTER(LEN=3) BINASC
C
C TYPE: KIND OF FILE
CHARACTER(LEN=12) TYPE
C
END TYPE BIEF_FILE

Allocation of structures

Once declared, BIEF_OBJ structures must be defined and memory for their arrays of
data must be dynamically allocated. This is done by specific subroutines, depending of their
type, i.e. whether they are vectors, matrices or blocks. BIEF_MESH structure must also be
allocated.
The allocations of structures are grouped in a subroutine called POINT_NAME
(NAME is the name of a TELEMAC programme, for example ARTEMIS).

The mesh structure must be allocated first. Vectors and matrices will then be allocated
with respect to that mesh.

Mesh : subroutine ALMESH

A mesh must be declared previously as a BIEF_MESH structure

Syntax: CALL ALMESH( MESH, NOM, IELM, SPHERI,CFG,NFIC,

EQUA,NPLAN,NPMAX,NPTFRX,NELMAX,I3,I4)

ALMESH prepares the BIEF_MESH structures and fills some of them, for example it will
allocate the memory for storing the component IKLE and will read it in the geometry file.
However not all the data structure is ready after exiting ALMESH. This task is carried out by

ACCESSIBILITE : FREE Page 20/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

the subroutine INBIEF which must be called later, when all the necessary data have been
logged.

Arguments:

MESH : The BIEF_MESH structure to allocate.

NOM : Fortran name of this structure in 6 characters.
IELM : Element with the highest number of degrees of freedom in the mesh.
11 : only linear interpolation in 2D
12 : quasi-bubble in 2D
41 : linear in 3D with prisms
SPHERI : Logical. If true, coordinates will be spherical, if not, Cartesian.
CFG : Configuration. So far 2 integer values:
CFG(1) is the storage of matrices (1: classical EBE, 3: edge-based)
CFG(2) is the matrix-vector product (1: classical EBE, 2: frontal)
These data will be used to build specific data structures relevant to
every option.
NFIC : Logical unit where the geometry file has been opened.
EQUA : Equations to solve or calling programme in 20 characters. Up to now is
only used to allocate specific arrays for Finite volumes if
EQUA='SAINT-VENANT VF'. is used to
optimise memory requirements.

Next 6 arguments are optional:

NPLAN : Number of horizontal planes in 3D meshes of prisms.

NPMAX : Maximum number of vertices in the mesh, in case of adaptive meshing (not
implemented yet).
NPTFRX : Maximum number of boundary points in the mesh, in case of adaptive meshing
(not implemented yet).
NELMAX : Maximum number of elements in the mesh, in case of adaptive meshing
(not implemented yet).
I3, I4 : When present, it means that the X and Y coordinates of the mesh are in
reality X+I3 and Y+I4, I3 and I4 (integers representing a number of metres,
have been removed to minimize truncation errors (see also the Selafin format
where these two numbers are included for a geo-referenced post-processing.

Vector : ALLVEC, ALLVEC_IN_BLOCK

A vector must be declared previously as a BIEF_OBJ structure

Syntax: CALL ALLVEC(NAT,VEC,NOM,IELM,DIM2,STATUT)

ACCESSIBILITE : FREE Page 21/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Arguments:

NAT : Nature (1=real, 2=integer).

VEC : The BIEF_OBJ structure to be allocated as a vector.
NOM : Fortran name of vector in 6 characters.
IELM : Vector discretisation type
(or dimension depending on the status, see below)
0 : dimension 1, constant per element.
1 : dimension 1 linear discretisation.
10 : triangles, constant discretisation per element.
11 : triangles, linear discretisation.
12 : triangles, quasi-bubble discretisation.
40 : prism, constant discretisation per element.
41 : prism, linear discretisation.
DIM2 : Second dimension of vector.
STATUT 0 : Any array. IELM is then its first dimension.
1 : Vector defined on a mesh, with no possibility of changing discretisation.
2 : Vector defined on a mesh, with possibility of changing discretisation within
the limits of the memory space.

Syntax: CALL ALLVEC_IN_BLOCK(BLO,N,NAT,NOM,IELM,DIM2,STATUT)

With ALLVEC_IN_BLOCK, N vectors with the same characteristics are put directly into the
block BLO. NOM is then only a generic name, for example if NOM is 'T ', the names of the
vectors will be T1, T2, etc. Only the block BLO must be declared. T2 will be in fact
BLO%ADR(2)%P but can be named also T2 if T2 is declared as a BIEF_OBJ pointer and
pointed to BLO%ADR(2)%P:

TYPE(BIEF_OBJ), POINTER :: T2

T2 => BLO%ADR(2)%P

Matrix: ALLMAT

A matrix must be declared previously as a BIEF_OBJ structure. We only deal with matrices
of double precision numbers.

Syntax: CALL ALLMAT(MAT,NOM,IELM1,IELM2,CFG,TYPDIA,TYPEXT)

Arguments:

MAT : The BIEF_OBJ structure to be allocated as a vector.

NOM : Fortran name of matrix in 6 characters.

ACCESSIBILITE : FREE Page 22/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

IELM1 : Type of discretisation for rows (same convention as for the vectors).
IELM2 : Type of discretisation for columns.
CFG : Configuration. So far 2 integer values:
: CFG(1) is the storage of matrices (1: EBE, 3: edge based)
: CFG(2) is the matrix-vector product (1: EBE, 2: frontal)
TYPDIA : Diagonal type ('0' : zero, 'Q' : any, 'I' : identity)
TYPEXT : Type of the off-diagonal terms ('0': zero, 'Q': any, 'S': symmetrical)

Block : ALLBLO

A block must be declared previously as a BIEF_OBJ structure.

Syntax: CALL ALLBLO(BLO,NOM)

Arguments:

BLO : The BIEF_OBJ structure to be allocated as a block.

NOM : Fortran name of block in 6 characters.

In this case, we have an empty shell where we do not specify which objects have been placed
in the block. A block structure can thus be used again. To fill the block, the subroutine
ADDBLO must then be called (see paragraph A.I.4.4). The syntax will be:

CALL ADDBLO(BLOCK,OBJ)

to add a BIEF_OBJ structure OBJ to the block called BLOCK.

A block can be emptied by the simple line:

BLOCK%N = 0
because the component N is the number of objects in the block.

Example

We take here the example of a double precision array called SAMPLE, with one dimension,
and quasi-bubble discretisation. This vector will be then set to a constant value.

1) Declare the structure:

TYPE(BIEF_OBJ) :: SAMPLE

in a global declaration through a module, or locally.

ACCESSIBILITE : FREE Page 23/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

2) Allocate the structure:

CALL ALLVEC(1,SAMPLE,'SAMPLE',12,1,STATUT)

3) To set the value of the vector to 5.D0 for all points of the mesh, you can then do:

CALL OS('X=C ',X=SAMPLE,C=5.D0)

which is equivalent in this case to (but the following would require declaration of integer I):

DO I=1,SAMPLE%DIM1
SAMPLE%R(I)=5.D0
ENDDO

To understand this loop, remember that R is the component storing the real data of vectors,
and DIM1 the size of the first dimension. However it is not mandatory to remember this if
you use the functions and subroutines designed for operations on structures.

Operations on structures

The functions and subroutines described below are used for manipulating structures without
having to know how they are arranged. This paragraph will be limited to the functions related
to the notion of structure itself. The traditional operations on matrices and vectors will be
dealt with in Chapter A.III.

All the functions described hereafter will be naturally declared by a USE BIEF statement at
the beginning of subroutines. Otherwise they would have to be declared as EXTERNAL.

General operations on structures

LOGICAL FUNCTION CMPOBJ(T1,T2):

Up to now T1 is a vector or a block, as is T2.

CMPOBJ indicates if the two structures are identical. A check is made to see whether these
two structures are of the same type and, if so, their characteristics are compared:

- for vectors: discretisation.

- for blocks: the number of structures that it contains.

Nothing has been done so far for the other structures.

ACCESSIBILITE : FREE Page 24/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

This function is used by subroutine OS.

Operations on vectors

SUBROUTINE CHGDIS(VEC,OLDELT,NEWELT,MESH):

CHGDIS changes the discretisation of a vector.

VEC is the vector, MESH the structure containing the mesh integers. OLDELT is the former
vector discretisation and NEWELT is the new one. A vector can thus go from a linear
discretisation to a quasi-bubble discretisation, or the reverse. In the first case, the missing
values are found by linear interpolation, while in the second case the superfluous values are
forgotten. There are certain restrictions to the use of this subroutine:
- a vector cannot be extended if the required memory space is not provided for during
allocation.
- Certain changes are impossible, for obvious reasons: changing a triangle to a quadrilateral,
etc.

SUBROUTINE CPSTVC(T1,T2):

This subroutine copies a vector structure onto another. If T1 is a vector, T2 then becomes a
vector with the same characteristics. Nevertheless, the memory allocated during allocation
cannot be changed. The only data copied for the moment are:

Discretisation type (component ELM)

The first dimension (component DIM1)
The second dimension (component DIM2)
The component DIMDISC in case of discontinuous vectors.

This subroutine should be used when dealing with temporary all purpose BIEF_OBJ
structures like T1, T2, etc. in Telemac-2D and Sisyphe and T3_01, T3_02, etc. in Telemac-
3D. As a matter of fact, these structures may have been changed by a previous use, e.g. they
may have been turned into boundary vectors with a smaller size than a full domain vector,
hence an initialisation like CALL OS(‘X=0 ‘,X=T1) may have a random effect if not
secured previously by specifying what must be T1. Copying the structure of a known object
like e.g. the depth in structure H, will do it. CALL CPSTVC(H,T1) will give T1 the same
dimension and discretisation as the depth.

Operations on matrices

ACCESSIBILITE : FREE Page 25/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Note : all the operations on vectors may also be applied to the diagonal and the extradiagonal
terms contained in the matrix structure (respectively M%D and M%X for a matrix M). The
following subroutines only apply to matrices:

SUBROUTINE CPSTMT(M1,M2,TRANS):

Copies characteristics of the matrix M1 on to the matrix M2, or of transposed of matrix M1 to

M2 (if optional argument TRANS is set to true).

CPSTMT is similar to CPSTVC, it carries out the following operations:

1) copies types of elements.

2) copies types of diagonal and off-diagonal terms (calls CPSTVC for the diagonal and the
off-diagonal terms).
3) copies characteristics of the matrix (components TYPDIA and TYPEXT).
4) checks that M2 has enough memory for its new characteristics : sizes of diagonal and
extra-diagonal terms.

INTEGER FUNCTION DIM1_EXT(IELM1,IELM2,STO,TYPEXT):

The extra-diagonal terms of matrices are stored in 2-dimensional arrays. DIM1_EXT returns
the first dimension of this array, depending on:

IELM1: Type of discretisation for rows (same convention as for the vectors).
IELM2: Type of discretisation for columns.
STO : Storage of the matrix (1: EBE, 3: edge based)
TYPEXT : Type of the off-diagonal terms ('0': zero, 'Q': any, 'S': symmetrical)

INTEGER FUNCTION DIM2_EXT(IELM1,IELM2,STO,TYPEXT):

The extra-diagonal terms of matrices are stored in 2-dimensional arrays. DIM2_EXT returns
the second dimension of this array, depending on:

IELM1: Type of discretisation for rows (same convention as for the vectors).
IELM2: Type of discretisation for columns.
STO : Storage of the matrix (1: EBE, 3: edge based)
TYPEXT : Type of the off-diagonal terms ('0': zero, 'Q': any, 'S': symmetrical)

ACCESSIBILITE : FREE Page 26/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Operations on blocks

SUBROUTINE ADDBLO(BLOCK,T):

BLOCK is a block and T a structure. Adds the structure T to the block.

Reaching objects in blocks

If T1 is a vector stored as the second object in a block B, the address of T1 is B%ADR(2)%P.

As a matter of fact, ADR is an array of POINTER_TO_BIEF_OBJ structures, we take the
second one, and its unique component P (P would not be present if Fortran 90 were accepting
the arrays of pointers).

B%ADR(2)%P can then be treated as a BIEF_OBJ structure, for example the third real value
of T1 is B%ADR(2)%P%R(3). It is not recommended to deal directly with objects in blocks,
this can be done in a subroutine by calling it with the argument (e.g.) B%ADR(2)%P. It will
be then received in the subroutine as a normal BIEF_OBJ structure.

Component selectors can be piled up if blocks themselves are stored in blocks as in the
following example, where T1 as been stored as the second object into a block C stored as the
third object in the block B. T1 is then:

B%ADR(3)%P%ADR(2)%P

The only difficulty and common error is to forget the component P which is due to Fortran
obscure reasons.

BUILDING MATRICES AND VECTORS

The subroutines MATRIX and VECTOR construct matrices and vectors respectively,
according to the instructions given in their arguments.

CONSTRUCTION OF MATRICES

SUBROUTINE MATRIX( M,OP,FORMUL,IELM1,IELM2,

XMUL,F,G,H,U,V,W,
MESH,MSK,MASKEL )

ACCESSIBILITE : FREE Page 27/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The result is the matrix M, with row element IELM1 and column element IELM2, constructed
according to the formula FORMUL and the operation OP (see below). XMUL, F ,G ,H ,U ,V
,W are respectively a constant and six vector structures (defined with TYPE(BIEF_OBJ))
used in the definition of the matrix. The discretisation of F, G, H, U, V and W is checked and
is taken into account in the calculations. These last six structures must not be dummy
arguments, even if they are not used.

The other arguments are:

MESH : Mesh declared as a BIEF_MESH structure.

MSK : Logical. Indicates if the elements are masked.
MASKEL : Element masking array.

Possible operations:

OP is an operation coded in 8 characters, as for the subroutine OM. N is an internal working

matrix which contains the matrix with the formula requested (see next paragraph). M is the
matrix given by the user and which will be modified according to the operation indicated:

OP = 'M=N ' : COPY OF N ON TO M

OP = 'M=TN ' : COPY OF TRANSPOSED OF N ON TO M
OP = 'M=M+N ' : N IS ADDED TO M
OP = 'M=M+TN ' : TRANSPOSED OF N IS ADDED TO M

The operations with the form M=M+CN can be carried out through the multiplying factor
XMUL which applies to N.

Available formulae:

FORMUL is a string of 16 characters describing the formula. Generally only the first 6 are
used but extra information may be contained in characters 7 to 16. For example the sixteenth
character is sometimes used to specify the derivatives and may then contain the characters X,
Y or Z.

Available elements:

All the possible formulae are given below. However, all the discretisation combinations are
not programmed. If a matrix or a given discretisation has not been programmed, an error
message will appear to this effect.

In the next part of the text, Ψi is the base corresponding to the element IELM1 (row) and Ψ j
the base corresponding to the element IELM2 (column). The example of dimension 3 is

ACCESSIBILITE : FREE Page 28/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

given. For the other dimensions, some terms would of course have to be removed. The
beginning of names of the corresponding subroutines in BIEF are given in brackets. They are
complemented by letters indicating the elements treated. The first letter corresponds to the
row and the second letter to the column. Letter O stands for a linear segment, A for a linear
triangle, B for a quasi-bubble triangle, C for a quadratic triangle, P for a prism, T for a
tetrahedron. More specifically F stands for a vertical linear triangle which is part of the
vertical border of a mesh of prisms split into tetrahedrons. Example : subroutine MT01AA
will compute the mass-matrix of a linear triangle.

FORMUL = 'MATMAS '

(in library BIEF subroutines with names which start with MT01)

Mass-matrix.

N (i, j ) = XMUL ∫Ω Ψi Ψ j dΩ

FORMUL = 'MATDIF '

(in library BIEF subroutines with names which start with MT02)

Diffusion matrix with different coefficients according to the directions x, y and z.

In 2 dimensions:
∂Ψi ∂Ψ j ∂Ψi ∂Ψ j
N (i, j ) = XMUL ∫ (U +U ) dΩ
Ω ∂x ∂x ∂y ∂y

The case of an isotropic viscosity is given above. But the viscosity may also be tensorial. In
this case U (a BIEF_OBJ structure) must have a second dimension, for example 3 in 2-
⎛ U xx U xy ⎞
dimensional applications. U will has the general following form: U = ⎜⎜ ⎟ , but the
⎟
⎝ U yx U yy ⎠
tensor is symmetric and Uxy = Uyx.

Elements of the tensor must be stored in U as follows:

Uxx in U(*,1)
Uyy in U(*,2)
Uxy in U(*,3)

ACCESSIBILITE : FREE Page 29/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

In a 2D non isotropic case, the diffusion matrix is of the form:

∂Ψi ∂Ψ j ∂Ψi ∂Ψ j ∂Ψi ∂Ψ j ∂Ψi ∂Ψ j

N (i, j ) = XMUL ∫ (U xx + U yy + U xy + U xy ) dΩ
Ω ∂x ∂x ∂y ∂y ∂x ∂y ∂y ∂x

When a transversal Kt and longitudinal Kl dispersion are used (case of Elder's turbulence
model), the formula giving the tensor U is:

U xx = Kl cos(θ) 2 + Kt sin(θ) 2

U yy = Kl sin(θ) 2 + Kt cos(θ) 2

U xy = ( Kl − Kt ) (sin(θ) − cos(θ))

In 3 dimensions (beware, F, G and H are used in this case, unlike in 2D where U,V and
W are used):

∂Ψi ∂Ψ j ∂Ψ ∂Ψ j ∂Ψi ∂Ψ j
N (i, j ) = XMUL ∫ ( F +G i +H ) dΩ
Ω ∂x ∂x ∂y ∂y ∂z ∂z

FORMUL = 'MATDIF2 '

In 3D only, formula MATDIF2 is like MATDIF, but the hydrostatic inconsistencies are dealt
with.

FORMUL = 'MATDIF3 '

In 2D only so far, diffusion matrix with diffusion coefficients which are piece-wise linear or
constant, but may be discontinuous between elements (this is used in groundwater flows).

∂Ψi ∂Ψ j ∂Ψi ∂Ψ j
N (i, j ) = XMUL ∫ (U +V ) dΩ
Ω ∂x ∂x ∂y ∂y

Here one must have :

U%ELM=10, U%DIM2=3, U%DIMDISC=11

V%ELM=10, V%DIM2=3, V%DIMDISC=11

FORMUL = 'MASUPG '

ACCESSIBILITE : FREE Page 30/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

(subroutines with names which start with MT03)

Matrix used for the convection term with method SUPG option 1.
r r
N (i, j ) = XMUL ∫ F . grad (Ψi ) U . grad (Ψ j )dΩ
Ω

F here is a vector with the components F, G and H.

U is a vector with the components U, V and W.

FORMUL = 'MAUGUG '

(subroutines with names which start with MT04)

Matrix used for the convection term with method SUPG option 2.
r r
N (i, j ) = XMUL ∫ U . grad (Ψi ) U . grad (Ψ j )dΩ
Ω

U is a vector with the components U, V and W.

FORMUL = 'MATVGR '

(subroutines with names which start with MT05)

Matrix used for the convection term with centred discretisation.

r
N (i, j ) = XMUL ∫ Ψi U . grad (Ψ j )dΩ
Ω

U is a vector with the components U, V and W.

FORMUL = 'FMATMA '

(subroutines with names which start with MT06)

Matrix used for conservative smoothing.

ACCESSIBILITE : FREE Page 31/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

N (i, j ) = XMUL ∫ F Ψi Ψ j dΩ
Ω

FORMUL = 'MSLUMP '

(subroutines with names which start with MT07)

Mass matrix with local mass-lumping.

N (i, j ) = XMUL ∫ (1 − F ) Ψi + FΨi Ψ j dΩ

Ω

Here, F must be a P0 function, that is, constant for each element. If the value of F is locally 0,
the mass-matrix will be locally lumped into a diagonal.

FORMUL = 'MATFGR X'

(subroutines with names which start with MT08)

∂Ψi
N (i, j ) = − XMUL ∫ Ψ j F dΩ Beware the minus sign !!!!!!
Ω ∂x

If FORMUL(16:16) is equal to 'Y' or 'Z' instead of 'X', the derivative will be obtained
according to y or z.

FORMUL = 'MATQGR ' (not programmed yet)

(subroutines with names which start with MT09)

r
N (i, j ) = XMUL ∫ Ψi F U . grad (Ψ j )dΩ
Ω

Subroutines with names which start with MT10 are not yet programmed.

FORMUL = 'MATGRF X'

(subroutines with names which start with MT11)

ACCESSIBILITE : FREE Page 32/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

∂ ( F Ψi )
N (i, j ) = − XMUL ∫ Ψ j dΩ Beware the minus sign !!!!
Ω ∂x

If FORMUL(16:16) is equal to 'Y' or 'Z' instead of 'X', the derivatives will be obtained
according to y or z.

FORMUL = 'MATUGH X'

(subroutines with names which start with MT12)

Matrix used for the method SUPG, options 1 and 2.

∂F r
N (i, j ) = XMUL ∫ Ψ j U . grad (Ψi )dΩ
Ω ∂x

If FORMUL(16:16) is equal to 'Y' or 'Z' instead of 'X', the derivatives will be obtained
according to y or z.

U is a vector with the components U, V and W.

FORMUL = 'MATGRA X'

(subroutines with names which start with MT13)

Gradient matrix.

∂ Ψj
N (i, j ) = XMUL ∫Ω Ψi dΩ
∂x

If FORMUL(16:16) is equal to 'Y' or 'Z' instead of 'X', the derivatives will be obtained
according to y or z.

FORMUL = 'MAMURD PSI' or FORMUL = 'MAMURD2 PSI'

(subroutines with names which start with MT14)

Distribution matrix in case of use of the Multidimensional Upwind Residual Distribution

scheme in 3D. See reference [4] for more details.

ACCESSIBILITE : FREE Page 33/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

If FORMUL(14:16) is equal to ' N' instead of 'PSI' the matrix will be assembled.

FORMUL = 'FFBT '

(subroutines with names which start with MT99)

This is in fact a series of different matrices and the string FORMUL(8:16) is also used for
defining the formula. For example if FORMUL(8:16)=' 0XX0', the matrix will be:

∂F ∂Ψ j
N (i, j ) = XMUL ∫ F Ψi dΩ
Ω ∂x ∂x

Explanation: the term in the integral is a product of 4 terms based, for the first 2, on the vector
F, and then on the Basis function called here B and the test function called T.

If the first character is 0, the first term will be F.

∂F
If the first character is X, the first term will be .
∂x
∂F
If the first character is Y, the first term will be .
∂y

Then we proceed to second character and again function F, to third character and function
Ψ j , to fourth character and function Ψi .

Up to now the combinations 0XX0, 0YY0, XX00, 0X0Y, XY00, YY00, 0Y0X are
implemented. The formula FORMUL(8:16)='00XX+00YY' is also available. Note that
missing combinations can be obtained because the first two characters can be exchanged.
Moreover exchanging the last two characters gives the transposed matrix of the previous
formula.

The existing subroutines building matrices in version 6.0 are the following, their function can be
deduced from the explanations above:

mt01aa.f mt01bb.f mt01cc.f mt01oo.f mt01pp.f

mt01tt.f mt02aa.f mt02aa_2.f mt02bb.f mt02cc.f
mt02pp.f mt02pt.f mt02tt.f mt03aa.f mt03bb.f
mt03cc.f mt04aa.f mt04bb.f mt04cc.f mt04pp.f
mt04tt.f mt05aa.f mt05bb.f mt05cc.f mt05pp.f
mt05tt.f mt06aa.f mt06bb.f mt06cc.f mt06ff.f

ACCESSIBILITE : FREE Page 34/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

mt06ft.f mt06ft2.f mt06oo.f mt06oc.f mt06pp.f

mt06tt.f mt07aa.f mt07bb.f mt07cc.f mt08aa.f
mt08ab.f mt08ac.f mt08ba.f mt08bb.f mt08pp.f
mt08tt.f mt11aa.f mt11ab.f mt11ac.f mt11ba.f
mt11bb.f mt12aa.f mt12ab.f mt12ac.f mt12ba.f
mt12bb.f mt13aa.f mt13ab.f mt13ba.f mt13bb.f
mt13cc.f mt13ca.f mt14pp.f mt99aa.f

CONSTRUCTION OF VECTORS

SUBROUTINE VECTOR( VEC,OP,FORMUL,IELM1,

XMUL,F,G,H,U,V,W,
MESH,MSK,MASKEL )

The principle is the same as for MATRIX. The result is the vector VEC, with discretisation
IELM1, constructed according to FORMUL and the operation OP (see below).
XMUL, F ,G ,H ,U ,V ,W are respectively a constant and six vector structures used in the
definition of the new vector. The discretisation of F, G, H, U, V and W is checked and is
taken into account for the calculations.

the other arguments are the same as for MATRIX:

Possible operations:

OP may be equal to :

'=' : in this case the vector corresponds to the formula indicated.

'+' : the formula indicated is added to VEC.

Available formulae:

FORMUL is a string of 16 characters the first 6 of which take the name of the equivalent
former subroutine in BIEF version 3.0 (for certain, however, the meaning has been changed).
The sixteenth character is sometimes used to specify the derivatives and may then contain the
characters X, Y or Z.

All the possible formulae are given below. However, all the discretisation combinations are
not programmed. If a vector has not been programmed, an error message will appear to this
effect.

ACCESSIBILITE : FREE Page 35/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

In the next part of the text, Ψi is the base corresponding to the element IELM1. The example
of dimension 3 is given. For the other dimensions, some terms would of course have to be
removed. The names of the corresponding subroutines in BIEF 3.2 are given in brackets.

FORMUL = 'MASBAS '

(subroutines with names which start with VC00)

Integrals of the bases, or product of a mass matrix by a vector with the value of 1 everywhere.

VEC (i ) = XMUL ∫ Ψi dΩ
Ω

FORMUL = 'MASVEC '

(subroutines with names which start with VC01)

Product of a mass matrix by a vector F.

VEC (i ) = XMUL ∫ F Ψi dΩ
Ω

FORMUL = 'SUPG '

(subroutines with names which start with VC03)

r r
VEC (i ) = XMUL ∫ K grad ( Ψi ) U grad ( F ) dΩ
Ω

U is a vector with the components U, V and W.

K is a vector with the components G and H. (this would have to be modified in dimension 3).

FORMUL = 'VGRADP ' or 'VGRADP2 ' (used in 3D only)

(subroutines with names which start with VC04)

r
VEC (i ) = XMUL ∫ U 2 D grad 2 D ( Ψi ) dΩ
Ω

ACCESSIBILITE : FREE Page 36/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

U2D is a vector with the components U and V.

VGRADP is the same formula, with corrections when the generalised sigma transformation
is used.

FORMUL = 'FLUBOR '

(subroutines with names which start with VC05)

rr
VEC (i ) = XMUL ∫ Ψi U n dΓ
Γ

U is a vector with the components U, V and W.

n is the normal outer vector.

FORMUL = 'FLUBOR2 '

In 3D only, FLUBOR2 is like FLUBOR, but in the case of a generalised sigma

transformation.

FORMUL = 'VGRADF '

(subroutines with names which start with VC08)

r
VEC (i ) = XMUL ∫ Ψi U grad ( F ) dΩ
Ω

U is a vector with the components U, V and W.

FORMUL = 'QGRADF '

(subroutines with names which start with VC09)

r
VEC (i ) = XMUL ∫ Ψi G U grad ( F ) dΩ
Ω

U is a vector with the components U, V and W.

ACCESSIBILITE : FREE Page 37/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

FORMUL = 'FLUBDF '

(subroutines with names which start with VC10)

rr
VEC (i ) = XMUL ∫ Ψi F U n dΓ
Γ

U is a vector with the components U, V and W.

r
n is the normal vector external to the domain.

FORMUL = 'GGRADF X'

(subroutines with names which start with VC11)

VEC (i ) = XMUL ∫ Ψi G grad ( F ) dΩ

Ω

If FORMUL(16:16) is equal to 'Y' or 'Z' instead of 'X', the derivative will be obtained
according to y or z.

FORMUL = 'GRADF X'

(subroutines with names which start with VC13)

VEC (i ) = XMUL ∫ Ψi grad ( F ) dΩ

Ω

If FORMUL(16:16) is equal to 'Y' or 'Z' instead of 'X', the derivative will be obtained according to y
or z.

In 3 dimensions, variants are available:

GRADF(X,Y) X and GRADF(X,Y) Y will consider only the gradient of a function

which does not depend on Z.
GRADF2 will take care of hydrostatic inconsistencies.

FORMUL = 'PRODF '

(subroutines with names which start with VC14)

ACCESSIBILITE : FREE Page 38/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

∂U 2 ∂V ∂U ∂V 2
VEC (i ) = XMUL ∫ Ψi F (2 ( ) + 2 ( )2 + ( + ) ) dΩ
Ω ∂x ∂y ∂y ∂x

This vector is used in the calculation of the turbulent production with the model k-epsilon.

FORMUL = 'DIVQ '

(subroutines with names which start with VC15)

r
VEC (i ) = XMUL ∫ Ψi div( F U ) dΩ
Ω

U is a vector with the components U, V and W.

FORMUL = 'SUPGDIVU '

(subroutines with names which start with VC16)

r r
VEC (i ) = XMUL ∫ K grad (Ψi ) div(U ) dΩ
Ω

U is a vector with the components U, V and W.

K is a vector with the components F, G and H.

FORMUL = 'FLUDIF '

(subroutines with names which start with VC17)

r
VEC (i ) = XMUL ∫ Ψi U . grad ( F ).n dΩ
Ω

This is not currently used nor implemented.

FORMUL = 'VGRADF2 '

(subroutines with names which start with VC18)

VEC (i ) = XMUL ∫Ω Ψi U . grad ( F ) dΩ

ACCESSIBILITE : FREE Page 39/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

This is specifically for 3D computations with prisms, and unlike VGRADF, the test function Ψi is
here a 2-dimensional test function (no dependency on z). This is used by Telemac-3D in subroutine
WSTARW.

FORMUL = 'HUGRADP '

(subroutines with names which start with VC19)

r
VEC (i ) = XMUL ∫Ω F U . grad ( Ψi ) dΩ

This is used in 2D, mostly for computing fluxes. H in HUGRADP stands for the depth denoted h,
which can be misleading as it does not refer to the function H which is an argument of subroutine
r
VC19AA. A variant HUGRADP2 exists, in this case the velocity is not only U of components (U,V),
r
but U + G grad ( H ) . This is a way of treating the gradient of the free surface elevation as a
piecewise constant function, which it is in reality when the depth is linear.

The existing subroutines building vectors in version 6.0 are the following, their function can be
deduced from the explanations above:

vc00aa.f vc00bb.f vc00cc.f vc00pp.f vc00pp2.f

vc00ft.f vc00ff.f vc00tt.f vc01aa.f vc01bb.f
vc01ff.f vc01ft.f vc01oo.f vc01pp.f vc01tt.f
vc01tt0.f vc03aa.f vc03bb.f vc04aa.f vc04pp.f
vc05oo.f vc05aa.f vc04tt.f vc05ff.f vc05ft.f
vc08aa.f vc08bb.f vc08cc.f vc08pp.f vc08tt.f
vc09aa.f vc10oo.f vc11aa.f vc11aa2.f vc11bb.f
vc11pp.f vc11tt.f vc11tt0.f vc13aa.f vc13bb.f
vc13cc.f vc13pp.f vc13pp2.f vc13tt.f vc14aa.f
vc15aa.f vc16aa.f vc18pp.f vc19aa.f

OPERATIONS ON MATRICES AND VECTORS

Some operations described below also apply to vectors contained in blocks, since it is possible to
place these blocks in the subroutine arguments.

OPERATIONS ON VECTORS

ACCESSIBILITE : FREE Page 40/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

SUBROUTINE OS(OP,X,Y,Z,C,[IOPT,INFINI,ZERO]):

OP is a string of 8 characters describing an operation between X,Y,Z and C.

X is a vector or a working array which will contain the result of the operation.
Y and Z are vector structures. Y and Z can be dummy arguments if they do not appear in the
operation, but they must be declared as BIEF_OBJ structures. C is a double precision real
number.

Parameters X,Y,Z,C,IOPT, INFINI and ZERO are optional, the last 3 are used only when a
division is implied in the operation asked, for example if OP = 'X=Y/Z '. When they are
present, it is better to name them as is done in the following line:

CALL OS('X=Y/Z ',U,V,W,0.D0,IOPT=2,INFINI=1.D0,ZERO=1.D-10)

If IOPT = 1 : no check of division by 0 is made.

If IOPT = 2 : the infinite terms are replaced by the constant INFINI.
If IOPT = 3 : stop in the case of division by a number less than the parameter ZERO.
If IOPT = 4 : infinite terms are truncated at the value 1.D0/ZERO or -1.D0/ZERO
(depending on their sign).

Warning:

The structure of X is updated according to the result. Consistency checks between X, Y and Z
are applied. Y and Z must have the same discretisation.

Very important note:

When Y is mentioned in the operation and X and Y have different characteristics, the conflict
is settled by copying the characteristics of Y onto those of X (by a call to CPSTVC). This is
done without any warning message and means that vectors can be used as working arrays.
Only vectors allocated with a status equal to 1 will trigger an error message if a change of
their discretisation is tried.

The operation OP may be :

OP = 'X=C ' : C VALUE ASSIGNED TO ALL COMPONENTS OF X
OP = 'X=0 ' : C VALUE ASSIGNED TO ALL COMPONENTS OF X
OP = 'X=Y ' : Y COPIED ON TO X
OP = 'X=+Y ' : IDEM
OP = 'X=-Y ' : -Y COPIED ON TO X
OP = 'X=1/Y ' : INVERSE OF Y COPIED ON TO X
OP = 'X=Y+Z ' : SUM OF Y AND Z COPIED ON TO X
OP = 'X=Y-Z ' : DIFFERENCE OF Y AND Z COPIED ON TO X
OP = 'X=YZ ' : PRODUCT Y BY Z COPIED ON TO X
OP = 'X=-YZ ' : PRODUCT Y BY Z COPIED ON TO X
OP = 'X=XY ' : PRODUCT Y BY X COPIED ON TO X

ACCESSIBILITE : FREE Page 41/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

OP = 'X=X+YZ ' : PRODUCT Y BY Z ADDED TO X

OP = 'X=X-YZ ' : PRODUCT Y BY Z SUBSTRACTED FROM X
OP = 'X=CXY ' : PRODUCT OF C X AND Y COPIED ON TO X
OP = 'X=CYZ ' : PRODUCT OF C, Y AND Z COPIED ON TO X
OP = 'X=CXYZ ' : PRODUCT OF C, X, Y AND Z COPIED ON TO X
OP = 'X=X+CYZ ' : PRODUCT OF C, Y AND Z ADDED TO X
OP = 'X=Y/Z ' : DIVISION OF Y BY Z COPIED ON TO X
OP = 'X=CY/Z ' : PRODUCT OF C BY Y DIVIDED BY Z ET COPIED ONTO X
OP = 'X=CXY/Z ' : PRODUCT C X Y DIVIDED BY Z AND COPIED ON X
OP = 'X=X+CY/Z' : PRODUCT OF C BY Y DIVIDED BY Z ADDED TO X
OP = 'X=X+Y ' : Y ADDED TO X
OP = 'X=X-Y ' : Y SUBSTRACTED FROM X
OP = 'X=CX ' : X MULTIPLIED BY C
OP = 'X=CY ' : CY COPIED ON TO X
OP = 'X=Y+CZ ' : CZ ADDED TO Y AND COPIED ON TO X
OP = 'X=X+CY ' : CY ADDED TO X
OP = 'X=SQR(Y)' : SQUARE ROOT OF Y COPIED ON TO X
OP = 'X=ABS(Y)' : ABSOLUTE VALUE OF Y COPIED ON TO X
OP = 'X=N(Y,Z)' : X NORM OF THE VECTOR WITH COMPONENTS Y,Z
OP = 'X=Y+C ' : C ADDED TO Y COPIED ON TO X
OP = 'X=X+C ' : C ADDED TO X
OP = 'X=Y**C ' : Y AT THE POWER OF C COPIED ON TO X
OP = 'X=COS(Y)' : COSINE OF Y COPIED ON TO X
OP = 'X=SIN(Y)' : SINE OF Y COPIED ON TO X
OP = 'X=ATN(Y)' : ARCTG OF Y COPIED ON TO X
OP = 'X=A(Y,Z)' : INVERSE OF TANGENT Y/Z COPIED ON TO X
OP = 'X=+(Y,C)' : X = MAX OF Y AND C
OP = 'X=-(Y,C)' : X = MIN OF Y AND C
OP = 'X=+(Y,Z)' : X = MAX OF Y AND Z
OP = 'X=-(Y,Z)' : X = MIN OF Y AND Z
OP = 'X=YIFZ<C' : FOR EACH POINT : X = Y IF Z < C
OP = 'X=C(Y-Z)' : X = C*(Y-Z)

Examples:

CALL OS(‘X=0 ‘,X=TAB) will set the double precision array of BIEF_OBJ structure TAB
to zero.

CALL OS(‘X=Y+Z ‘,X=TRAV1,Y=U,Z=V) will copy the sum of U and V on to TRAV1.

CALL OS(‘X=Y+Z ‘,TRAV1,U,V) will have the same effect. As all the arguments are
present up to Z, there is no ambiguity.

SUBROUTINE OV(OP,X,Y,Z,C,NPOIN):

OV carries out the same operations as OS (it is called by OS), but directly on double precision
arrays and without consistency checks or structure updating. The argument NPOIN indicates
the number of values on which the operation must be conducted.

SUBROUTINE OV_2 (OP,X,IX,Y,IY,Z,IZ,C,NPOIN):

ACCESSIBILITE : FREE Page 42/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

OV_2 carries out the same operations as OV, but it is possible to choose the vector dimension
concerned by the operation. These dimension numbers are indicated by IX, IY and IZ.

The instruction:

CALL OV_2(OP,X,2,Y,5,Z,3,C,NPOIN) thus replaces the former instruction:

CALL OV(OP,X(1,2),Y(1,5),Z(1,3),C,NPOIN)

where X, Y and Z were declared as two-dimensional arrays.

SUBROUTINE OVD(OP,X,Y,Z,C,IOPT,INFINI,ZERO,NPOIN):

OVD carries out the same operations as OS (it is called by OS), but directly on double
precision arrays and without consistency checks or structure updating. The argument NPOIN
indicates the number of values on which the operation must be conducted.

SUBROUTINE
OVD_2(OP,X,DIMX,Y,DIMY,Z,DIMZ,C,DIM1,NPOIN,IOPT,INFINI,ZERO):

OVD_2 is comparable to OVD but acts on 2-dimensional vectors, the second size being
DIM1. OVD_2 will actually call OVD with X(1,DIMX), Y(1,DIMY) and Z(1,DIMZ) as
arguments instead of X, Y and Z.

DIM1 is the first dimension of vectors X, Y and Z.

SUBROUTINE OSBD(OP,X,Y,Z,C,MESH) :

The form and the principle are the same as for OS but the array MESH (mesh structure) is
given as a last argument. In this case we have vectors which would be refused by OS because
of lack of consistency. For OSBD, X is defined on the boundaries and Y and Z are vectors
defined on the whole domain. There is thus data retrieval of Y and Z, which requires the
presence of MESH.

The possible operations are as follows:

OP = 'X=Y ': BOUNDARY VALUES OF Y COPIED ON TO X

OP = 'X=+Y ': IDEM
OP = 'X=X+Y ': BOUNDARY VALUES OF Y ADDED TO X
OP = 'X=Y+Z ': BOUNDARY VALUES OF Y AND Z ADDED TO X
OP = 'X=X-Y ': BOUNDARY VALUES OF Y SUBSTRACTED TO X
OP = 'X=CY ': BOUNDARY VALUES OF CY COPIED ON TO X

ACCESSIBILITE : FREE Page 43/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

OP = 'X=X+CY ': BOUNDARY VALUES OF CY ADDED TO X

OP = 'X=CXY ': BOUNDARY VALUES OF CXY COPIED ON TO X

All the arguments are mandatory.

SUBROUTINE OVBD(OP,X,Y,Z,C,NBOR,NPTFR) :

Same role as OSBD but by giving the general numbering of the boundary points and the
number of boundary points. OVBD does not conduct any check.

SUBROUTINE OSDB(OP,X,Y,Z,C,MESH) :

Same principle as for OSBD. Here, X is defined on the entire domain and Y and Z are vectors
defined on the boundaries. Only the X values corresponding to boundary points are filled.

The following operations are possible:

OP = 'X=Y ' : Y COPIED ON TO X

OP = 'X=+Y ' : IDEM
OP = 'X=X+Y ' : Y ADDED TO X
OP = 'X=X-Y ' : Y SUBSTRACTED FROM X
OP = 'X=CY ' : CY COPIED ON TO X
OP = 'X=Y+Z ' : Y+Z COPIED ON TO X
OP = 'X=X-YZ ' : YZ SUBSTRACTED FROM X
OP = 'X=X+CY ' : CY ADDED TO X
OP = 'X=XY ' : X MULTIPLIED BY Y

SUBROUTINE OSDBIF(OP,X,Y,Z,C,INDIC,CRITER,MESH):

Same principle as for OSDB but a test is done. If INDIC(K)=CRITER, the operation OP is
done on index number K of vector X.

The following operations are possible:

OP = 'X=Y ' : Y COPIED ON TO X

OP = 'X=+Y ' : IDEM

INDIC is an integer array (not a structure). CRITER is a given integer.

SUBROUTINE OVDB(OP,X,Y,Z,C,NBOR,NPTFR):

Same role as OSDB but by giving data from MESH, the general numbering of the boundary
points and the number of boundary points. OVDB does not conduct any check.

ACCESSIBILITE : FREE Page 44/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

OPERATIONS ON MATRICES

SUBROUTINE OM(OP,M,N,D,C,MESH) :

OP is the operation to be carried out. M and N are two matrices, D a diagonal and C a
constant. N, D and C are only used when they are part of the operation. MESH is the integer
block of the mesh.

The following operations are possible:

OP = 'M=N ' : COPY OF N ON TO M

OP = 'M=TN ' : COPY OF TRANSPOSED OF N ON TO M
OP = 'M=CN ' : PRODUCT OF N BY THE C CONSTANT
OP = 'M=M+CN ' : CN ADDED TO M
OP = 'M=M+CTN ' : C TIMES TRANSPOSED OF N ADDED TO M
OP = 'M=M+N ' : N ADDED TO M
OP = 'M=M+TN ' : TRANSPOSED OF N ADDED TO M
OP = 'M=MD ' : RIGHT HAND PRODUCT OF M BY D
OP = 'M=DM ' : LEFT HAND PRODUCT OF M BY D
OP = 'M=DMD ' : LEFT AND RIGHT HAND PRODUCT OF M BY D
OP = 'M=0 ' : M COMPONENTS ARE SET TO 0
OP = 'M=X(M) ' : CHANGE TO A NON SYMMETRICAL FORM
OP = 'M=MSK(M)' : MASKING EXTRADIAGONAL TERMS
OP = 'M=M-DN ' : REMOVING DN FROM M
OP = 'M=M-ND ' : REMOVING ND FROM M
OP = 'M=M+D ' : Diagonal D added to M

When the operation only concerns M, it is advisable to repeat M instead of the argument N. In
all cases N should be a matrix-structure, or it may generate inexplicable crashes.

It is possible that a few of these operations are not yet programmed with all the matrix-
storage.

SUBROUTINE LUMP(DIAG,A,MESH,XMUL):

Returns a vector representing a diagonal matrix DIAG (in fact a BIEF_OBJ structure
with a vector type) containing the sum of the rows of the matrix A. The other arguments are
given below:

MESH: Mesh structure.

XMUL: Multiplying factor.

ACCESSIBILITE : FREE Page 45/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

MATRIX x VECTOR PRODUCTS

SUBROUTINE MATVEC(OP,X,A,Y,C,MESH,[LEGO]) :

The result is the vector X (BIEF_OBJ structure) which, depending on the operation
OP, contains different combinations of X, C and the product of A and Y:

OP = 'X=AY ' : X = AY
OP = 'X=X+AY ' : X = X + AY
OP = 'X=X-AY ' : X = X - AY
OP = 'X=X+CAY ' : X = X + C AY
OP = 'X=TAY ' : X = TA Y (TRANSPOSED OF A)
OP = 'X=X+TAY ' : X = X + TA Y
OP = 'X=X-TAY ' : X = X - TA Y
OP = 'X=X+CTAY' : X = X + C TA Y

The other arguments are:

MESH : Mesh integer structure.

Optional argument:

LEGO : Logical.

If LEGO is equal to .FALSE., the vector X will not be assembled and part of the result (due to
the off-diagonal terms of A) will be contained in the array W of structure MESH. The vector
X will contain only the contribution of the diagonal.

The aim of LEGO=.FALSE. is to save on assemblies during calculations where X is the sum
of several matrix x vector products.

Thus to calculate X = A Y + B Z, the following two calls will be made one after the other:

CALL MATVEC('X=AY ',X,A,Y,C,MESH,LEGO=.FALSE.)

CALL MATVEC('X=X+AY ',X,B,Z,C,MESH,LEGO=.TRUE.)

This will save on the assembly of the product A Y.

SUBROUTINE MATRBL(OP,X,A,Y,C,MESH):

ACCESSIBILITE : FREE Page 46/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The principle is the same as MATVEC but MATRBL applies to blocks.

If A is a block of 4 matrices. X and Y must be blocks of 2 vectors.

If A is a block of 9 matrices. X and Y must be blocks of 3 vectors.

The only operations that are possible for the moment are:

OP = 'X=AY ' : X = AY
OP = 'X=TAY ' : X = TA Y (TRANSPOSED OF A)

SOLVING LINEAR SYSTEMS

The processing of a linear system is handled entirely by the subroutine SOLVE,

except for the Dirichlet-type boundary conditions processed by DIRICH (see also B.III.5).

SUBROUTINE DIRICH ( F,S,SM,FBOR,LIMDIR,WORK,

MESH,KDIR,MSK,MASKPT)

F <--> INITIAL AND FUTURE SOLUTION OF THE SYSTEM

S <--> SYSTEM MATRIX
SM --> RIGHT HAND SIDE OF SYSTEM ("SECOND MEMBRE" IN
FRENCH)
FBOR --> DIRICHLET POINT BOUNDARY CONDITION
LIMDIR --> BOUNDARY CONDITIONS TYPE
IF LIMDIR(K) = KDIR THE Kth BOUNDARY POINT
IS A DIRICHLET TYPE POINT.
WORK --> WORKING ARRAY BLOCK.
KDIR --> CONVENTION FOR DIRICHLET CONDITIONS
MESH --> BIEF_MESH STRUCTURE
MSK --> IF YES, PRESENCE OF MASKED ELEMENTS
MASKPT --> MASKED POINTS ARRAY
=1. : NORMAL =0. : MASKED POINT

If S is a block of 4 or 9 matrices, F must be a block of 2 or 3 vectors, LIMDIR must be an array with

2 or 3 dimensions, and FBOR must be an array of 2 or 3 vectors.

DIRICH will modify the matrices and right hand sides of the system to take into account the
prescribed values.

ACCESSIBILITE : FREE Page 47/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

SUBROUTINE SOLVE(X,A,B,TB,CFG,INFOGR,MESH,AUX)

X : Solution vector.
A : System matrix.
B : Second member of system.
TB : Block containing working arrays.
CFG : Solver configuration.
INFOGR : if .TRUE., information will be printed.
MESH : : BIEF_MESH structure.
AUX : Matrix used for preconditioning. Not used by diagonal
preconditioning

Here is the meaning of options stored in the SLVCFG structure called above CFG:

CFG%METHOD:

Value of METHOD Meaning

1 CONJUGATE GRADIENT
2 CONJUGUATE RESIDUAL
3 NORMAL EQUATION ON CONJUGATE
GRADIENT
4 MINIMAL ERROR
5 CONJUGATE GRADIENT SQUARED
6 CONJUGATE GRADIENT SQUARED
STABILISED
7 GMRES

CFG%KRYLOV : Only used by GMRES. The option is the dimension of Krylov's

space (see ref. [3]).

CFG%PRECON : Preconditioning choice.

Value of PRECON Meaning

1 NOTHING
2 DIAGONAL PRECONDITIONING
3 BLOCK-DIAGONAL PRECONDITIONING
5 DIAGONAL PRECONDITIONING
with absolute values of diagonal
7 CROUT PRECONDITIONING
11 GAUSS-SEIDEL EBE PRECONDITIONING
13 MATRIX GIVEN BY THE USER
17 SPECIFIC TO TELEMAC-3D. DIRECT
SOLUTION ON VERTICALS ARE USED
AS PRECONDITIONING.

ACCESSIBILITE : FREE Page 48/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

CFG%EPS : Relative accuracy requested, or absolute if norm of the right-hand side

is less than 1..
CFG%ZERO : Epsilon for the divisions by zero.
CFG%NITMAX : Maximum number of iterations.

TB will be used by SOLVE to find BIEF_OBJ structures with working arrays. The number of
structures to be placed in TB depends on the method chosen. At the time being, the minimum number
of arrays in TB must be: S*MAX(7,2+2*METHOD%KRYLOV) where S is 1 if the system is made
of 1 matrix, 2 for blocks of 4 matrices (2 unknowns like in ARTEMIS) and 3 for blocks of 9 matrices
(3 unknowns like in Telemac-2D).

PARALLELISM

Parallelism consists of using simultaneously a cluster of computers, or a group of processors

in the same computer, to solve a single problem. Using n processors would ideally divide by
n the time necessary to solve the same problem with only one processor. The task would be
easy if the problem could be broken down into sub-tasks, independent of each other. It
becomes much more difficult when each processor needs the results from the others. We will
focus hereafter on parallelism performed with processors having each its own memory, and
communicating with the others via message transmission, this is the case with networks of
work stations or PC's and is known as distributed-memory parallelism.
Many experiments in automatic parallelism, where compilers themselves perform the task of
optimizing the program, showed very poor improvement in CPU time. Furthermore,
vectorization and parallelism appeared to be contradictory. Vectorization requires simple
loops to perform sub-tasks whereas distributed-memory parallelism hands over complex tasks
to each processor so as to optimize communication time and data transmission time.
Efficiently vectorized software would be naturally poorly parallelized. As an example, the
assembly loops resulting from an EBE matrix-vector product cannot be accelerated by more
than a ratio of two even if we overlook the communication time. This is due to the fact that
the results of each processor have to be assembled. That leads to a new cost which limits
drastically the overall time to be gained. This is known as a granularity problem, the size of
the tasks to be parallelized being too small. It is unlikely that progress in the algorithm would
help in solving this theoretical bottleneck. From that, the idea emerges to break up the
problem in another way: not by isolating small tasks but in a kind of geographical way, by
decomposing the domain of computation. This idea of domain decomposition aims at
assigning onto each processor one part of the domain over which it would solve the fluid
mechanics problem. The implementation is quite easy in the case of explicit algorithms: each
equation is only a function of the variables related to the nodes in the immediate vicinity,
computed at the earlier time step. Each processor is then in charge of the equations related to
a group of nodes, and of the data concerning the neighbours of these nodes, resulting from the
previous time step. This is executed merely by a partition of the domain, with an overlap of
one element, and data transmission at the end of each time step. In the case of our implicit

ACCESSIBILITE : FREE Page 49/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

algorithms, and especially with linear systems solved on the whole domain, the
implementation is more complex, though possible. In fact, we can guarantee that the results
of a parallel computation will be the same as a scalar computation, except for truncation
errors because computations will not be performed in the same order. Parallelism (initially
implemented on our algorithms by Reinhard Hinkelmann at the University of Hanover can be
limited to the following problems:
- Partition of the domain,
- Communication between processors.
- Implementation of some basic algorithms: vector assembly, dot product, computation of
normal vector and so on.
We will examine these three points hereafter.

Partition of the domain

In the case of finite element meshes and implicit algorithms, it is better to partition without
overlapping, edge to edge. The specifications for an efficient domain decomposer would be
the following:
- realizing a partition of meshes of triangles (the sub-domains of three-dimensional meshes of
prisms will be made from sub-domains of triangles).
- partitioning the domain into blocks in order to ensure a balance between the processors.
Because the main algorithms are made of loops over the elements and nodes, the partition
will guarantee a balance between the numbers of elements, or similarly between the number
of nodes within each sub-domain.
- minimizing the number of nodes shared by different sub-domains and for which
communications between processors will be necessary.

We currently use the Metis mesh partitioner, which is available on the web site: http://www-
users.cs.umm.edu/~karypis/metis.

Data structure specific to parallelism

We describe here some of the data structures that will be often used in parallelism.

Each sub-domain is assigned to a processor together with the information of a standard

domain (connectivity table IKLE, nodes coordinates and so on) but also with additional
information, to help in assembling the results over the whole domain at the end of the
computation. This information is as follows:
- an array KNOLG storing the global numbers of the nodes in the whole mesh. The inverse
array, KNOGL, is defined within a loop:
DO I=1,NPOIN
KNOGL(KNOLG(I))=I
ENDDO
- an array NACHB whose dimension is (5,NPTIR), where NPTIR is the number of the
interfacial nodes between the sub-domain and the others. These interfacial nodes are
numbered from 1 to NPTIR. NACHB(1,IR) is the global number of the interfacial node IR.
This array gathers the information to be transmitted to the others processors. The integers

ACCESSIBILITE : FREE Page 50/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

NACHB(2,IR) to NACHB(5,IR) are the numbers of the other sub-domains which the nodes
belong to. They may have a -1 value if these sub-domains are less than 4. The dimension 5
must be increased if a node belongs to more than 5 sub-domains.
Some additional information has to be defined on the actual boundary nodes of a 2-
dimensional domain:
ISEG, XSEG, YSEG and NUMLIQ.
If ISEG >0: the boundary node just after belongs to another sub-domain, its global number is
ISEG, and its real coordinates are XSEG and YSEG.
If ISEG <0: the boundary node just before belongs to another sub-domain, its global number
is -ISEG, and its real coordinates are XSEG and YSEG.
If ISEG = -999999: the node verifies the two conditions above (this pathological case is not
considered by the software).
The latest algorithms designed in Telemac replaced the use of XSEG and YSEG by parallel
communications, thus these arrays could be removed in a near future.
- the integer array NUMLIQ is a specific numbering of the liquid boundaries, which allows
association of boundary conditions to them, e.g. an imposed discharge. A numbering is easy
to define when the whole domain is known. A possible convention is to start the numbering
of these liquid boundaries (inflow and outflow) from the extreme south-west node of the
domain and proceeding in the anti clock-wise way along the edge. In the case of a sub-
domain for which it is not possible to go over the whole contour, the numbering must be
specified because it cannot be simply recomputed.
- IFAPAR is used by the method of characteristics to compute the paths or trajectories when
they cross interfaces between sub-domains. The size is IFAPAR(6,NELEM2), as only 2-
dimensional data is required. IFAPAR(1:3,IELEM) gives the processor numbers behind the 3
edges of a triangle. IFAPAR(4:6,IELEM) gives, for the same edges, the local number in its
processor of the element behind the edge.
- an array INDPU, inverse of NACHB(1,*) helps storing the data received from the other
processors: INDPU(NACHB(1,I))=I. Given the number of an interfacial node, INDPU sends
back its global number within the sub-domain.
- an array FAC, providing for each node, the inverse of the number of sub-domains to which
it belongs (see the algorithm for dot product hereafter).

Communication between processors

Programming by communicative process requires the use of a library of communication

functions, such as PVM or MPI. We currently use MPI version 2. These libraries perform
different operations:
- setting up of the parallel machine, that is, organizing the communication between various
computers or processors,
- running programs on all the processors (spawn order with PVM).
In some cases, one processor has the function of a master, the others being the slaves. The
program is first run on the master processor, and includes a start order for the slaves. A group
name is given to the computation. Apart from this initialization step, there is then no more
hierarchy between the processors.

ACCESSIBILITE : FREE Page 51/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

- various kinds of communication: point to point or collective.

Point to point communication
This is the basic communication between two processors, the receptor and the transmitter.
The send function and the receive function can differ depending on the types of data
(integers, real numbers, etc.). The functions arguments are:
- identifier of receptor or transmitter,
- address of the data to transmit or receive,
- a message flag.
Transmissions can be made in two ways. Synchronous transmission occurs when waiting for
the receptor to be ready; this avoids a copy in the buffer. Asynchronous transmission occurs
whatever the state of the reception.
Collective communication
Collective communications use simultaneously all the processors. Three types may be
distinguished:
- broadcast: a processor (generally the master) sends the same data to all the slaves,
- synchronization: refers to a barrier which all processors must reach before going on the
computation,
- conditional transmission: each processor sends a data and receives in return the sum, the
maximum or the minimum of all the data transmitted.
To make the source programs independent of the choice of the communication functions
library, it is worth writing an interface library to deal with all the communications between
the processors. In Telemac this library is called “parallel”. When there is no parallelism
involved a fake library “paravoid” is used instead, which does not contain any link to a
parallelism library. Only a few functions are necessary:
P_DMAX(X): maximum of X over all the processors. X is a double-precision real.
P_DMIN(X): minimum of X over all the processors. X is a double-precision real.
P_DSUM(X): sum of all the values of X provided by all the processors. X is a double-
precision real.
P_IMAX(I): maximum of I over all the processors. I is an integer.
P_IMIN(I): minimum of I over all the processors. I is an integer.
P_ISUM(I): sum of all the values of I provided by all the processors. I is an integer.
P_MAIL(CHAINE,NCAR): broadcasting a character string CHAINE, with a length NCAR,
to all the processors.
P_READ(BUFFER,NBYTES,SOURCE,TYPE): reading of NBYTES bytes of data whose
type is TYPE, to be stored at the address BUFFER and sent by the processor SOURCE.
P_SYNC: stops the processors till all of them call this function.
P_WRIT(BUFFER,NBYTES,DEST,TYPE): writing of NBYTES bytes of data, whose type is
TYPE, located at the address BUFFER and intended for the processor DEST.

Adaptation of the algorithms

Dot product

ACCESSIBILITE : FREE Page 52/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The dot product of two vectors over the whole domain implies local computing first, then
summing up over the whole sub-domains. While summing, the interface nodes are taken into
account several times. The array FAC is then used to correct this error. The parallel dot
product P_DOT of the vectors X and Y is written as follows:
P_DOT = 0.D0
DO I=1,NPOIN
P_DOT=P_DOT+X(I)*Y(I)*FAC(I)
ENDDO
P_DOT=P_DSUM(P_DOT)

On a vector computer, multiplying by FAC(I) does not affect the time of computation. On the
contrary, the call to the P_SUM routine causes a synchronization of the processors.

Matrix x vector product

First, building the matrices and computing the product are done locally, independently of the
other sub-domains. The result is a vector without any contribution from the neighbour sub-
domains, on the interfacial nodes. The missing contributions result from the computation of
the vector on the other sub-domains. For example, if the node I belongs to two different sub-
domains, for which we get X(I)=3 and X(I)=5 respectively, the actual value of X(I) would be
the sum 3+5. This can be achieved if processor 1 sends the value 3 to processor 2 and
processor 2 sends the value 5 to processor 1. Although it appears simple, this operation is
quite complex to achieve because it can lead to a fatal risk: both processors waiting endlessly
for the contribution of the other before sending their own. We describe hereafter the series of
operations required, known as “blocking communication”. More recently, a non-blocking
communication scheme has been implemented by Pascal Vezolles from IBM Europe.
Basically this second approach consists of providing MPI with the list of communications to
perform, and MPI internal routines will organize the work with their own algorithms.

Communication of data after a matrix-vector product:

Up to version 5.8:

Generally speaking we have a number of processors which much send or receive information
to or from the others. The main difficulty is to avoid blocked situations where two processors
would wait to receive information from each other before sending their own, hence the
definition of higher rank and lower rank processors. We have kept the explanations on this
obsolete implementation because it really tackles the problem, while the new implementation
from version 5.9 on only uses the capabilities of the MPI language, namely the non blocking
communication with subroutines MPI_IRECV and MPI_ISEND.

The transmission is split into 4 different tasks, depending on the rank of the processors:
- transmission of the data to the higher rank processors.
- reception by the higher rank processors.
- transmission of the data to the lower rank processors.

ACCESSIBILITE : FREE Page 53/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

- reception by the lower rank processors.

New data are required for every processor. Each processor prepares its own numbering of
higher rank and lower rank processors as well as a numbering of nodes interfacing with each
of these processors. 4 new arrays IKP, NHP, IKM and NHM are necessary to navigate from
one numbering to another:
- IKP(NBMAXDSHARE,2): IKP(IZH,1) refers to the processor which is the IZH th local
higher rank processor. IKP(IZH,2) is the number of interfacial nodes shared with this
processor. NBMAXDSHARE is defined in BIEF_DEF where it is set to 80. It is the
maximum number of sub-domains neighbouring a given sub-domain.
- IKM(NBMAXDSHARE,2): IKM(IZH,1) refers to the processor which is the IZH th local
lower rank processor. IKM(IZH,2) is the number of interfacial nodes shared with this
processor.
- NHP(NBMAXDSHARE,NPTIR): NHP(IZH,IR) is the global number in the sub-domain of
a point whose number is IR in the interface with the IZH th higher rank processor.
- NHM(NBMAXDSHARE,NPTIR): NHM(IZH,IR) is the global number in the sub-domain
of a point whose number is IR in the interface with the IZH th lower rank processor.
ILMAX is the maximum distance in order between the processor and its neighbours. It will
restrict the size of the loops over these neighbours.
Considering this information, the data transmission for vector V (defined over the whole
domain) and for processor IPID, is written as follows:

1) storage of the data to be sent in a first buffer:

DO I=1,NPTIR
BUF(I)=V(NACHB(1,I))
ENDDO

2) transmission to higher rank processors, for example processor ILP

2.1) storage of the data relative to the processor in a second buffer
DO I=1,IKP(ILP,2)
ERGBUF(I)=BUF(INDPU(NHP(ILP,I)))
ENDDO
2.2) sending
CALL P_WRIT(ERGBUF,8*IKP(ILP,2),
IKP(ILP,1),ABS(IKP(ILP,1)-IPID)

3) reception from lower rank processors, for example processor ILM

3.1) reception
CALL P_READ(ERGBUF,8*IKM(ILM,2),
IKM(ILM,1),ABS(IKM(ILM,1)-IPID)
3.2) storage in vector V
DO I=1,IKM(ILM,2)
V(NHM(ILM,I))=V(NHM(ILM,I))+ERGBUF(I)
ENDDO

ACCESSIBILITE : FREE Page 54/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

4) transmission to lower rank processors, for example processor ILM

4.1) storage of the data relative to the processor in a second buffer
DO I=1,IKM(ILM,2)
ERGBUF(I)=BUF(INDPU(NHM(ILM,I)))
ENDDO
4.2) sending
CALL P_WRIT(ERGBUF,8*IKM(ILM,2),
IKM(ILM,1),ABS(IKM(ILM,1)-IPID)

5) reception from upper rank processors, for example processor ILP

5.1) reception
CALL P_READ(ERGBUF,8*IKP(ILP,2), IKP(ILP,1),ABS(IKP(ILP,1)-IPID)
5.2) summing into vector V
DO I=1,IKP(ILP,2)
V(NHP(ILP,I))=V(NHP(ILP,I))+ERGBUF(I)
ENDDO
This algorithm can be made more complex to process several vectors at the same time or for
tasks different from summing.

From version 5.9 on:

The implementation is much easier with the MPI subroutines MPI_IRECV and MPI_ISEND
(see subroutine PARACO). Only lists of processors are necessary, regardless of any order in
the communications, the rest is handled by MPI. To achieve this, a number of new data have
been added to the BIEF_MESH structure. They are listed below. Moreover in version 5.9
parallel communication data linked to segments have been added, which doubles the
necessary data.

NB_NEIGHB: number of neighbouring processors (seen by points).

NB_NEIGHB_SEG: number of neighbouring processors (seen by segments).

NB_NEIGHB_PT: number of points shared with processors (array of size NB_NEIGHB).

NB_NEIGHB_PT_SEG: number of segments shared with processor I (array of size
NB_NEIGHB_SEG).

LIST_SEND: list of neighbouring processors to which data must be sent (seen by points).
LIST_SEND_SEG: list of neighbouring processors to which data must be sent (seen by
segments).

There should be also accordingly a LIST_RECEIVE, but it is actually exactly like

LIST_SEND, so it has not been created.

ACCESSIBILITE : FREE Page 55/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

NH_COM: array of size (DIM1NHCOM,NB_NEIGHB). DIM1NHCOM is at least the

maximum number of points that can be shared with a single processor. It can be slightly more
for optimisation (see subroutine PARINI). NH_COM(I,J) is the global number in the sub-
domain of the Ith point shared with the Jth neighbouring processor.
NH_COM_SEG: like NH_COM but for segments.

BUF_SEND: buffer of memory that will be used by MPI subroutines.

BUF_RECV: buffer of memory that will be used by MPI subroutines.

Specific cases

It is worth noting that just a few alterations of the scalar and matrix-vector products are
sufficient to solve a linear equation with partial derivative in shared memory. Furthermore,
the contributions of the interfacial terms can be postponed until the final solving. They would
be necessary before only if real nodal values, dot product, matrix-vector product or final
results are needed. For a linear equation, these operations can be confined in the resolution of
the linear system. Once the tools have been set up to communicate between processors,
parallelization of fluid mechanics software is quite easy. However, specific cases, arising
mainly from non-linearity have to be considered. The basic idea is to get identical results on
vector or parallel computers, except for truncation errors. Some examples follow:
- diagonal preconditioning: the diagonal used for preconditioning has to be completed at the
interfaces.
- computation of nodal values after projection onto a basis: let us consider the gradient of a
function f . A mean nodal value of grad ( f ) is given by:
∫Ω grad ( f )Ψi dΩ
grad ( f ) i =
∫Ω Ψi dΩ
issued from the mean-value theorem. In this case the computation of the general term
∫Ω Ψi dΩ has to be completed at the interfaces. The vector including: ∫Ω grad ( f )Ψi dΩ
is unchanged when added to the right-hand side of a linear system (the solver itself will
complete this term). However it must be completed when used to compute another term such
as a turbulent production.
- any global concept: maximum Courant number, maximum Froude number, etc., have to be
transmitted between processors.
- the method of characteristics: for high values of the Courant number, a characteristic curve
may leave a sub-domain and enter others. Programming this situation within the parallel
architecture requires a huge number of random transmissions, depending on the flow. The
implementation of this technique in parallel has been achieved by Jacek Jankowski from
BundesAnstalt für Wasserbau in Germany.

UTILITIES
A number of tools are offered in BIEF, in the form of functions and subroutines.

ACCESSIBILITE : FREE Page 56/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

FUNCTIONS

All the functions described below facilitate programming and avoid transmission of
arguments.

INTEGER FUNCTION DIMENS(IELM):

IELM is a type of element. DIMENS returns the dimension corresponding to the element
given. For example, DIMENS(11) = 2.

DOUBLE PRECISION FUNCTION DOTS(T1,T2):

T1 and T2 may be two vectors, or two blocks.

For vectors, returns their scalar product. For blocks, returns the sum of the scalar products of the
vectors they contain.
Warning: only the first dimension of the vectors is taken into account for the time being.

See also P_DOTS

LOGICAL FUNCTION EOF(LUNIT):

LUNIT is the logical function of a file. EOF says if we are at the end of this file or not.

INTEGER FUNCTION IELBOR(IELM,I):

Returns the type of boundary element associated with a given element. For example, IELBOR(11,1)
= 1. I is used when there are several types of boundary elements. For a prism, for example,
IELBOR(41,1)=11 and IELBOR(41,2)=21.

INTEGER NBFEL(IELM):

Returns the number of faces for the element type IELM (value initialised in ININDS)

INTEGER NBPEL(IELM):

Returns the number of points per element for the element type IELM. (value initialised in ININDS)

INTEGER NBMPTS(IELM):

Returns the maximum number of points in the domain for a given discretisation, in the case of an
adaptive mesh. For the time being, this function is equal to NBPTS.

INTEGER NBPTS(IELM):

ACCESSIBILITE : FREE Page 57/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Returns the number of points in the domain for a given discretisation (value initialised in ININDS).

DOUBLE PRECISION FUNCTION P_DOTS(T1,T2,MESH):

As DOTS but takes into account domain decomposition. P_DOTS will thus communicate with other
processors to get their contribution.

MESH is the mesh structure.

Warning: only the first dimension of the vectors is taken into account for the time being.

DOUBLE PRECISION FUNCTION BIEF_SUM(T1):

T1 may be a vector, or a block.

For a vector, returns the sum of the vector components. For a block, returns the sum of all the
components of the vectors it contains.

Warning: only the first dimension of the vectors is taken into account for the time being.

INTEGER FUNCTION TIME_IN_SECONDS():

Returns the time in seconds given by the computer clock. For computing the elapse time of a job.
Beware, this value is sometimes reset to zero by the computer, generally every 24 hours.

BASIC SUBROUTINES

SUBROUTINE BIEF_CLOSE_FILES(CODE,FILES,NFILES,PEXIT)

Replaces the old CLOSE_FILES or CLOSE_FILES2

CODE is a 20 characters string saying which programme calls the subroutine, for example
'ARTEMIS'.
FILES is an array of BIEF_FILE structures containing a description of all files used by the program.
NFILES is the number of files (and dimension of FILES)
PEXIT is a logical value. If yes, the call to the subroutine will also trigger an exit from MPI.

ACCESSIBILITE : FREE Page 58/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

All the relevant files, whose names are known through the DECLARATIONS_TELEMAC module,
are closed by this subroutine.

SUBROUTINE CLIP(VEC,XMIN,CLPMIN,XMAX,CLPMAX,NPOIN)

CLIP clips an array of real values:

Lower values limited by XMIN if the logic CLPMIN is true.

Upper values limited by XMAX if the logic CLPMAX is true.

CLIP can handle vector structures as well as conventional FORTRAN arrays.

For a conventional array, NPOIN is taken as a dimension of the array.

VEC must be a BIEF_OBJ structure of vector type:

If NPOIN = 0, the dimension given by the structure is taken.

If NPOIN<0, the dimension -NPOIN is imposed. This must then be less than
or equal to the real dimension.

SUBROUTINE FILTER( VEC,BLDMAT,T1,T2,A,FORMUL,

XMUL,F,G,H,U,V,W,MESH,
MSK,MASKEL,N)

Filtering operation of the vector VEC. T1 and T2 are working BIEF_OBJ structures. From
XMUL, the arguments are the same as those of MATRIX. A is a matrix which is either given
(if the logical value BLDMAT is false), or constructed according to the formula FORMUL (if
BLDMAT is true). In the latter case, the arguments F, G, H, U, V, W, may be used if they
appear in the formula FORMUL.

VEC is modified N times by FILTER according to the following formula:

new VEC = XMUL A VEC where AL is the diagonal matrix obtained by mass-lumping A, that is
AL
by totalling the terms in each row.

If A is a mass matrix (FORMUL = 'MATMAS '), a smoothed vector VEC is obtained, with its
integral in the domain (the 'mass') preserved.

If FORMUL = 'FMATMA ', a smoothed vector VEC is obtained, with preservation of the
integral of the function F VEC.

ACCESSIBILITE : FREE Page 59/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

SUBROUTINE BIEF_OPEN_FILES(CODE,FILES,NFILES,PATH,FLOT,IFLOT,ICODE)

Replaces the old OPEN_FILES, to enable coupled programs to run concurrently even if they use the
same logical units.

The first three arguments are like BIEF_CLOSE_FILES.

PATH is the full name of the path leading to the directory containing the files (or at least the
parameter file).

FLOT is a logical value stating if there is code coupling. In this case the logical units of every file are
dynamically computed and will start at IFLOT+1, IFLOT being the argument after FLOT..

IFLOT: see explanations on FLOT above.

ICODE is the code number in case of coupling (the calling program will be code 1, the called
program will be code 2).

The basic data for opening the files is stored in the dictionary of each program, namely in the key-
word called SUBMIT. Here is the example for the geometry file in Telemac-2D:

SUBMIT : 'NGEO-READ-01;T2DGEO;OBLIG;BIN;LIT;SELAFIN-GEOM'

NGEO is no longer used.

READ means that this file will be opened in only read mode.
01 is the file number. It also means that when there is no code coupling, the value of the logical unit
will be 1 (in code coupling this value is floating and will be decided by the program itself).

T2DGEO will be the name of the file in the temporary directory where the case will be run. T2DGEO
is also declared in Telemac-2D as an integer which is the file number. It will be 1 and will not float in
case of code coupling.

OBLIG means that the file is mandatory

BIN means that it is a binary file

LIT is a message for parallelism that the file will be read by every processor and must thus be copied
for every of them. ECR would mean that it is a result that must be given back with an extension
indicating the processor number.

SELAFIN-GEOM indicates that the file is at the SELAFIN format and GEOM says that it must be
taken as the geometry file for domain decomposition. Other possibilities are : CAS (steering file),

ACCESSIBILITE : FREE Page 60/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

DICO (dictionary), CONLIM (boundary conditions to be taken into account in domain

decomposition).

All the possibilities are documented in the dictionaries of parallelised programs.

The last argument ICODE is the program number in case of coupling. So far some data in BIEF
library are concurrently used by coupled programs, hence BIEF must now which program is running,
this is done by using: CALL CONFIG_CODE(ICODE) when shifting to another program in code
coupling, CONFIG_CODE will thus avoid conflicts between files.

Note : the parameter file and the dictionary have prescribed names and are not opened by
BIEF_OPEN_FILES. For example, in Telemac-2D they are opened and closed in subroutine
LECDON_TELEMAC2D.

SUBROUTINE PARCOM(X,ICOM,MESH)

PARCOM completes the matrix-vector product in parallelism, by adding to a vector X contributions

from elements that are in other sub-domains.

X is a BIEF_OBJ structure of a vector or a block of vectors.

ICOM is an option.
MESH is the BIEF_MESH structure of the mesh.

ICOM = 1: the contribution with maximum absolute value is taken.

ICOM = 2: the sum of contributions is taken (the most widely used option).
ICOM = 3: the maximum value is taken.
ICOM = 4: the minimum value is taken.

This subroutine is able to work in 2D and 3D as well. Blocks of vectors are also treated. In 2D it will
also cope with quadratic discretisation, which implies not only a communication of points, but also of
segments. PARCOM calls a subroutine PARCOM2 and a subroutine PARCOM2_SEG which act
directly on real vectors. The call to PARCOM may be bypassed in specific cases, e.g. when a parallel
communication of segments is required.

SUBROUTINE PARMOY(X,MESH)

PARMOY is used in parallelism to give the mean value of a vector X at the interface between 2 sub-
domains. MESH is the BIEF_MESH structure of the mesh.

SUBROUTINES DEALING WITH THE SELAFIN FORMAT FILE

ACCESSIBILITE : FREE Page 61/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The SELAFIN format is used in 2D and 3D for the results files and for the geometry files. It is
given in appendix 3. Several routines are offered for writing or reading such files. Others remain
internal routines in BIEF and will be called directly either by ALMESH or INBIEF.

SUBROUTINE ECRGEO(X,Y,NPOIN,NBOR,NFIC,NVAR,TEXTE,VARCLA,
NVARCL,TITRE,SORLEO,NSOR,IKLE,NELEM, NPTFR,NDP,DATE,TIME,NCSIZE,NPTIR,KNOLG)

X,Y are the coordinates of the mesh (equivalent to MESH%X%R and MESH%Y%R)
NPOIN is the number of nodes in the mesh
NBOR is the array MESH%NBOR%I giving the global numbers of boundary points.
NFIC is the logical unit of the file
NVAR is the number of variables to write in the file (at every time-step)
TEXTE is the 32 characters strings given the names and units of variables (SORLEO, see below, will
say if they must be put in the file).
VARCLA is another array of 32 characters strings used for the so-called clandestine variables in
TELEMAC-2D, i.e. variables which are in the geometry file and are merely transmitted to the results
file.
NVARCL is the number of clandestine variables.
TITRE is the title of the file or the study (80 characters).
SORLEO is an array of logical values saying which variables in the list TEXTE will be put in the file.
NSOR is the size of SORLEO
IKLE, NELEM, NPTFR, NDP are the classical components of BIEF_MESH structures : connectivity
table, number of elements, number of boundary points and number of points per element.
DATE and TIME are two arrays of 3 integers giving the year, month, day and hour, minute, second
NCSIZE is the number of processors.
NPTIR is the number of interface points with other sub-domains (if NCSIZE greater than 1).
KNOLG is the global number of points in the original mesh (if NCSIZE greater than 1).

SUBROUTINE FILPOL(F,C,XSOM,YSOM,NSOM,MESH)

FILPOL fills a vector F with a constant C, but only for points of F which are in a given polynomial in
the computational domain.

F is a BIEF_OBJ structure of a vector.

C is the constant.
XSOM and YSOM are arrays of double precision numbers giving the coordinates of the apices of the
polynomial.
NSOM is the number of apices (e.g. 3 for a triangle).
MESH is the BIEF_MESH structure of the mesh.

SUBROUTINE FIND_IN_SEL (RES,NAME,NFIC,W,OK)

ACCESSIBILITE : FREE Page 62/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

FIND_IN_SEL will find in a SELAFIN format file a variable with a given name.

RES is a BIEF_OBJ structure to put the result in.

NAME is the name of the variable (16 characters).
NFIC is the logical unit of the file
W is a working real (real, not double precision) array of size the number of points in the mesh.
OK is a logical value saying if the variable has been found.

SUBROUTINE FONSTR ( H,ZF,Z,CHESTR,NGEO,

NFON,NOMFON,MESH,FFON,LISTIN)

FONSTR can find the bottom topography and the bottom friction in a geometry file in the SELAFIN
format. In this file the bottom topography must be called FOND or BOTTOM, the friction must be
called FROTTEMENT or BOTTOM FRICTION. If the bottom is not in the file, another possibility is
that the bottom is computed as a function of the free surface and the depth. In this case they must be
called respectively SURFACE LIBRE or FREE SURFACE and HAUTEUR D'EAU or WATER
DEPTH. The bottom can also be given as a cluster of bathymetry points in a specific file. These data
will then be interpolated to give nodal values. The format of bathymetry points is the following: every
line is dedicated to 1 point with X Y Z in free format. Xand Y are the coordinates
and Z is the bottom elevation.
Lines beginning with C or B are ignored. With such a standard, SINUSX files can be read.

If the bottom friction is not in the geometry file, CHESTR is set to the value FFON.

The arguments of FONSTR are:

H,ZF,Z are BIEF_OBJ structures where the depth (if any), the bottom, and the free surface (if
present) will be stored.
CHESTR is the BIEF_OBJ structure for the friction coefficient.
NGEO is the logical unit of the geometry file.
NFON is the logical unit of the bottom file.
NOMFON is the name of the bottom file.
MESH is the BIEF_MESH structure of the mesh.
FFON is the friction coefficient if it is constant.
LISTIN is a logical value. If yes, information will be printed.

The bottom friction can then be changed with the user subroutine STRCHE.

SUBROUTINE LITENR(VARSOR,CLAND,NPRE,STD,HIST,NHIST,NPOIN, AT, TEXTPR,

TEXTLU, NVAR, VARCLA, NVARCL, TROUVE, ALIRE, W, LISTIN, MAXVAR)

ACCESSIBILITE : FREE Page 63/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

LITENR will read a time record in a selafin file. It assumes that the heading with geometry data has
been read, and that a number of time records may also have been read. Some variables of the next
time record are read by LITENR. As in ECRGEO, the name of variables is in TEXTPR, but in this
list, only the variables given by the logical array ALIRE will be read. The result will be put in a block
called VARSOR. If there are clandestine variables (their number is NVARCL), their name is given in
VARCL and they will be put into the block CLAND. Other arguments are:

NPRE : logical unit of the file.

STD : binary standard of the file (3 characters STD, IBM or I3E). Obsolescent, use 'STD'.
HIST : sometimes an array of real values may be put after the time in the same record.
NHIST : size of NHIST. So far 0 because it is not implemented in RUBENS.
NPOIN : number of points in the mesh.
AT : time of the record read by LITENR.
TEXTLU is a working array of character*32 strings to store the names of variables in the file.
NVAR is the number of normal variables
TROUVE is an integer array saying if the variables asked have been found.
W is a working real (real, not double precision) array of size the number of points in the mesh.
LISTIN is a logical saying if information on what is read must be printed.

SUBROUTINE SKIPGEO(NFIC,TITFIC,NPOIN,NVAR,TEXTLU)

SKIPGEO reads a SELAFIN file with logical unit NFIC up the time records. It returns the title of the
file: TITFIC, the number of points in the mesh: NPOIN, the number of variables stored: NVAR, and
their names and units: TEXTLU (an array of CHARACTER*32 strings).

SUBROUTINES DEALING WITH ALL FORMATS

From version 6.0 on several formats are accepted for inputs and outputs and new subroutines have
been created to deal with this new feature. For example the equivalent of the former ECRGEO with
be a sequence of a call to CREATE_DATASET and a call to WRITE_MESH. Writing a record of
results will be done with BIEF_DESIMP (which also prints on the listing) or WRITE_DATA.

SUBROUTINE BIEF_DESIMP( FORMAT_RES, VARSOR, HIST, NHIST, N, NRES, STD,

AT, LT, LISPRD, LEOPRD,SORLEO, SORIMP, MAXVAR, NOMVAR, PTINIG, PTINIL )

FORMAT_RES is the file format (‘SELAFIN ‘, ‘SELAFIND’ or ‘MED ‘)

VARSOR is a block containing BIEF_OBJ structures with the variables to be printed in the file.
HIST and NHIST are used to add data in the time record of the Selafin format (HIST will be the array
of the values and NHIST their number)

ACCESSIBILITE : FREE Page 64/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

N is the number of points to be printed (it may be different from the number of degrees of freedom, as
soùe values are dropped when quasi-bubble or quadratic elements are used).
NRES is the logical unit of the file.
STD is a 3-character string (meant for binary variants, currently not used)
AT is the current time.
LT is the iteration number.
LISPRD and LEOPRD are the printing periods on listing and file.
SORLEO and SORIMP are logical arrays stating if a variable must be exited or not (same order as in
the block VARSOR).
MAXVAR is the number of variables in the block VARSOR, and the dimension of SORLEO and
SORIMP.
NOMVAR is an array of 32-character strings containing the names (16 characters) and units (16
characters) of variables.
PTINIG and PTINIL are the time steps (respectively for file and listing) at which will start the prints.
These integers stem from key-words such as “NUMBER OF FIRST TIME-STEP FOR GRAPHIC
PRINTOUTS” in Telemac-2D and 3D.

SUBROUTINE BIEF_SUITE(VARSOR, CLAND, NUMDE,

NPRE, STD, HIST, NHIST, NPOIN, AT, TEXTPR,VARCLA, NVARCL, TROUVE, ALIRE,
LISTIN, FIN, MAXVAR, NPLAN, DT)

BIEF_SUITE is used to start a new computation from previous results. The time record to start with
is the last one if FIN=.TRUE., and is NUMDEB if FIN=.FALSE. Otherwise the principle and
arguments are the same as LITENR, see above. For Selafin format BIEF_SUITE is a combination of
SKIPGEO and LITENR.

NPLAN and DT are optional parameters.

If NPLAN is present (case of Telemac-3D with prisms) and if the number of planes is different, the
data will be interpolated to cope with the number of planes asked, i.e. NPLAN.

If DT is present, the time step of records in the file will be returned. This assumes that there are at
least 2 records in the file, otherwise an error message will be issued.

SUBROUTINE BIEF_VALIDA(VARREF, TEXTREF, UREF, REFFORMAT, VARRES,

TEXTRES, URES, RESFORMAT, MAXTAB, NP, IT, MAXIT, ACOMPARER)

BIEF_VALIDA offers an automatic way to compare two SELAFIN files to perform validations of
modifications in a program. A reference file (logical unit UREF) is compared to a result file (logical
unit URES).

VARREF and VARRES are blocks where the variables to read will be put.

ACCESSIBILITE : FREE Page 65/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

TEXTREF and TEXTRES are the names of the variables and give their implicit numbering.
UREF and URES are the logical units of reference file and result file.
REFFORMAT and RESFORMAT are the formats of reference file and result file (i.e. ‘SELAFIN ‘,
SELAFIND’ or ‘MED ‘.
MAXTAB is the maximum number of variables.
NP the number of points in the mesh.
IT and MAXIT are respectively the current and the maximum iteration. A comparison is done only
when the last iteration MAXIT is reached and only the last time-step is checked.
ACOMPARER is an integer array saying if a variable must be checked (1) or not (0).

SUBROUTINE CREATE_DATASET
(FORMAT,NRES,TITLE,MAXVAR,NOMVAR,OUTVAR)

FORMAT: a 8-character string. Possible values are ‘SELAFIN ‘, ‘SELAFIND’ and ‘MED ‘.
SELAFIN is the classical format in the Telemac system. SELAFIND is the same but with real
numbers saved in double precision (so far not supported by post processors). MED is an EDF format
that is recognised by all tools of the Salomé platform.

NRES: the logical unit

In Telemac-2D for example and for the results file, these first two arguments will be:
T2D_FILES(T2DRES)%FMT and T2D_FILES(T2DRES)%LU.

TITLE is the title of the case, in 80 characters.

MAXVAR is the maximum number

This subroutine will only store in the file the information of the title and the names and units
of variables.

SUBROUTINE WRITE_DATA(FORMAT_RES, NRES, MAXVAR, AT, LT, SORLEO,

NOMVAR, VARSOR, N)

Mostly as BIEF_DESIMP, but a lower level. It will not deal with periods and printing on listing.

FORMAT_RES is the file format (‘SELAFIN ‘, ‘SELAFIND’ or ‘MED ‘)

NRES is the logical unit of the file.
MAXVAR is the number of variables in the block VARSOR and NOMVAR.
AT is the current time, LT is the iteration number.
SORLEO is a logical array stating if a variable must be exited or not.
NOMVAR is an array of 32-character strings containing the names (16 characters) and units (16
characters) of variables.
VARSOR is a block containing BIEF_OBJ structures with the variables to be printed in the file.

ACCESSIBILITE : FREE Page 66/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

N is the number of points to be printed.

SUBROUTINE WRITE_MESH (FORMAT, NRES, MESH, NPLAN, MARDAT, MARTIM,

I_ORIG, J_ORIG)

FORMAT and NRES are like in subroutine CREATE_DATASET above.

MESH is the BIEF_MESH structure of the mesh.
NPLAN is the number of planes in the mesh (1 in 2D).
MARDAT and MARTIM are two arrays of 3 integers containing the date : year, month, day,
and hours, minutes, seconds.
I_ORIG and J_ORIG are the numbers of metres to add to coordinates to get georeferenced
data.

SCIENTIFIC LIBRARY

Some scientific functions have been included in BIEF for convenience:

DOUBLE PRECISION FUNCTION ATANC (A,B)

ATANC returns the Arc tangent of A.

DOUBLE PRECISION FUNCTION JULTIM (YEAR,MONTH,DAY,HOUR,MIN,SEC,AT)

JULTIM returns the time in Julian centuries since the 31 December 1899. The starting time of a
computation is given by YEAR,MONTH,DAY,HOUR,MIN,SEC, and AT (current time in the
computation is added).

DOUBLE PRECISION FUNCTION TSLOC (YEAR,MONTH,DAY,HOUR,MIN,SEC,AT)

TSLOC returns the local sidereal time.

HIGHER ORDER SUBROUTINES IN BIEF

A number of subroutines in BIEF are more dedicated to physics and can be directly called by
programmes to solve e.g. diffusion or advection equations:

SUBROUTINE CVDFTR

In 2 dimensions, solves the advection-diffusion of a tracer, including source terms. Starting from a
tracer FN at time step n, it gives back the tracer F at time step n+1. Refer to source code for a full list
of arguments. The advection may have been done previously by the method of characteristics, in

ACCESSIBILITE : FREE Page 67/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

which case the result is in FTILD, or is done by CVDFTR itself, which may call other subroutines
such as CVTRVF and CVTRVF_POS. Explicit and implicit source terms may be treated, as well as
punctual sources. An argument ICONVF monitors the choice of the advection scheme.

SUBROUTINE CHARAC

This is the header subroutine for advection with the method of characteristics. It calls scalar or
parallel variants of this method. The parallel version of the method of characteristics is included in
module STREAMLINE. CHARAC may deal with a single.

Refer to source code for a full list of arguments. FN is the variable to be advected and FTILD the
result. They may be blocks of variables and in this case the argument NOMB is the number of
variables that will be treated.

USER SUBROUTINES IN BIEF

A number of subroutines are called by BIEF and may be changed by the user to implement
specific cases. These subroutines have generally no arguments and only global data defined in a
module may thus be changed. Subroutines are provided with examples.

SUBROUTINE CORLAT

CORLAT is called by INBIEF when the coordinates are spherical. It allows changing of latitude and
longitude of points.

SUBROUTINE CORRXY

CORRXY is called once at the beginning of INBIEF (and before CORLAT). It allows to change the
coordinates of points. Users are free to do any change (for example translations or rotations) provided
that it keeps the topology of the mesh.

A translation in TELEMAC-2D would be done by adding USE DECLARATIONS_TELEMAC2D in

CORRXY, declaring integer I, and then:

DO I=1,NPOIN
X(I) = X(I) + 100.D0
Y(I) = Y(I) + 200.D0
ENDDO

As a matter of fact, NPOIN, X and Y are pointers defined in DECLARATIONS_TELEMAC2D, to

MESH%NPOIN, MESH%X%R and MESH%Y%R

SUBROUTINE STRCHE

ACCESSIBILITE : FREE Page 68/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

STRCHE is called once after reading the bottom friction in the geometry file, or after setting it to a
constant value. This subroutine is empty and can be used only with modules containing global
declarations. We give hereafter an example that would work with TELEMAC-2D:

SUBROUTINE STRCHE
USE BIEF
USE DECLARATIONS_TELEMAC2D
INTEGER I
DO I=1,NPOIN
IF(X(I).GT.5.D0) THEN
CHESTR%R(I) = 35.D0
ELSE
CHESTR%R(I) = 30.D0
ENDIF
ENDDO
RETURN
END

DESIGNING A NEW PROGRAMME

Global data

Global data are defined by Fortran 90 modules. A number of other data are gathered in a BIEF
module called DECLARATIONS_TELEMAC. It is given below:
C
C DECLARATIONS COMMON TO ALL PROGRAMMES VERSION 6.0
C
MODULE DECLARATIONS_TELEMAC
C
C----------------------------------------------------------------------
C
C 1./ INTEGER VALUES FOR DESCRIBING BOUNDARY CONDITIONS:
C
C FOR THE BOUNDARY CONDITIONS FILE:
C
C ENTRANCE: PRESCRIBED VALUES (SAVE VELOCITIES)
INTEGER, PARAMETER :: KENT = 5
C
C VELOCITY IMPOSED (INSTEAD OF DISCHARGE)
INTEGER, PARAMETER :: KENTU = 6
C
C FREE OUTPUT
INTEGER, PARAMETER :: KSORT = 4
C
C NO-SLIP CONDITION
INTEGER, PARAMETER :: KADH = 0
C
C WALL WITH OR WITHOUT FRICTION
INTEGER, PARAMETER :: KLOG = 2
C
C OPEN BOUNDARY WITH INCIDENT WAVE

ACCESSIBILITE : FREE Page 69/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

INTEGER, PARAMETER :: KINC = 1

C
C ESTEL-2D : DRAINAGE LIBRE
INTEGER, PARAMETER :: KDRAIN = 3
C
C ESTEL-2D : CONDITION MIXTE
INTEGER, PARAMETER :: KMIX = 4
C
C DEPENDING ON ALGORITHMS AND CASES, THESE VALUES WILL BE TRANSFORMED
C INTO:
C
C TECHNICAL BOUNDARY CONDITIONS
C
C NEUMANN
INTEGER, PARAMETER :: KNEU = 1
C
C DIRICHLET
INTEGER, PARAMETER :: KDIR = 2
C
C DEGREE OF FREEDOM
INTEGER, PARAMETER :: KDDL = 3
C
C INCIDENT WAVE
INTEGER, PARAMETER :: KOND = 4
C
C-----------------------------------------------------------------------
C
C 2./ CODE COUPLING
C
CHARACTER*144 COUPLING
C
C 3./ NAME OF CURRENT CODE (SEE BIEF_OPEN_FILES AND CONFIG_CODE)
C
CHARACTER(LEN=24) :: NAMECODE,NNAMECODE(3)
C
C-----------------------------------------------------------------------
C
END MODULE DECLARATIONS_TELEMAC

To use these values, it is only necessary to write:

USE DECLARATIONS_TELEMAC

as the first statement of every program or subroutine using them.

It is recommended to do a module of global declarations of your programme, containing the

data read in the parameter file, the BIEF_OBJ structures, etc. However this module must not be used
in subroutines that would be called by another programme in the Telemac system, which has no such
declarations.

General structure of a programme based on BIEF 6.0

Main program

ACCESSIBILITE : FREE Page 70/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

We give hereafter in extenso the example of the main program of TELEMAC-2D, which
exemplifies all complex cases : parameter estimation and code coupling.
C ************************
PROGRAM HOMERE_TELEMAC2D
C ************************
C
C***********************************************************************
C TELEMAC 2D VERSION 6.0 27/03/09 J-M HERVOUET (LNHE) 01 30 87 80 18
C
C***********************************************************************
C
C FONCTIONS:
C ==========
C
C 1) READING ALL NECESSARY DATA
C
C 2) CALLING TELEMAC2D AND IN CASE OF COUPLING SISYPHE
C
C IN CASE OF PARAMETER ESTIMATION, HOMERE_ADJ_T2D IS CALLED INSTEAD
C TELEMAC2D
C
C-----------------------------------------------------------------------
C
C APPELE PAR : PRINCI
C
C SOUS-PROGRAMMES APPELES : LECDON , POINT , TELEMAC2D
C
C**********************************************************************
C
USE BIEF
USE DECLARATIONS_TELEMAC
USE DECLARATIONS_TELEMAC2D
USE DECLARATIONS_SISYPHE, ONLY : SIS_FILES
USE INTERFACE_TELEMAC2D
C
IMPLICIT NONE
INTEGER LNG,LU
COMMON/INFO/LNG,LU
C
INTEGER TDEB(8),TFIN(8),NCAR,IFLOT
C
CHARACTER(LEN=24), PARAMETER :: CODE1='TELEMAC2D '
CHARACTER(LEN=24), PARAMETER :: CODE2='SISYPHE '
C
CHARACTER(LEN=250) PATH
CHARACTER(LEN=144) MOTCAR(300),FILE_DESC(4,300)
C
C======================================================================
C
C INITIALISING FILES (NAMES OF FILES=' ' AND LOGICAL UNITS =0)
C GETTING NCSIZE BY CALLING P_INIT
C
CALL BIEF_INIT(CODE1,PATH,NCAR,.TRUE.)
C
C INITIAL TIME FOR COMPUTATION DURATION
C
CALL DATE_AND_TIME(VALUES=TDEB)
C
C PRINTING BANNER ON LISTING
C
IF(LNG.EQ.1) WRITE (LU,100)
IF(LNG.EQ.2) WRITE (LU,101)
WRITE (LU,102)
100 FORMAT(/////,1X,'LISTING DE TELEMAC-2D ',78('-'))
101 FORMAT(/////,1X,'LISTING OF TELEMAC-2D ',78('-'))
102 FORMAT(/////,
*14X,' TTTTT EEEEE L EEEEE M M AAAAA CCCCC',/,

ACCESSIBILITE : FREE Page 71/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

*14X,' T E L E MM MM A A C ',/,
*14X,' T EEE L EEE M M M AAAAA C ',/,
*14X,' T E L E M M A A C ',/,
*14X,' T EEEEE LLLLL EEEEE M M A A CCCCC',/,
*14X,' ',/,
*14X,' 2D VERSION 6.0 FORTRAN 90 ',/,
*14X,' WITH SEVERAL TRACERS ',/,
*14X,' COUPLED WITH SISYPHE INTERNALLY ',/,
*14X,/////)
C
C-----------------------------------------------------------------------
C
C READING THE STEERING FILE
C
CALL LECDON_TELEMAC2D(MOTCAR,FILE_DESC,PATH,NCAR)
C
C-----------------------------------------------------------------------
C
C OPENING FILES FOR TELEMAC2D
C
IFLOT = 0
CALL BIEF_OPEN_FILES(CODE1,T2D_FILES,44,PATH,NCAR,
* INCLUS(COUPLING,'INTER'),IFLOT,1)
C
C-----------------------------------------------------------------------
C
C MEMORY ALLOCATION
C
CALL POINT_TELEMAC2D
C
C SAVING COMMON NDS CORRESPONDING TO TELEMAC-2D MESH
C
CALL SAVE_NDS(1)
C
C-----------------------------------------------------------------------
C
C INITIALISING SISYPHE
C
IF(INCLUS(COUPLING,'SISYPHE')) THEN
C
C FALSE= P_INIT NOT CALLED
CALL BIEF_INIT(CODE2,PATH,NCAR,.FALSE.)
C
IF(LNG.EQ.1) WRITE (LU,103)
IF(LNG.EQ.2) WRITE (LU,104)
WRITE (LU,105)
103 FORMAT(/////,1X,'LISTING DE SISYPHE AVEC COUPLAGE',78('-'))
104 FORMAT(/////,1X,'LISTING OF SISYPHE WITH COUPLING',78('-'))
105 FORMAT(/////,
* 14X,' SSSS I SSSS Y Y PPPP H H EEEEE' ,/,
* 14X,' S I S Y Y P P H H E ' ,/,
* 14X,' SSS I SSS Y PPPP HHHHH EEEE ',/,
* 14X,' S I S Y P H H E ',/,
* 14X,' SSSS I SSSS Y P H H EEEEE' ,/,
* 14X,' ',/,
* 14X,' VERSION 6.0 ',/,
* 14X,' COUPLED WITH TELEMAC-2D INTERNALLY ',/,
* 14X,/////)
C
CALL LECDON_SISYPHE(MOTCAR,FILE_DESC,PATH,NCAR,CODE1)
C
CALL BIEF_OPEN_FILES(CODE2,SIS_FILES,44,PATH,NCAR,
* INCLUS(COUPLING,'SISYPHE'),IFLOT,2)
CALL POINT_SISYPHE
C
C SAVING COMMON NDS CORRESPONDING TO SISYPHE MESH (SO FAR THE SAME !)
C
CALL SAVE_NDS(2)
C

ACCESSIBILITE : FREE Page 72/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

ELSEIF(COUPLING(1:1).EQ.' ') THEN

C
C NOTHING TO DO
C
ELSEIF(INCLUS(COUPLING,'DELWAQ')) THEN
C
C NOTHING TO DO
C
ELSE
C ERREUR
IF(LNG.EQ.1) WRITE (LU,*) 'CAS DE COUPLAGE INCONNU : ',COUPLING
IF(LNG.EQ.2) WRITE (LU,*) 'UNEXPECTED COUPLING CASE: ',COUPLING
CALL PLANTE(1)
STOP
ENDIF
C
C RESETTING TELEMAC2D CONFIGURATION
C
CALL CONFIG_CODE(1)
C
C=======================================================================
C
IF(ESTIME.EQ.' ') THEN
C
C-----------------------------------------------------------------------
C
C NORMAL MODE: ONE CALL OF TELEMAC2D
C
CALL TELEMAC2D(PASS=-1,ATDEP=0.D0,NITER=0,CODE=' ')
C
C-----------------------------------------------------------------------
C
ELSE
C
C-----------------------------------------------------------------------
C
C PARAMETER ESTIMATION MODE : CALLING HOMERE_ADJ_T2D
C
CALL HOMERE_ADJ_T2D
C
ENDIF
C
C=======================================================================
C
C CLOSING FILES
C
CALL BIEF_CLOSE_FILES(CODE1,T2D_FILES,44,.TRUE.)
C
IF(INCLUS(COUPLING,'SISYPHE')) THEN
CALL CONFIG_CODE(2)
CALL BIEF_CLOSE_FILES(CODE2,SIS_FILES,44,.FALSE.)
ENDIF
C
C-----------------------------------------------------------------------
C
IF(LNG.EQ.1) WRITE (LU,10)
IF(LNG.EQ.2) WRITE (LU,11)
10 FORMAT(1X,///,1X,'FIN NORMALE DU PROGRAMME',///)
11 FORMAT(1X,///,1X,'CORRECT END OF RUN',///)
C
C-----------------------------------------------------------------------
C
C TIME OF END OF COMPUTATION
C
CALL DATE_AND_TIME(VALUES=TFIN)
CALL ELAPSE(TDEB,TFIN)
C
C-----------------------------------------------------------------------
C

ACCESSIBILITE : FREE Page 73/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

STOP
END

Some explanations:

* The statement USE BIEF is given first because the module

DECLARATIONS_TELEMAC2D contains declarations of BIEF_OBJ structures, for
example the depth H or the mesh called MESH.

* The string CODE contains the name of the programme and will be used by BIEF
subroutines such as BIEF_OPEN_FILES to open the relevant files. It implies that the
LECDON_TELEMAC2D subroutine uses also the module DECLARATIONS_TELEMAC
and correctly fills the names of the files.

Other calls are explained in the following paragraphs.

Reading the parameter file

This is done by the call to LECDON_TELEMAC2D. Such a subroutine must be written for
every program in the system. LECDON_TELEMAC2D calls the subroutine DAMOCLES
which returns the parameters read in the dictionary file and in the user parameter file. We give
hereafter parts of LECDON_TELEMAC2D as an example:
USE DECLARATIONS_TELEMAC
USE DECLARATIONS_TELEMAC2D
C
IMPLICIT NONE
INTEGER LNG,LU
COMMON/INFO/LNG,LU
C
INTEGER I,K,NCSIZE,ERR,NCAR
INTEGER NREJEX,NREJEY,NCOSUP,NREJEV,NCRITE
C
CHARACTER*8 MNEMO(MAXVAR)
CHARACTER(LEN=250) PATH,NOM_CAS,NOM_DIC
CHARACTER(LEN=144) FILE_DESC(4,300)
C
C-----------------------------------------------------------------------
C
C DECLARATION OF ARRAYS FOR CALLING DAMOCLES
C
INTEGER, PARAMETER :: NMAX = 300
C
INTEGER ADRESS(4,NMAX),DIMENS(4,NMAX)
DOUBLE PRECISION MOTREA(NMAX)
INTEGER MOTINT(NMAX)
LOGICAL MOTLOG(NMAX)
CHARACTER(LEN=144) MOTCAR(NMAX)
CHARACTER*72 MOTCLE(4,NMAX,2)
INTEGER TROUVE(4,NMAX)
LOGICAL DOC
C
C
………………………
C
C INITIALISATIONS FOR CALLING DAMOCLES :
C

ACCESSIBILITE : FREE Page 74/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

DO 10 K=1,NMAX
MOTCAR(K)(1:1)=' '
DIMENS(1,K) = 0
DIMENS(2,K) = 0
DIMENS(3,K) = 0
DIMENS(4,K) = 0
10 CONTINUE
C IF YES WILL PRINT ALL DOCUMENTATION IN DICTIONARY
DOC = .FALSE.
C
C-----------------------------------------------------------------------
C OPENING PARAMETER FILE AND DICTIONARY
C-----------------------------------------------------------------------
C
IF(NCAR.GT.0) THEN
C
NOM_DIC=PATH(1:NCAR)//'T2DDICO'
NOM_CAS=PATH(1:NCAR)//'T2DCAS'
C
ELSE
C
NOM_DIC='T2DDICO'
NOM_CAS='T2DCAS'
C
ENDIF
C
OPEN(2,FILE=NOM_DIC,FORM='FORMATTED',ACTION='READ')
OPEN(3,FILE=NOM_CAS,FORM='FORMATTED',ACTION='READ')
C
C-----------------------------------------------------------------------
C
CALL DAMOCLE( ADRESS , DIMENS , NMAX , DOC , LNG , LU ,
* MOTINT , MOTREA , MOTLOG , MOTCAR , MOTCLE ,
* TROUVE , 2 , 3 , .FALSE. , FILE_DESC )
C
C-----------------------------------------------------------------------
C FERMETURE DES FICHIERS DICTIONNAIRE ET CAS
C-----------------------------------------------------------------------
C
CLOSE(2)
CLOSE(3)

Remark: the names of the steering file and the dictionary, their logical units are here hard-
coded. As they are closed after, logical units 2 and 3 may be re-used.

After calling DAMOCLES, the parameters are in the arrays MOTINT, MOTREA, MOTLOG
and MOTCAR if they are (respectively) integers, double precision numbers, logical values or
character strings. Their rank in the arrays is given by their index in the dictionary.

ADRESS(1,*) is the addresses of integers in array MOTINT.

ADRESS(2,*) is the addresses of double precision numbers in array MOTREA.
ADRESS(3,*) is the addresses of logical values in array MOTLOG.
ADRESS(4,*) is the addresses of strings in array MOTCAR.

For example the turbulence model is in Telemac-2D an integer with rank 7 in the dictionary.
It is initialised as follows:
ITURB = MOTINT( ADRESS(1, 7) )

ACCESSIBILITE : FREE Page 75/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The size of arrays is given by DIMENS, for example the array of prescribed free surfaces
(index 31 of double precision numbers in the dictionary) in TELEMAC-2D is initialised by:
NCOTE = DIMENS(2,31)
IF(NCOTE.NE.0) THEN
DO K=1,NCOTE
COTE(K) = MOTREA( ADRESS(2,31) + K-1 )
ENDDO
ENDIF

As MOTCAR is declared as an array of CHARACTER*144 strings, it may be necessary to

take only a part of them, as below:
TITCAS = MOTCAR( ADRESS(4, 1) )(1:72)

Where TITCAS is declared as a CHARACTER*72 string.

Checking and modifications of key-words should be done only in LECDON.

Allocating memory

This is done in the subroutine called POINT_NAMEOFPROGRAMME. We give and

comment hereafter parts of POINT_TELEMAC2D:
USE BIEF
USE DECLARATIONS_TELEMAC
USE DECLARATIONS_TELEMAC2D !where all BIEF_OBJ structures are declared
C
C+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
C
.
. (Declarations and printing skipped), then:
.
C
C DISCRETISATIONS TYPES
C
C P0 and P1 discretisation
C
IELM0 = 10*(IELMH/10)
IELM1 = IELM0 + 1
C
C P1 Discretisation of boundaries
C
IELB1 = IELBOR(IELM1,1)
C Element with the greatest number of degrees of freedom
IELMX=MAX(IELMU,IELMH,IELMT,IELMK,IELME)
C
C TYPE OF STORAGE AND MATRIX-VECTOR PRODUCT
C
CFG(1) = OPTASS
CFG(2) = PRODUC
C
C=======================================================================
C
C ALLOCATING THE MESH
C
CALL ALMESH(MESH,'MESH ',IELMX,SPHERI,CFG,T2D_FILES(T2DGEO)%LU,
* EQUA,I3=I3,I4=I4)
C IF ORIGIN COORDINATES IN GEOMETRY FILE AND NOT IN PARAMETER FILE,

ACCESSIBILITE : FREE Page 76/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

C VALUES OF GEOMETRY FILE ARE TAKEN

IF(I3.NE.0.AND.I_ORIG.EQ.0) I_ORIG=I3
IF(I4.NE.0.AND.J_ORIG.EQ.0) J_ORIG=I4
C
C EXAMPLE OF CREATION OF ALIASES
C
IKLE => MESH%IKLE
X => MESH%X%R
Y => MESH%Y%R
NELEM => MESH%NELEM
C
C=======================================================================
C
C EXAMPLE OF ALLOCATION OF A REAL ARRAY
C
CALL ALLVEC(1,U,'U ',IELMU,1,1)
C
C EXAMPLE OF ALLOCATION OF A BLOCK
C
CALL ALLBLO(UNK,'UNK ')
C ADDING BIEF_OBJ STRUCTURES IN THE BLOCK UNK
CALL ADDBLO(UNK,DH)
CALL ADDBLO(UNK, U)
CALL ADDBLO(UNK, V)

C EXAMPLE OF ALLOCATION OF A MATRIX

C
CALL ALLMAT(AM2,'AM2 ',IELM1,IELM1,CFG,'Q',TYP)
C
C ALLOCATING A BLOCK TB WITH 3 VECTORS CALLED T1, T2 AND T3
C
CALL ALLBLO(TB ,'TB ')
CALL ALLVEC_IN_BLOCK(TB,42,1,'T ',IELMX,1,2)
C
C ALIASES FOR THESE ARRAYS
C T1, T2 AND T3 ARE DECLARED IN DECLARATIONS_TELEMAC2D AS FOLLOWS
C TYPE(BIEF_OBJ), POINTER :: T1,T2,T3
C ALIASES FOR T1, T2 AND T3
T1 =>TB%ADR( 1)%P
T2 =>TB%ADR( 2)%P
T3 =>TB%ADR( 3)%P

The real main programme

The main program HOMERE_... given above calls TELEMAC2D. This is where the
real specific job of your programme must be done. At the beginning of it, but after reading the
boundary conditions file, the BIEF_MESH structure called MESH must be fully initialised,
and this is done by a call to INBIEF:
CALL INBIEF(LIHBOR%I,KLOG,IT1,IT2,IT3,LVMAC,IELMX,
* LAMBD0,SPHERI,MESH,T1,T2,OPTASS,PRODUC,EQUA)

Inputs and outputs: opening and closing files

The various data and results files of every Telemac programme are described in its dictionary.
The information relevant to files will be read with the subroutine READ_SUBMIT, which is
called in subroutine LECDON_TELEMAC2D (for example), and stored in an array of file
structures (called, depending of the Telemac module: T2D_FILES, T3D_FILES, SIS_FILES,

ACCESSIBILITE : FREE Page 77/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

WAC_FILES, ART_FILES, E2D_FILES or E3D_FILES). Hereafter is given an excerpt of

Telemac-2D dictionary regarding the results file:

NOM = 'FICHIER DES RESULTATS'

NOM1 = 'RESULTS FILE'
TYPE = CARACTERE
INDEX = 11
MNEMO = ‘T2D_FILES%ADR(T2DRES)'
SUBMIT = 'T2DRES-READWRITE-08;T2DRES;OBLIG;BIN;ECR;SELAFIN'
DEFAUT = ' '
DEFAUT1 = ' '

The character string called SUBMIT is used both by the perl scripts and, through Damocles,
by the Fortran programme. It is composed of 6 character strings.
The first string, here T2DRES-READWRITE-08, is made of:
1) the Fortran integer for storing the file number: T2DRES (which is declared
in declarations_telemac2d.f)
2) the argument ACTION in the Fortran Open statement that will be used to
open the file. ACTION may be READ, WRITE, or READWRITE. Here it is
READWRITE because the results file is written, and in case of validation it
is read at the end of the computation. It will be stored into
T2D_FILES%ADR(T2DRES)%ACTION
3) the logical unit to open the file. This a priori value may be changed in case
of code coupling. It is stored into T2D_FILES%ADR(T2DRES)%LU

The second string, here T2DRES, is the name of the file as it will appear in the temporary file where
the computation is done.

The third string may be OBLIG (the name of the file must always be given), or FACUL (this file is not
mandatory).

The fourth string (here BIN) says if it is a binary (BIN) or ASCII (ASC) file.

The fifth string is just like the READWRITE statement and is used by the perl scripts.

The sixth string is also used by the perl scripts and gives information on how the file must be treated.
‘SELAFIN’ means that the file is a Selafin format, it will have to be decomposed if parallelism is used.
Other possibilities are:
SELAFIN-GEOM: this is the geometry file
FORTRAN: this is the Fortran file for user subroutines
CAS: this is the parameter file
CONLIM: this is the boundary conditions file
PARAL: this file will have an extension added to its name, for distinguishing between processors
DICO: this is the dictionary
SCAL: this file will be the same for all processors

The following sequence of subroutines is used for opening, using and closing files:

ACCESSIBILITE : FREE Page 78/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Note : subroutine INIT_FILES2 in BIEF version 5.9 has been renamed BIEF_INIT in version
6.0 and has from now on nothing to see with files.
1) opening files:

IFLOT=0
CALL BIEF_OPEN_FILES(CODE,T2D_FILES,44,PATH,NCAR,COUPLAGE,IFLOT,ICODE)

CODE: name of calling program in 24 characters

T2D_FILES: the array of BIEF_FILE structures
44: the size of the previous array
PATH: full name of the path leading to the directory the case is
NCAR: number of characters of the string PATH
COUPLAGE: logical stating if there is a coupling between several programs.
IFLOT: in case of coupling, will be the last logical unit taken by a file
ICODE: code number in a coupling. For example in a coupling between Telemac-2D and Sisyphe,
Telemac-2D will be code 1 and Sisyphe will be code 2.

2) using files:

Most operations on files consist on reading and writing, which always uses the logical unit. Every file
has a name in the temporary folder where the program is executed, e.g. T2DRES. The associated file
number is an integer with the same name. The logical unit of this file will be equal to T2DRES if there
is no coupling, but more generally it is stored into T2D_FILES(T2DRES)%LU. The logical unit of the
geometry file in Sisyphe will be SIS_FILES(SISGEO)%LU.
Sometimes the real name of files in the original is also used, for example to know if it exists (= has
been given in the parameter file). This name is retrieved in the component NAME. For example the
name of the geometry file in Sisyphe will be SIS_FILES(SISGEO)%NAME. Note that the name of the
same file in the temporary folder is SIS_FILES(SISGEO)%TELNAME. We have in fact:
SIS_FILES(SISGEO)%TELNAME=’SISGEO’.

3) closing files:

CALL BIEF_CLOSE_FILES(CODE,T2D_FILES,44,PEXIT)

CODE: name of calling program in 24 characters

T2D_FILES: the array of BIEF_FILE structures
44: the size of the previous array
PEXIT: logical, if yes will stop parallelism (in a coupling the last program calling BIEF_CLOSE_FILES
will also stop parallelism).

INTERNAL STRUCTURE OF BIEF

BIEF DATA STRUCTURE

This chapter will present a description of the finite elements used, the mesh and the
storage modes for the finite element matrices.

ACCESSIBILITE : FREE Page 79/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

DESCRIPTION OF FINITE ELEMENTS

TRIANGLE P1

This is a triangle with linear interpolation. The reference triangle is composed of the
coordinate points (0,0) (0,1) and (1,0). On this reference element, the basis functions
have the following values :

P1(ξ,η) =1 - ξ - η
P2(ξ,η) = ξ
P3(ξ,η) = η

QUASI-BUBBLE TRIANGLE

The Quasi-Bubble element is obtained by adding an additional point to the three

vertices of a triangle. The centre of gravity of the triangle constitutes a natural choice for
this fourth point. The initial element P1 is thus divided into three sub-triangles:

P1

T1 T3
P4

T2

P2 P3

figure 1: transformation of triangular element T into a quasi-bubble triangle.

By adopting a linear discretisation, the basis functions of the triangle QB (in the sense
of finite element) are the 4 Ψ linear functions defined on the triangle T and confirming:

ψi (P j ) = δij

ACCESSIBILITE : FREE Page 80/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

QUADRATIC TRIANGLE

A quadratic interpolation of the velocity field is a well-known solution to stability problems

raised by the Ladyzhenskaya-Babuška-Brezzi condition in Navier--Stokes equations (also
called discrete inf-sup condition). The pressure (or the depth in Shallow Water equations)
remains linear. For quadratic interpolation, we add 3 degrees of freedom, numbered 4, 5 and 6
on Figure quadratic.
3

6 5

4
2
figure 1 bis: quadratic triangle.

The coordinates of the 6 degrees of freedom are:

Point 1: (0,0)
Point 2: (1,0)
Point 3: (0,1)
Point 4: (1/2,0)
Point 5: (1/2,1/2)
Point 6: (0,1/2)

The quadratic interpolation polynoms Pi ( x, y ) , with i = 1...6 , are such that

Pi ( x, y ) = ϕ i (T ( x, y )) where T is the isoparametric transformation that gives the real
−1

triangle as a function of the reference triangle and Qi are the basis functions in the reference
triangle. In practice T "1 is never built and the computation of integrals is done in the
reference triangle.
The 6 quadratic basis ϕ i (α , β ) are chosen to ensure the following property:
6
∑ ϕ i (α , β ) = 1, ∀(α , β ) ∈ triangle
i =1
Moreover every basis must be equal to 1 on its own point and zero on the five others. This is
verified if we take:
For i = 1, 2, 3, ϕ i (α , β ) = (2 × λi (α , β ) − 1) × λi (α , β )
and for i = 4, 5, 6, ϕ i (α , β ) = 4 × λk (α , β ) × λl (α , β )
where k and l are the indices of points of the segment where is point i. More precisely:

ACCESSIBILITE : FREE Page 81/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

ϕ1 (α , β ) = (2 × λ1 (α , β ) − 1) × λ1 (α , β )
ϕ 2 (α , β ) = (2 × λ2 (α , β ) − 1) × λ2 (α , β )
ϕ 3 (α , β ) = (2 × λ3 (α , β ) − 1) × λ3 (α , β )
ϕ 4 (α , β ) = 4 × λ1 (α , β ) × λ2 (α , β )
ϕ 5 (α , β ) = 4 × λ2 (α , β ) × λ3 (α , β )
ϕ 6 (α , β ) = 4 × λ3 (α , β ) × λ1 (α , β )
Remark: on boundaries a point number 3 is added in the middle and the interpolation
polynoms are:
ϕ1 (ξ ) = 2 × (1 − ξ ) × ( 12 − ξ )
ϕ 2 (ξ ) = (2 × ξ − 1) × ξ
ϕ 3 (ξ ) = 4 × ξ × (1 − ξ )

QUADRILATERAL Q1

The reference square is comprised of the coordinate points (-1,-1) (1,-1) (1,1) and (-1,1). On this
reference element, the base functions have the following values:

P1(ξ,η) = ( 1 - ξ - η + ξη )/4
P2(ξ,η) = ( 1 + ξ - η - ξη )/4
P3(ξ,η) = ( 1 + ξ + η + ξη )/4
P4(ξ,η) = ( 1 - ξ + η - ξη )/4

TETRAHEDRON

So far real there is no module in the Telemac system which fully uses this element. In telemac-3D
and Estel-3Dmeshes of tetrahedrons are not accepted in

The reference tetrahedron is comprised of the coordinate points:

(0,0,0) (1,0,0) (0,1,0) (0,0,1). On this reference element, the base functions have the following
values:

Ψ1 = (1 − α − β − γ )

Ψ2 = α

Ψ3 = β

ACCESSIBILITE : FREE Page 82/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Ψ4 = γ

PRISM

This is a prism with 3 vertical rectangular faces, and two triangular faces, one at the bottom and
one at the top, and which are not necessarily horizontal.

3 (The figures indicate local numbering of the nodes).

2
Figure 2: numbering of nodes in a prism

The reference element is as follows:

γ

1 4
6

5
0 1 β

−1 1
α 3

2
(the figures in circles indicate local numbering of the nodes).

ACCESSIBILITE : FREE Page 83/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Figure 3: reference element for a prism

The basis functions Ψj corresponding to the nodes j of the reference element are:

⎛1− γ ⎞
Ψ1 = (1 − α − β)⎜ ⎟
⎝ 2 ⎠

⎛1− γ ⎞
Ψ2 = α⎜ ⎟
⎝ 2 ⎠

⎛1− γ ⎞
Ψ3 = β⎜ ⎟
⎝ 2 ⎠

⎛1+ γ ⎞
Ψ4 = (1 − α − β)⎜ ⎟
⎝ 2 ⎠

⎛1+ γ ⎞
Ψ5 = α⎜ ⎟
⎝ 2 ⎠

⎛1+ γ ⎞
Ψ6 = β⎜ ⎟
⎝ 2 ⎠

The basis functions ϕi on any prism in the Ω mesh are obtained by creating the Ψi functions with
the isoparametric transformation F, transforming the reference prism into this prism of any type.

For a prism in the Ω mesh with vertex coordinates (xi,yi,zi), F makes any point M0 with
coordinates (α,β,γ) of the reference element correspond to any point M with coordinates (x,y,z) of
this prism by:
⎧ 6

⎪ x = ∑ xi Ψi (α, β, γ )
⎪ i =1
⎪ 6

⎨ y = ∑ y i Ψi (α, β, γ )
⎪ i =
6
1
⎪z =
⎪
⎩
∑
i =1
z i Ψi (α, β, γ )

ACCESSIBILITE : FREE Page 84/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The Ψi functions which appear in the definition of F are the same as the basis functions defined on
the reference element since the reference element chosen is isoparametric (the interpolation nodes
are also the geometric nodes). In our case, the expressions of F can be simplified since:
x1 = x4 ; y1 = y4
x2 = x5 ; y2 = y5
x3 = x6 ; y3 = y6

The following is therefore obtained for F :

⎧
⎪ x = (1 − α − β) x1 + αx 2 + β x3
⎪
⎨ y = (1 − α − β) y1 + αy 2 + β y 3
⎪ ⎡1 − γ ⎤ ⎡1 + γ ⎤
⎪ z = [(1 − α − β) z1 + αz 2 + β z 3 ]⎢ + [(1 − α − β) z 4 + α z + β z ]
⎣ 2 ⎥⎦ ⎢⎣ 2 ⎥⎦
5 6
⎩

The following is deduced for the ϕi functions: ϕi (x, y, z) = Ψi (F-1 (x, y, z))

DESCRIPTION OF MESH

NB: The variables written in capitals are those used in the BIEF FORTRAN program. When a
variable is also a component of the BIEF_MESH structure, it is mentioned into commas. For
example on the line hereafter (MESH%NELEM) means that NELEM can be retrieved from a
BIEF_MESH structure by the component NELEM..

A mesh is composed of NELEM elements (MESH%NELEM) and NPOIN nodes

(MESH%NPOIN) known by their coordinates X, Y, Z (respectively MESH%X, Y and Z).
Each type of element (triangle P1,prism P0,...) is linked to a code and includes NDP nodes.
(MESH%NDP) On an element, the nodes are numbered from 1 to NDP. The connection
between this element numbering (local numbering) and the numbering of the mesh nodes
from 1 to NPOIN (general numbering) is made through the connectivity table IKLE
(MESH%IKLE). The global number of the node with the local number ILOC in the element
IELEM is IKLE(IELEM,ILOC).

IELM NDP(IELM)
00 (segment P0 = constant value) 1
01 (segment P1 = linear) 2
10 (triangle P0 = constant value) 1
11 (triangle P1 = linear) 3

ACCESSIBILITE : FREE Page 85/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

12 (quasi-bubble triangle) 4
13 (quadratic element) 6
20 (quadrilateral Q0 = constant value) 1
21 (quadrilateral Q1 = linear) 4
30 (tetrahedron T0 = constant value 1
31 (tetrahedron T1 = linear 4
40 (prism P0 = constant value) 1
41 (prism P1 = linear) 6
50 (tetrahedron T0 from split prism) 1
51 (tetrahedron T1 from split prism) 4
60 (triangle P0 in a lateral boundary 1
of a mesh of prisms split into
tetrahedrons)
61 (triangle P1 in a lateral boundary 3
of a mesh of prisms split into
tetrahedrons)
70 (quadrilateral Q0 in a lateral 1
boundary of a mesh of prisms)
71 (quadrilateral Q1 in a lateral 4
boundary of a mesh of prisms)
80 (triangle P0 in a boundary 1
of a mesh of tetrahedrons)
81 (triangle P1 in a boundary 3
of a mesh of tetrahedrons)

Table 1: Elements in BIEF version 6.0 (the TELEMAC-3D prism is a prism with four
vertical quadrangular sides). Quadrilateral elements are kept for an internal use by
TELEMAC-3D but no longer maintained.

In addition, the boundary points of the mesh must be known. These are numbered from 1
to NPTFR (MESH%NPTFR). The connection with the general numbering is made through
the table NBOR (MESH%NBOR). NBOR(IPTFR) is the general number of the boundary
point IPTFR.

The tables X, Y, Z, IKLE and NBOR are sufficient for defining the mesh. However, it is
useful to have other tables available, which can often facilitate the writing of the
algorithms. Thus, is it very useful to have tables other than NBOR to describe the
boundaries. In fact, three types of numbering can be associated with the boundary of the
studied domain. These are the boundary point numbers, the boundary face numbers and the
local numbers of the boundary nodes in each of the boundary faces. To connect them,
BIEF uses IKLBOR (BIEF%IKLBOR), a connectivity table for the boundary faces,
NELBOR (MESH%NELBOR) linking the boundary face numbers to the element numbers
to which they belong, and NULONE (MESH%NULONE), a table linking the local

ACCESSIBILITE : FREE Page 86/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

numbers of the boundary nodes in the boundary faces to the local numbers of these nodes
in the elements to which they belong. The following example illustrates the use of these
tables for a triangular element:

Take a triangle P1 numbered IELEM constructed on the 3 nodes with global numbers
NG1, NG2, NG3. The face defined by the two points NG2 and NG3 is a boundary face
with the number IFAFR. The nodes NG2 and NG3 are boundary nodes with the boundary
numbers IPTFR1 and IPTFR2. The nodes NG1, NG2 and NG3 have the local numbers 1, 2
and 3 in the triangle. Finally, the nodes IPTFR1 and IPTFR2 have the local numbers 1 and
2 in the boundary face.

triangle numbered IELEM

NG3
IPTFR2
NG1

side face numbered IFAFR

NG2
IPTFR1

Figure 4: numbering of points and faces on boundaries

We have:
IKLE(IELEM,1) = NG1
IKLE(IELEM,2) = NG2
IKLE(IELEM,3) = NG3

NBOR(IPTFR1) = NG2
NBOR(IPTFR2) = NG3

NELBOR(IFAFR) = IELEM

IKLBOR(IFAFR,1) = IPTFR1
IKLBOR(IFAFR,2) = IPTFR2

ACCESSIBILITE : FREE Page 87/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

NULONE(IFAFR,1) = 2
NULONE(IFAFR,2) = 3

For certain elements (prisms), the boundary faces are of two types. Thus, the boundary
faces of the prism are triangles or quadrilaterals. A dimension is then added to the tables
NELBOR, IKLBOR and NULONE in order to distinguish the type of face in question.
To know the types of boundary faces (segment P1, triangle P1...) for example to calculate
boundary matrices, a function IELBOR is used. IELBOR(IELM,1) gives the code of the
first type of face of the type IELM element (bottom and top of prisms),
IELBOR(IELM,2).gives the type of vertical sides of boundary prisms, which may be
triangles or quadrilaterals depending on the fact that the prisms are split into tetrahedrons
or not.

The adaptive mesh is simply specified by dimensioning with the maximum possible
number of NELMAX elements or the maximum possible number of NELBRX boundary
elements all the tables with several dimensions such as IKLE, NULONE...etc.

STORAGE OF MATRICES

The theoretical aspects of "Element By Element" and “Edge based” storage are discussed
below. The resulting conventions are given in appendix 1.

EBE STORAGE

In a finite element code using iterative resolution methods, a matrix is essentially used
to multiply it by a vector. Other operations with a matrix are less frequent, and, as will be
seen in Chapter IV, these operations can be constructed on the architecture of a matrix-
vector product. The storage mode of a matrix has thus been motivated in order to make its
vector product as effective as possible.

It is well known that it is not necessary to assemble a finite element matrix to multiply
it by a vector. On a mesh of NELEM elements, a matrix M is written as a function of the
elementary matrices Me on each of the elements according to the following:
NELEM
M = ∏P M
e =1
e e Pet

where Pe is a transfer matrix between the element and the general mesh. Pe is constructed
using the connectivity table. For example, for a triangle P1 with element number IELEM
and vertices with general numbers NG1, NG2 and NG3, MIELEM is a matrix 3*3 and
PIELEM is a matrix NPOIN*3 such that the coefficient of PIELEM situated at the
intersection of row I and column J is 1 if I = IKLE(IELEM,J) and otherwise it is 0.

ACCESSIBILITE : FREE Page 88/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

0 0 0
1 0 0 line IKLE(IELEM,1)
. . .
0 1 0 line IKLE(IELEM,2)
PIELEM = . . .
. . .
. . .
0 0 1 line IKLE(IELEM,3)
0 0 0
NELEM
If X is a vector, the product M.X becomes: MX = ∏ (P M
e =1
e e Pet ) X

which is the same as multiplying Me by the components of X associated with the nodes of
the element e (elementary products), then calculating the sum for all the mesh elements
(assembly). It is of course never necessary to construct the matrix Pe which is no other
than the connectivity table IKLE.

A matrix M can be stored in the form of NELEM matrices Me. For a mesh of triangles P1,
this gives 9*NELEM coefficients. This number can be reduced by retaining only the off-
diagonal terms for each elementary matrix and assembling the diagonal terms as shown
below.

Let De and Ee the diagonal and off-diagonal parts of Me (Me = De + Ee), then:
NELEM NELEM NELEM
MX = ∏
e =1
( Pe De Pet ) X + ∏ ( Pe Ee Pet ) X = DX +
e =1
∏ (P E P ) X
e =1
e e e
t

where D is the diagonal of M, obtained by assembling the diagonals De.

In BIEF, a matrix MAT is therefore stored in two arrays, one being DMAT, containing the
diagonal of the assembled matrix, and the other XMAT, containing the off-diagonal terms
of the elementary matrices. For a matrix constructed on a mesh of triangles P1, all that has
to be stored is 6*NELEM + NPOIN coefficients, which represents a saving in space of
about 2.5*NELEM coefficients compared with complete storage of the element matrices.

In addition, by using elementary matrices, it is possible to obtain a vectorisable matrix

vector product on a vector computer. The loop on the elementary products is vectorisable
and the assembly loop for these elementary products may also be vectorisable provided a
few precautions are taken concerning the numbering of the mesh. We shall look in greater
detail at the matrix-vector product and assembly in Chapter IV, which deals with matrix
operations.

ACCESSIBILITE : FREE Page 89/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

For storage of off-diagonal elements, the convention adopted in BIEF is as follows. Let us
take the case of an element IELEM constructed on NLOC nodes. An elementary matrix
Me includes in this case NLOC*(NLOC-1) off-diagonal terms Ei,j, situated in row i and
column j of Me.

Let:

XMAT(IELEM,1) = E1,2
XMAT(IELEM,2) = E1,3
.........................................

XMAT(IELEM,NLOC-1) = E1,NLOC
.........................................

XMAT(IELEM,NLOC*(NLOC-1)/2) = ENLOC-1,NLOC

for the terms in the upper triangular part of Me. If Me is symmetrical, the array XMAT is
complete. Otherwise, the lower triangular part of Me must also be stored, which is
achieved in the following way:

XMAT(IELEM,NLOC*(NLOC-1)/2 + 1) = E2,1
XMAT(IELEM,NLOC*(NLOC-1)/2 + 2) = E3,1
.........................................
XMAT(IELEM,NLOC*(NLOC-1)/2+ NLOC - 1) = ENLOC,1
.........................................
XMAT(IELEM,NLOC*(NLOC-1)) = ENLOC,NLOC-1

A matrix MIELEM constructed on a triangle P1 is thus written as a function of XMAT as

follows (the * indicate the diagonal terms which are stored elsewhere since they are
assembled):

* XMAT(IELEM,1) XMAT(IELEM,2)
MIELEM = XMAT(IELEM,4) * XMAT(IELEM,3)
XMAT(IELEM,5) XMAT(IELEM,6) *

The following table summarises, for a few types of elements, the memory space required
for storing a matrix (for reference purposes, the space needed for compact storage is
indicated).

ACCESSIBILITE : FREE Page 90/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Type of element BIEF storage Compact storage

Quadrilateral Q1 NPOIN+12 NELEM=13 NPOIN 19 NPOIN
Triangle P1 NPOIN+ 6 NELEM=13 NPOIN 15 NPOIN
Triangle P2 NPOIN+30 NELEM=16 NPOIN 24 NPOIN
Quadrilateral Q2 (9 nodes) NPOIN+72 NELEM=19 NPOIN 33 NPOIN
Brick P1 NPOIN+56 NELEM=57 NPOIN 55 NPOIN
Prism TELEMAC-3D NPOIN+30 NELEM=61 NPOIN 43 NPOIN

EDGE-BASED STORAGE

Edge-based storage is a recent technique which enables to store a matrix in an optimal and
easy way. The idea is that the element of the matrix, let’s say e.g. ∫ Ψi Ψ j dΩ , with i
Ω
different from j, is not equal to 0 only if points I and j are linked by a segment of the mesh.
Every segment is thus the best location to store these off-diagonal terms. For a non
symmetrical matrix, there will be two coefficients to store on every segment, for a
symmetrical matrix, only one will be necessary. This can be extended to complex elements
such as quasi-bubble by adding the relevant segments. The data structure to deal with such
a storage is very simple:

An array called GLOSEG, equivalent of IKLE for elements, which gives the global
numbers of the two ends of the segment. Its dimension in Fortran is (NSEG,2) where
NSEG is the total number of segments, i.e. for triangles : (3*NELEM+NPTFR)/2.

An array called ELTSEG, with dimensions (NELEM,NS), where NS is the number of

segments in an element.(3 for a triangle). ELTSEG gives for every element the segment
numbers of its 3 segments.

An array ORISEG, with dimensions (NELEM,NS). ORISEG gives the orientation of every
segment in an element, i.e. it is equal to 1 if the segment is in counter-clockwise
orientation (from its point 1 to its point 2), and is equal to 2 otherwise.

A matrix storage then consists of:

- A diagonal
- Two arrays XA1 and XA2 of size NSEG.

XA1 contains the coefficient of point 2 in equation of point 1, and XA2 its symmetrical
part, coefficient of point 1 in equation of point 2.

XA2 is not necessary if the matrix is symmetrical. When the matrix is rectangular, XA2
first contains the part symmetrical to XA1, then the extra terms, each one corresponding
with a segment and with the same order as the segments.

ACCESSIBILITE : FREE Page 91/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The matrix thus stored is assembled.

The local numbering of segments in an element is the following:

Linear triangle:

Segment 1 goes from point 1 to point 2 or from point 2 to point 1 (depending of ORISEG)
Segment 2 goes from point 2 to point 3 or from point 3 to point 2 (depending of ORISEG)
Segment 3 goes from point 3 to point 1 or from point 1 to point 3 (depending of ORISEG)

Quasi-bubble triangle:

Segment 1 goes from point 1 to point 2 or from point 2 to point 1 (depending of ORISEG)
Segment 2 goes from point 2 to point 3 or from point 3 to point 2 (depending of ORISEG)
Segment 3 goes from point 3 to point 1 or from point 1 to point 3 (depending of ORISEG)
Segment 4 goes from point 1 to point 4
Segment 5 goes from point 2 to point 4
Segment 6 goes from point 3 to point 4

Segments 4 to 6 need no value of ORISEG, they always go from a linear point to the quadratic
point. This is used in matrix-vector products algorithms, see subroutine MVSEG.

Quadratic triangle:

Segment 1 goes from point 1 to point 2 or from point 2 to point 1 (depending of ORISEG)
Segment 2 goes from point 2 to point 3 or from point 3 to point 2 (depending of ORISEG)
Segment 3 goes from point 3 to point 1 or from point 1 to point 3 (depending of ORISEG)
Segment 4 goes from point 1 to point 4
Segment 5 goes from point 2 to point 5
Segment 6 goes from point 3 to point 6
Segment 7 goes from point 2 to point 4
Segment 8 goes from point 3 to point 5
Segment 9 goes from point 1 to point 6
Segment 10 goes from point 1 to point 5
Segment 11 goes from point 2 to point 6
Segment 12 goes from point 3 to point 4
Segment 13 goes from point 4 to point 5
Segment 14 goes from point 5 to point 6
Segment 15 goes from point 6 to point 4

ORISEG is not useful for segments 4 to 15. For segments 4 to 12 the principle is that the first point
is linear (1, 2 or 3) and the second is quadratic (4, 5 or 6). Note that in rectangular linear-quadratic
matrices, segments 13, 14 and 15 will not appear as they link only quadratic points. This is why

ACCESSIBILITE : FREE Page 92/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

they have been put at the end, so that we have no gap in segment numbering for rectangular
matrices.
The total number of segments 4 to 6 is NSEG.
The total number of segments 7 to 9 is NSEG.
The total number of segments 10 to 11 is 3 NELEM
The total number of segments 13 to 15 is 3 NELEM

Quadratic boundary segments have also a local numbering. Point 1 and point 2 are defined as in
lilnear segments, point 3 is in the middle.

Linear prism:

Horizontal segments:

Segment 1 goes from point 1 to point 2 or from point 2 to point 1 (depending of ORISEG)
Segment 2 goes from point 2 to point 3 or from point 3 to point 2 (depending of ORISEG)
Segment 3 goes from point 3 to point 1 or from point 1 to point 3 (depending of ORISEG)
Segment 4 goes from point 4 to point 5 or from point 5 to point 4 (depending of ORISEG)
Segment 5 goes from point 5 to point 6 or from point 6 to point 5 (depending of ORISEG)
Segment 6 goes from point 6 to point 4 or from point 4 to point 6 (depending of ORISEG)

Vertical segments:

Segment 7 goes from point 1 to point 4

Segment 8 goes from point 2 to point 5
Segment 9 goes from point 3 to point 6

Crossed segments (for their global numbering see subroutine STOSEG41):

Segment 10 goes from point 1 to point 5

Segment 11 goes from point 2 to point 4
Segment 12 goes from point 2 to point 6
Segment 13 goes from point 3 to point 5
Segment 14 goes from point 3 to point 4
Segment 15 goes from point 1 to point 6

CONSTRUCTION OF MATRICES :

The BIEF matrices are calculated exactly through analytical integration. The terms of
a finite element matrix are generally polynomial integrals, which can be estimated through
successful completion of the analytical integration. On paper, the analytical integration is
long, tedious and a source of error, even though it is possible to take a few short cuts. This
is why we prefer the formal calculation software programme MAPLE V, which can give in
FORTRAN the exact result of an integral calculation.

ACCESSIBILITE : FREE Page 93/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

An example is given below of a matrix calculation as it can be carried out with MAPLE V.
The full description is given in the reference [06].

EXAMPLE OF A MASS-MATRIX CALCULATION

As an example, we choose here to calculate the mass matrix on a mesh of

quadrilaterals Q1. It is a little more complicated than linear triangles, but will show that the
Jacobian of isoparametric transformations is not always a constant.

It is sufficient to conduct the calculation on a quadrangle Q with vertices P1, P2, P3, P4
with coordinates (x1,y1), (x2,y2), (x3,y3) and (x4,y4). The element Mi,j of the elementary
mass matrix is written as follows: M i , j = ∫ Ψi Ψ j dQ .
Q

where Ψi is the base function associated with the node i (i=1,2,3 or 4).

We thus calculate the integral on a reference element thanks to an isoparametric transform

T. Any point of the reference element Q0 with coordinates (ξ,η) is associated with a point
on the quadrilateral Q with coordinates (x,y) such that:

x(ξ,η) = t 1 + t 2 ξ + t 3 η + t 4 ξη
y(ξ,η) = t' 1 + t' 2 ξ + t' 3 η + t' 4 ξη

P1
1
η P2
2 4 P4
+1
4 3 T
ξ
-1 +1 Y
1 2 3
-1 P3
X

Figure 6: isoparametric transformation (the numbers in the quadrilaterals indicate

local numbering)

The image by T of each vertex of the reference element thus gives a vertex of the
quadrilateral, which, by identification, provides the coefficients t1, t2, ... of the
transformation, as a function of the coordinates x1,y1 x2,y2 x3,y3 x4,y4 of the
vertices:

ACCESSIBILITE : FREE Page 94/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

t1 = ( +x1 + x2 + x3 + x4 ) / 4
t2 = ( -x1 + x2 + x3 - x4 ) / 4
t3 = ( -x1 - x2 + x3 + x4 ) / 4
t4 = ( +x1 - x2 + x3 - x4 ) / 4

t'1 = ( +y1 + y2 + y3 + y4 ) / 4
t'2 = ( -y1 + y2 + y3 - y4 ) / 4
t'3 = ( -y1 - y2 + y3 + y4 ) / 4
t'4 = ( +y1 - y2 + y3 - y4 ) / 4

A base Ψ in the real element corresponds in the reference element to a polynomial P such
that Ψ(x,y) = T(P(ξ,η)).

In our case, there are 4 polynomials associated with the 4 bases of the real element:

P1(ξ,η) = ( 1 - ξ - η + ξη )/4
P2(ξ,η) = ( 1 + ξ - η - ξη )/4
P3(ξ,η) = ( 1 + ξ + η + ξη )/4
P4(ξ,η) = ( 1 - ξ + η - ξη )/4

As for the bases Ψ, each polynomial has a value of 1 for one vertex of the element and 0
for the others.

In the reference element, the integral being sought takes the value:

+1 +1
∫
Q
Ψi Ψ j dQ = ∫
−1 −1∫ Pi Pj J dξdη

where J is the Jacobian of the transformation T , equal to the determinant of the Jacobian
matrix:

∂x ∂x
∂ξ ∂η
∂y ∂y
∂ξ ∂η

Let:
, , , ,
J = (t2 + t4 η) (t3 + t4 ξ) - (t2 + t4 η) (t3 + t4 ξ)

ACCESSIBILITE : FREE Page 95/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

J is assumed to be positive, which is obtained with local numbering of the points which
run along the boundary of the element in the counter-clockwise sense. J is not constant (it
is with linear triangles).

Since J is a polynomial, then we have the integral of a polynomial (of which the term with
the highest degree is in ξ3 η3).

This information is sufficient for MAPLE V to successfully carry out the calculation. For
example, for this calculation of a mass matrix, the following can be obtained:

FORMAL CALCULATION OF A Q1 MASS MATRIX :

MAT(1,1)=(X2*(2.*Y4+Y3)+X3*(Y4-Y2)+X4*(-Y3-2.*Y2))/36.
MAT(1,2)=(X2*(Y4+2.*Y3)+X3*(Y4-2.*Y2)-X4*(Y3+Y2))/72.
MAT(1,3)=(X2*Y3+X3*(Y4-Y2)-X4*Y3)/72.
MAT(1,4)=(X2*(Y4+Y3)+X3*(2.*Y4-Y2)+X4*(-2.*Y3-Y2))/72.
MAT(2,1)=(X2*(Y4+2.*Y3)+X3*(Y4-2.*Y2)-X4*(Y3+Y2))/72.
MAT(2,2)=(3.*X2*Y3+X3*(Y4-3.*Y2)-X4*Y3)/36.
MAT(2,3)=(X2*(-Y4+3.*Y3)+X3*(2.*Y4-3.*Y2)+X4*(-2.*Y3+Y2))/72.
MAT(2,4)=(X2*Y3+X3*(Y4-Y2)-X4*Y3)/72.
MAT(3,1)=(X2*Y3+X3*(Y4-Y2)-X4*Y3)/72.
MAT(3,2)=(X2*(-Y4+3.*Y3)+X3*(2.*Y4-3.*Y2)+X4*(-2.*Y3+Y2))/72.
MAT(3,3)=(X2*(-2.*Y4+3.*Y3)+3.*X3*(Y4-Y2)+X4*(-3.*Y3+2.*Y2 ))/36.
MAT(3,4)=(X2*(-Y4+2.*Y3)+X3*(3.*Y4-2.*Y2)+X4*(-3.*Y3+Y2))/72.
MAT(4,1)=(X2*(Y4+Y3)+X3*(2.*Y4-Y2)+X4*(-2.*Y3-Y2))/72.
MAT(4,2)=(X2*Y3+X3*(Y4-Y2)-X4*Y3)/72.
MAT(4,3)=(X2*(-Y4+2.*Y3)+X3*(3.*Y4-2.*Y2)+X4*(-3.*Y3+Y2))/ 72.
MAT(4,4)=(X2*Y3+X3*(3.*Y4-Y2)-3.*X4*Y3)/36.

On a vector computer, the previous FORTRAN expressions, integrated in a loop on the

elements, are vectorised.

The above demonstration can also be conducted in the same way with any matrix
which gives the integral of a polynomial expression. This is the case of mass matrices,
divergence type matrices. For diffusion matrices, it is the case with linear triangles, not
with quadrilaterals.

MATRICES WITH A QUASI-BUBBLE ELEMENT

The matrices to be calculated are of the type:

ACCESSIBILITE : FREE Page 96/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

M (i, j ) = ∫ f (Ψ j , ϕ i , F , G, H , U , V , W )dΩ
Ω

In these matrices, the test functions ϕ and the basis functions ψ could be of two
different types (P1 or Quasi-Bubble), as well as the discretisation functions of the variables
F,U,V...

Three cases are possible:

a - ϕ and ψ are of type P1:

This is the standard case. The elementary matrices are then composed of 9 terms and their
calculation is carried out by integration on a reference element by using a transformation
called isoparametric transformation.

b - ϕ and ψ are Quasi-Bubble type:

Elementary matrices of this type have 16 terms. These terms are calculated easily on
the basis of the calculation of the terms P1 thanks to the dividing up of the triangle T into
three sub-triangles. In fact, what we have is:

M (i, j ) = ∫ f (Ψ Tj 1 , ϕTi 1 , F ,...)dΩ + ∫ f (Ψ Tj 2 , ϕTi 2 , F ,...)dΩ + ∫ f (Ψ Tj 3 , ϕTi 3 , F ,...)dΩ

T1 T2 T3

I1 I2 I3

where the power indices denote the restrictions of the functions on the triangles in
question.

The restrictions of the basis function of the Quasi-Bubble element to the sub-triangles are
the basis functions P1 on these sub-triangles. Calculation of each of the integrals I1, I2,
and I3 is thus obtained independently by the method described in a. The sum of these
integrals must then be determined. In addition, the intersection of the supports of the
Quasi-Bubble basis functions is only made rarely on the three sub-triangles and often on a
single sub-triangle (off-diagonal terms). This results in the deletion of one or two of the
integrals I1, I2, and I3.

ACCESSIBILITE : FREE Page 97/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

P1

1 2

T1 T3
T 3 3
1
P4
2 1
1 T2 2
P2 P3

Figure 7: support of quasi-bubble function ψ1 (shaded) and local numbering within the
sub-triangles.

It can thus be observed that only the function ψ4 has a support which coincides with
the triangle T.

e.g.: calculation of the term M1,1:

we have:

M 1,1 = ∫ f (Ψ1T 1 , ϕ1T 1 , F ,...)dΩ + 0 + ∫ f (Ψ1T 3 , ϕ1T 3 , F ,...)dΩ

T1 T3
= m11,1 + m32,2

T1
m1, m2, or m3 designating the matrix P1 calculated on the sub-triangle Pi. In fact, Ψ 1 is
T3
the base function assigned to the first point of the sub-triangle T1, and Ψ 1 is the basis
function assigned to the second point of the sub-triangle T3.
The matrix M Quasi-Bubble x Quasi-Bubble is thus finally obtained thanks to pre-
assembling of sub-matrices P1. All these operations are summarised in the following table:

M1,1 = m11,1 + m32,2

M1,2 = m11,2
M1,3 = m32,1
M1,4 = m11,3 + m32,3
M2,1 = m12,1
M2,2 = m12,2 + m21,1
M2,3 = m21,2
M2,4 = m12,3 + m21,3

ACCESSIBILITE : FREE Page 98/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

M3,1 = m31,2
M3,2 = m22,1
M3,3 = m22,2 + m31,1
M3,4 = m22,3 + m31,3
M4,1 = m13,1 + m33,2
M4,2 = m13,2 + m23,1
M4,3 = m23,2 + m33,1
M4,4 = m13,3 + m23,3 + m33,3

c - ϕ and ψ are of different types:

The elementary matrices of this type are rectangular and include 12 terms. Here, we shall
deal with the case where ϕ is P1 and ψ Quasi-Bubble; the symmetrical situation results
directly from this.

The following can still be written:

M (i, j ) = ∫ f (Ψ Tj 1 , ϕTi 1 , F ,...)dΩ + ∫ f (Ψ Tj 2 , ϕTi 2 , F ,...)dΩ + ∫ f (Ψ Tj 3 , ϕTi 3 , F ,...)dΩ

T1 T2 T3
I1 I2 I3

Unlike the situation encountered in b), the restrictions of the functions ϕ to the sub-
triangles no longer correspond to the base functions P1 on these sub-triangles. In fact, what
we have is:

ϕi(Pj) = δij for 1 ≤ j ≤ 3

and:
ϕi (P4 ) = 1
3

since P4 is the centre of gravity of the triangle T.

In the internal numbering of the sub-triangles Ti , P4 always corresponds to the point n°3,
so that we have the following basis functions in the reference triangle:

ACCESSIBILITE : FREE Page 99/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

1.
3

1 2
0. 1. ξ
Figure 8: reference element for a triangle

function P P(1) P(2) P(3)

P1 (ξ, η) = 1 - ξ - 2 η 1
3 1 0 3
P2 (ξ, η) = ξ + η1 1
3 0 1 3
P3 (ξ, η) = η1 1
3 0 0 3

The isoparametric transformation retains the value of the functions at the nodes, so that the
anticipated result is obtained in the real mesh.

The matrix coefficients on the triangle T are obtained by assembling on the sub-triangles:

M1,1 = m11,1 + m32,2

M1,2 = m11,2 + m23,1
M1,3 = m23,2 + m32,1
M1,4 = m11,3 + m23,3 + m32,3
M2,1 = m12,1 + m33,2
M2,2 = m12,2 + m21,1
M2,3 = m21,2 + m33,1
M2,4 = m12,3 + m21,3 + m33,3
M3,1 = m13,1 + m31,2
M3,2 = m13,2 + m22,1
M3,3 = m22,2 + m31,1
M3,4 = m13,3 + m22,3 + m31,3

ACCESSIBILITE : FREE Page 100/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

In the opposite case of a Quasi-Bubble*P1 matrix, the following would be obtained:

M1,1 = m11,1 + m32,2

M1,2 = m11,2 + m32,3
M1,3 = m11,3 + m32,1
M2,1 = m12,1 + m21,3
M2,2 = m12,2 + m21,1
M2,3 = m12,3 + m21,2
M3,1 = m22,3 + m31,2
M3,2 = m22,1 + m31,3
M3,3 = m22,2 + m31,1
M4,1 = m13,1 + m23,3 + m33,2
M4,2 = m13,2 + m23,1 + m33,3
M4,3 = m13,3 + m23,2 + m33,1

MATRIX OPERATIONS:

It was shown above that matrix operations in BIEF are carried out at elementary level first
of all and then assembled.

This section gives a detailed description of the assembly algorithm and the main matrix
operations carried out in BIEF, in the case of an element by element storage, namely:

Product of a non symmetrical matrix and a vector

Product of a symmetrical matrix and a vector
Product of the transpose of a matrix and a vector
Processing of Dirichlet-type boundary conditions in the matrices
Diagonal preconditioning

The main algorithm is in fact the product of a matrix and a vector, as it will be seen that all
the others can be reduced to this, or at least be derived from it.

Then in the last section we shall detail the matrix-vector product when using an edge-based
storage.

ASSEMBLY OF AN ELEMENTARY VECTOR

With a known vector We of dimension NLOC for each element, a general vector R of
dimension NPOIN must be defined. Using the notation of chapter I, this is written as
follows:

ACCESSIBILITE : FREE Page 101/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

NELEM
R= ∑ (P W )
e =1
e e

Taking the example of the triangle P1, if the components of the vector WIELEM are
designated W1, W2, and W3 , then W1(IELEM) is the vector component at the node with
local number 1 of element IELEM, etc.

In FORTRAN, R is defined as follows:

DO 1 IELEM=1,NELEM

R(IKLE(IELEM,1)) = R(IKLE(IELEM,1)) + W1(IELEM)

R(IKLE(IELEM,2)) = R(IKLE(IELEM,2)) + W2(IELEM)
R(IKLE(IELEM,3)) = R(IKLE(IELEM,3)) + W3(IELEM)

1 CONTINUE

where IKLE is the connectivity table: IKLE(IELEM,I) is the general number of the Ith
local node of element IELEM.

This loop can be vectorised, as will be seen below.

The assembly loop is first of all transformed into three successive loops:
C
DO 1 IELEM=1,NELEM
R(IKLE(IELEM,1))=R(IKLE(IELEM,1))+W1(IELEM)
1 CONTINUE
C
DO 2 IELEM=1,NELEM
R(IKLE(IELEM,2))=R(IKLE(IELEM,2))+W2(IELEM)
2 CONTINUE
C
DO 3 IELEM=1,NELEM
R(IKLE(IELEM,3))=R(IKLE(IELEM,3))+W3(IELEM)
3 CONTINUE
C

These three loops are not automatically vectorised on a vector computer. Indeed, the
principle of vectorisation is to work in real time on a number of elements of the loop. This
number, referred to as the vector length of the computer, varies from one supercomputer to
another. It is 64 or 128 on a Cray YMP and up to 1024 on a Fujitsu. Taking the Cray as an
example, a loop running from 1 to NELEM will be processed in 64-element clusters. Thus,
if loop 1 is vectorised on a Cray computer, the instruction R(IKLE(IELEM,1))=
R(IKLE(IELEM,1)) +W1(IELEM) will be executed simultaneously for elements 1 to 64,
65 to 128 and so on. It is clear, therefore, that the result can only be correct if each
component of vector R is used only once in each cluster of 64 elements, i.e. if there are not
two elements IELEM1 and IELEM2 in the same cluster such that
IKLE(IELEM1,1)=IKLE(IELEM2,1). During compilation, the Cray will detect any
problem of backward dependency and not vectorise the loop.

ACCESSIBILITE : FREE Page 102/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

It is, however, possible to force vectorisation, but in this case it is essential to ensure that
the grid does not contain any backward dependencies. This again shows the advantages of
having split the initial assembly loop into three, as otherwise the condition of non-
dependency would have been more severe and hence more difficult to achieve. It would
have been necessary for IKLE(IELEM1,I) – IKLE(IELEM2,J) for I,J = 1,2,3 for all
different elements IELEM1, IELEM2 contained in each 64-element batch.

With a split assembly loop on the Cray, backward dependencies occurs if 2 different
elements IELEM1 and IELEM2 are such that:

IELEM1/64 = IELEM2/64 (/ here indicates the complete division)

and if I=1,2, or 3 such that

IKLE(IELEM1,I) = IKLE(IELEM2,I)

On a Fujitsu computer or similar, 64 must be replaced by 1024. The set conditions for the
grid are thus more severe.

In order to vectorise the three loops, it is necessary to find a system for numbering the
elements that eliminates any backward dependencies. This leads to a paradoxical situation
as such a numbering system is impossible in theory yet easy to apply in practice. Indeed:

- there are counter-examples if the number of elements is too small,

- heuristic algorithms easily find a large number of acceptable numbering systems if the
number of elements is sufficient (in practice sufficiently larger than the vector length, i.e.
64 for a Cray).

A counter-example and then a "heuristic" algorithm will therefore be discussed below.

Counter-example:

It is sufficient to consider a grid of triangles containing less than 64 elements, in which one
point belongs to four different triangles. This point must have the same local number (1, 2
or 3) in at least two of these triangles, which will create a backward dependencies that is
impossible to eliminate.

Element numbering algorithm

The basic idea is to search for dependency situations and progressively eliminate them.
Starting with an existing system (for more than 64 elements), the algorithm goes through

ACCESSIBILITE : FREE Page 103/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

the numbering and examines all sequences of 64 elements. When a faulty element appears,
its number is exchanged with that of a higher-ranking element.

The algorithm fails if there are still dependencies and no higher ranking element. In this
case the numbers are exchanged with those of a lower-ranking element, which means that
the previous checks are invalidated. The entire algorithm is therefore rerun!

In practice, this algorithm is extremely efficient and rarely has to be run more than twice.
This is due to the fact that, as soon as there are more than several hundred elements, the
combinational provides a large number of suitable numbering systems.

Once the elements have been numbered, it is simply a question of informing the compiler
that there are no backward dependencies in the loops that it will encounter (command
CDIR$ IVDEP on a Cray, *VOCL LOOP,NVREC on Siemens-Fujitsu).

In the case of a large vector length, there is no guarantee that a solution will exist for
average grids (containing a few thousand elements). In order to benefit from vectorisation,
however, it is still possible to split the assembly loops into sub-loops involving only
batches of elements that contain no backward dependencies. In this case, vectorisation is
forced for all these sub-loops.

Assuming that the following loop is valid for a vector length of 64:
C
DO 1 IELEM=1,NELEM
R(IKLE(IELEM,1))=R(IKLE(IELEM,1))+W1(IELEM)
1 CONTINUE
C
it can be transposed for higher vector-lengths as follows:
C
M64 = NELEM/64
N64 = MOD(NELEM,64)
C
DO 1 K =1,M64
DO 2 IELEM=(K-1)*64+1,K*64
R(IKLE(IELEM,1))=R(IKLE(IELEM,1))+W1(IELEM)
2 CONTINUE
1 CONTINUE
C
DO 3 IELEM=M64*64+1,M64*64+N64
R(IKLE(IELEM,1))=R(IKLE(IELEM,1))+W1(IELEM)
3 CONTINUE
C

Vectorisation of loops 2 and 3 may be forced.

Tests on a Cray YMP show that vectorisation provides very considerable savings in the
amount of time required for vector assembly:

- factor of 19 for quadrilaterals with bilinear interpolation (4 loops),

ACCESSIBILITE : FREE Page 104/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

- factor of 12 for triangles with linear interpolation (3 loops).

As vector assembly operations are used intensively in the algorithms, the overall amount of
time saved is also appreciable (up to a factor of 3).

PRODUCT NON SYMMETRICAL MATRIX BY VECTOR

The problem involves calculating the vector R, which is the product of the matrix M and
the vector V. It will be recalled that:
NELEM
R = MV = DV + ∑ ( P E P ).V
e =1
e e e
t

The example of quadrilaterals Q1 is discussed below. The matrix M is stored in the form of
two arrays DM(NPOIN) and XM(NELEM,12).

The FORTRAN instructions are as follows:

Contribution of the diagonal: product of D and V (loop that can be expressed in vector
form):
DO I=1,NPOIN
R(I) = DM(I) * V(I)
ENDDO

Contribution of off-diagonal terms: products E e ( PetV ) stored in working arrays W1, W2,
W3 and W4. This loop can also be expressed in vector form.
DO 2 IELEM=1,NELEM

General numbers of points for the element (given by the array IKLE)
I1 = IKLE(IELEM,1)
I2 = IKLE(IELEM,2)
I3 = IKLE(IELEM,3)
I4 = IKLE(IELEM,4)

As far as the element is concerned, the results concerning points with different local
numbers are stored separately (for numbers 1: W1, etc.)
W1(IELEM) = + XM(IELEM, 1) * V(I2)
+ XM(IELEM, 2) * V(I3)
+ XM(IELEM, 3) * V(I4)

W2(IELEM) = + XM(IELEM, 7) * V(I1)

+ XM(IELEM, 4) * V(I3)
+ XM(IELEM, 5) * V(I4)

ACCESSIBILITE : FREE Page 105/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

W3(IELEM) = + XM(IELEM, 8) * V(I1)

+ XM(IELEM,10) * V(I2)
+ XM(IELEM, 6) * V(I4)

W4(IELEM) = + XM(IELEM, 9) * V(I1)

+ XM(IELEM,11) * V(I2)
+ XM(IELEM,12) * V(I3)

2 CONTINUE

The vector defined by W1, W2, W3 and W4 is assembled and then added to R, which
already contains the contribution of the diagonal.

This algorithm is very easy to explain. Taking as an example the term XM(IELEM,1), this
is conventionally the term MAT(1,2) for element IELEM. It is thus a part of the coefficient
of point 2 of element IELEM in the equation for point 1 of the same element. The product
XM(IELEM,1)*V(I2) must therefore be added to the result R(I1). This is what happens in
loop 2 and the assembly loop via working array W1.

To summarise the method, it may be said that the vectors, and no longer the matrices, are
assembled. In a method involving classical compacting, vectorisation of the product matrix
x vector is broken by an internal loop on the surrounding points.

PRODUCT SYMMETRICAL MATRIX BY VECTOR

When the matrix is symmetrical, the terms XM(IELEM,NLOC*(NLOC-1)/2+1) to

XM(IELEM,NLOC*(NLOC-1)) are no longer stored as they are equal respectively to
XM(IELEM,1),...,XM(IELEM,NLOC*(NLOC-1)/2).

In calculating the working arrays W1,... , they simply need to be substituted, so that the
following are obtained, still for quadrilaterals Q1:

W1(IELEM) = + XM(IELEM,1) * V(I2)

+ XM(IELEM,2) * V(I3)
+ XM(IELEM,3) * V(I4)

W2(IELEM) = + XM(IELEM,1) * V(I1)

+ XM(IELEM,4) * V(I3)
+ XM(IELEM,5) * V(I4)
W3(IELEM) = + XM(IELEM,2) * V(I1)
+ XM(IELEM,4) * V(I2)
+ XM(IELEM,6) * V(I4)
W4(IELEM) = + XM(IELEM,3) * V(I1)
+ XM(IELEM,5) * V(I2)
+ XM(IELEM,6) * V(I3)

PRODUCT TRANSPOSED MATRIX BY VECTOR

ACCESSIBILITE : FREE Page 106/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The elementary products XM(IELEM,I) simply have to be replaced by

XM(IELEM,I+NLOC*(NLOC-1)/2) if I ≤ NLOC*(NLOC-1)/2 and by XM(IELEM,I-
NLOC*(NLOC-1)/2) if I > NLOC*(NLOC-1)/2. This gives the following for matrices
constructed on the quadrilaterals Q1:
W1(IELEM) = + XM(IELEM, 7) * V(I2)
+ XM(IELEM, 8) * V(I3)
+ XM(IELEM, 9) * V(I4)
W2(IELEM) = + XM(IELEM, 1) * V(I1)
+ XM(IELEM,10) * V(I3)
+ XM(IELEM,11) * V(I4)

W3(IELEM) = + XM(IELEM, 2) * V(I1)

+ XM(IELEM, 4) * V(I2)
+ XM(IELEM,12) * V(I4)

W4(IELEM) = + XM(IELEM, 3) * V(I1)

+ XM(IELEM, 5) * V(I2)
+ XM(IELEM, 6) * V(I3)

It can be seen from the last two examples above that problems of symmetry and
transposition are simply questions of how information is written for non-assembled
storage.

DIRICHLET-TYPE BOUNDARY CONDITIONS

The following discussion concentrates on the case in which Dirichlet-type points are not
eliminated from the equations. This is the only case that poses any problem, as it calls for
local correction of the matrix. Instead of eliminating points that are not degrees of
freedom, they are retained and assigned an equation of the type x=prescribed value. In the
other equations, 0 is taken as coefficient in places where there is a Dirichlet node, while
the right hand sides of the equations are of course also changed. In this way the symmetry
of the matrix is not modified.

In other words, for a Dirichlet-type point, 1 is placed on the matrix diagonal and off-
diagonal terms are cancelled. Starting from a point, however, there is no data structure for
quickly finding elements to which a single point belongs. It is thus apparently impossible
to cancel the related off-diagonal terms if these have been stored by element. In spite of
this, they may be cancelled with the loop described below, which again uses the principle
of the product matrix x vector.

In the following, the vector V has a value of 1 for a normal point and 0 for a Dirichlet
point. Thus any element of the matrix that would "touch" a Dirichlet point in a matrix x
vector product is cancelled and the other elements remain unchanged, which is the desired
effect. For a matrix constructed on quadrilaterals Q1, this gives:

DO 2 IELEM=1,NELEM

ACCESSIBILITE : FREE Page 107/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

I1 = IKLE(IELEM,1)
I2 = IKLE(IELEM,2)
I3 = IKLE(IELEM,3)
I4 = IKLE(IELEM,4)

XM(IELEM, 1) = XM(IELEM, 1) * V(I2) * V(I1)

XM(IELEM, 2) = XM(IELEM, 2) * V(I3) * V(I1)
XM(IELEM, 3) = XM(IELEM, 3) * V(I4) * V(I1)
XM(IELEM, 7) = XM(IELEM, 7) * V(I1) * V(I2)
XM(IELEM, 4) = XM(IELEM, 4) * V(I3) * V(I2)
XM(IELEM, 5) = XM(IELEM, 5) * V(I4) * V(I2)
XM(IELEM, 8) = XM(IELEM, 8) * V(I1) * V(I3)
XM(IELEM,10) = XM(IELEM,10) * V(I2) * V(I3)
XM(IELEM, 6) = XM(IELEM, 6) * V(I4) * V(I3)
XM(IELEM, 9) = XM(IELEM, 9) * V(I1) * V(I4)
XM(IELEM,11) = XM(IELEM,11) * V(I2) * V(I4)
XM(IELEM,12) = XM(IELEM,12) * V(I3) * V(I4)

2 CONTINUE

In a non-assembled matrix, the row and column for each Dirichlet-type point are thus
cancelled, with the exception of the diagonal terms.

As there is a special array for the matrix diagonal, it is then easy to replace an element on
this diagonal by 1 whenever the point in question is of Dirichlet type. Similarly, the set
values must then be placed in the second members of the linear system.

PRODUCTS BETWEEN DIAGONAL MATRIX AND MATRIX

These products appear in particular during diagonal or block-diagonal preconditioning of a

linear system, in which the system matrix M is replaced by DMD, in which D is a diagonal
matrix.

It is therefore necessary to obtain the products DM and MD.

In the following FORTRAN examples, D is declared to be a real array of dimension

NPOIN and D(I) represents the Ith element of the diagonal matrix. As it is obvious how the
diagonal of the results matrix is calculated, only the algorithms for the off-diagonal terms
will be discussed (case of quadrilaterals Q1):

Product DM:
C
DO 1 IELEM = 1 , NELEM
C
I1 = IKLE(IELEM,1)
I2 = IKLE(IELEM,2)
I3 = IKLE(IELEM,3)
I4 = IKLE(IELEM,4)
C
XM(IELEM, 1) = XM(IELEM, 1) * D(I1)
XM(IELEM, 2) = XM(IELEM, 2) * D(I1)
XM(IELEM, 3) = XM(IELEM, 3) * D(I1)

ACCESSIBILITE : FREE Page 108/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

C
XM(IELEM, 4) = XM(IELEM, 4) * D(I2)
XM(IELEM, 5) = XM(IELEM, 5) * D(I2)
XM(IELEM, 6) = XM(IELEM, 6) * D(I3)
C
XM(IELEM, 7) = XM(IELEM, 7) * D(I2)
XM(IELEM, 8) = XM(IELEM, 8) * D(I3)
XM(IELEM, 9) = XM(IELEM, 9) * D(I4)
C
XM(IELEM,10) = XM(IELEM,10) * D(I3)
XM(IELEM,11) = XM(IELEM,11) * D(I4)
XM(IELEM,12) = XM(IELEM,12) * D(I4)
C
1 CONTINUE
C

The formula for the assembled matrices would be DM(m,n) = D(m) x M(m,n). With
XM(IELEM,1) representing for example part of the term M(I1,I2), it is therefore logically
multiplied by D(I1). For the product MD, it will be multiplied by D(I2):

Product MD:

C
DO 1 IELEM = 1 , NELEM
C
I1 = IKLE(IELEM,1)
I2 = IKLE(IELEM,2)
I3 = IKLE(IELEM,3)
I4 = IKLE(IELEM,4)
C
XM(IELEM, 1) = XM(IELEM, 1) * D(I2)
XM(IELEM, 2) = XM(IELEM, 2) * D(I3)
XM(IELEM, 3) = XM(IELEM, 3) * D(I4)
C
XM(IELEM, 4) = XM(IELEM, 4) * D(I3)
XM(IELEM, 5) = XM(IELEM, 5) * D(I4)
XM(IELEM, 6) = XM(IELEM, 6) * D(I4)
C
XM(IELEM, 7) = XM(IELEM, 7) * D(I1)
XM(IELEM, 8) = XM(IELEM, 8) * D(I1)
XM(IELEM, 9) = XM(IELEM, 9) * D(I1)
C
XM(IELEM,10) = XM(IELEM,10) * D(I2)
XM(IELEM,11) = XM(IELEM,11) * D(I2)
XM(IELEM,12) = XM(IELEM,12) * D(I3)
C
1 CONTINUE
C

The result is itself in the form of a non-assembled matrix and the previous two loops are
vectorised.

MATRIX-VECTOR PRODUCT WITH EDGE-BASED STORAGE

As matrices in edge-based storage are fully assembled, the matrix-vector product is rather
easy to implement. If one wants to multiply a matrix A by a vector Y, to get X, first the

ACCESSIBILITE : FREE Page 109/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

diagonal terms have to be taken into account, X is initialised with DA Y. Then the off-
diagonal terms are dealt with with the following assembly loop:
DO ISEG=1,NSEG

X(GLOSEG(ISEG,1))=
X(GLOSEG(ISEG,1))+XA1(ISEG)*Y(GLOSEG(ISEG,2))

X(GLOSEG(ISEG,2))=
X(GLOSEG(ISEG,2))+XA2(ISEG)*Y(GLOSEG(ISEG,1))

ENDDO

For rectangular matrices, all the values of X are not initialised by the diagonal terms, so
some terms in X have to be previously set to 0.

SOLVERS AND PRECONDITIONING OPERATIONS

BIEF offers several iterative methods for solving a linear system M.X=B. This can be done
with preconditioning. A single solving subroutine SOLVE (see section A.IV) processes
both cases in which M is a matrix and those in which it is a block consisting of 4 or 9
matrices. In the subroutine SOLVE, preconditioning and method are specified by the
arguments PRECON and METHOD.

The integer PRECON may have the following values at present:

0 or 1: no preconditioning
2: preconditioning with the matrix diagonal
3: block-diagonal preconditioning
5: diagonal preconditioning with absolute value of matrix diagonal
7: Crout preconditioning
11: Gauss-Seidel EBE preconditioning
13: Preconditioning matrix given by the user
17: 3-diagonal solution on points on a vertical in 3D (specific to Telemac-3D)

or a combination of these values. As the basic preconditioning operations are designated

by a prime number, it can be split into PRECON prime factors in order to determine the
various preconditioning operations required by the user. For example, PRECON=14
corresponds to combined diagonal preconditioning and Crout preconditioning.

METHOD in an array of two integers.

The integer METHOD(1) may have the following values at present:

1 for the conjugate gradient method

2 for the conjugate residual method
3 for the normal equation conjugate gradient method

ACCESSIBILITE : FREE Page 110/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

4 for the minimum error method

5 for the squared conjugate gradient method
6 for the stabilised squared conjugate gradient method
7 for the GMRES method
8 for a direct solution

The integer METHOD(2) designates an option or alternative of the selected solver. At

present, this is only used for the GMRES method and designates the dimension of the
Krylov sub-space.

The various solvers and preconditioning operations will now be described in succession.

THE VARIOUS SOLVERS

A direct solver has been added to library BIEF from version 5.8 on (solver number 8). As
it may be changed in a near future (replaced by the software called MUMPS) it will not be
described here. Only iterative solvers are referred to hereafter.

These are used to solve a linear system of the form A.X = B. It will be recalled that the
different methods are chosen by assigning a certain value to the integer METHOD. All the
methods are iterative. Starting with an estimate of the solution X0, they construct a series
of vectors Xm that converge towards the exact solution of the system (provided of course
that A has the required properties).

Preconditioning options 7, 11, 13 and 17 are the only directly involved in the algorithms of
the various solution methods. The other types of preconditioning act on the matrix upline
of the calculation. A diagonal preconditioning like 2 or 3 may be combined with another
preconditioning like 7, 11 and 13. In this case the choice is the product of both, e.g. 14 for
a combination of diagonal and Crout preconditioning.

Note: preconditioning 7, 11 and 13 may behave differently in parallel, and are thus not
recommended with domain decomposition

The algorithms for the various methods available in BIEF are listed below. (X,Y)
designates the scalar product of the vectors X and Y and C is either the identity (no
preconditioning) or the Crout preconditioning matrix.

Conjugate gradient method (METHOD=1)

Convergence is ensured if A is a positive symmetrical matrix.

Initialisation operations:

ACCESSIBILITE : FREE Page 111/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

r0 = A X0 - B

solution of Cg0 = r0

d0 = g0

( r 0 , g0 )
ρ0 =
( Ad0 , d0 )

X1 = X0 - ρ0 d0

Iterations:

rm = rm-1 - ρm-1 A dm-1

solution of Cgm = rm

( r m , gm )
dm = gm + dm-1
( rm-1 , gm-1 )

( rm , dm )
ρm =
( dm , A dm )

Xm+1 = Xm - ρm dm

Conjugate residual method (METHOD=2)

Convergence is ensured if A is a positive symmetrical matrix.

Initialisation operations:

r0 = A X0 - B

solution of Cg0 = r0

d0 = g0

solution of Cd'0 = Ad0

ACCESSIBILITE : FREE Page 112/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

( g0 , Ad0 )
ρ0 =
( d' 0 , Ad0 )

X1 = X0 - ρ0 d0

Iterations:

rm = rm-1 - ρm-1 A dm-1

gm = gm-1 - ρm-1 d'm-1

( Agm , d' m-1 ) m-1

dm = gm - d
( Adm-1 , d' m-1 )

( Agm , d' m-1 )

Adm = Agm - Adm-1
( Adm-1 , d' m-1 )

solution of Cd'm = Adm

( Adm , gm )
ρm =
( Adm , d' m )

Xm+1 = Xm - ρm dm

Normal equation conjugate gradient method (METHOD=3)

Convergence is ensured if A is a regular matrix.

Initialisation operations:

r0 = A X0 - B

solution of Cg0 = r0

solution of t Cg'0 = g0

d0 = tA g'0

solution of Cd'0 = Ad0

ACCESSIBILITE : FREE Page 113/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

( d0 , d0 )
ρ0 =
( d' 0 , d' 0 )

X1 = X0 - ρ0 d0

Iterations:

rm = rm-1 - ρm-1 A dm-1

gm = gm-1 - ρm-1 d'm-1

solution of t Cg'm = gm

( t Ag' m , t Ag' m )
dm = t Ag' m + dm-1
( t Ag' m-1 , t Ag' m-1 )

solution of Cd'm = Adm

( t Ag' m , t Ag' m )
ρm =
( d' m , d' m )

Xm+1 = Xm - ρm dm

Minimum error method (METHOD=4)

Convergence is ensured if A is a regular matrix.

Initialisation operations:

r0 = A X0 - B

solution of Cg0 = r0

solution of t Cg'0 = g0

d0 = tA g'0

( g0 , g0 )
ρ0 =
( d0 , d0 )

ACCESSIBILITE : FREE Page 114/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

X1 = X0 - ρ0 d0

Iterations:

rm = rm-1 - ρm-1 A dm-1

solution of Cgm = rm

solution of t Cg'm = gm

( gm , gm )
dm = t Ag' m + dm-1
( gm-1 , gm-1 )

( gm , gm )
ρm =
( dm , dm )

Xm+1 = Xm - ρm dm

Conjugate gradient squared method (METHOD=5)

The algorithm is presented without preconditioning, as it is implemented in BIEF.

Convergence is ensured if A is a regular matrix.

Initialisation operations:

g0 = A X0 - B

k0 = p0 = g0

Iterations:

( km , g0 )
ρm =
( Apm , g0 )
hm = km - ρm A pm

Xm+1 = Xm - ρm (hm + km)

ACCESSIBILITE : FREE Page 115/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

gm+1 = gm - ρm A (hm + km)

m ( gm+1 , g0 )
β =
( gm , g0 )

m m 2 m
pm+1 = gm+1 + 2β hm + β p

km+1 = gm+1 + βm.hm

The stop test is the same for all the methods. Iterations continue until EPSI precision
specified by the user is reached after the test:

A.Xm+ 1 - B
≤ EPSI if B ≥ 1.(relative precision)
B

or

A.Xm+ 1 - B ≤ EPSI if B < 1. (absolute precision)

Conjugate gradient squared stabilised (METHOD=6)

This technique is a variant of the conjugate gradient squared method. It has been
programmed in BIEF by the University of Hannover (R. Ratke and A. Malcherek).

Generalised minimum residual =GMRES (METHOD=7)

The GMRES method has been published in 1983 and was a great improvement for non-
symmetrical complex linear systems. We shall only give here the basic idea, to explain
what is the dimension of KRYLOV space. As a matter of fact, this dimension is the
component KRYLOV of SLVCFG structures in BIEF.

At every iteration n of the algorithm, we try to minimise AX − B . This would give the
exact solution if X were sought for in the whole space, but here we restrict the
investigation to the so-called Krylov subspace generated by r = AXn - B, Ar, A2r, ...,
Ak-1r. k is the dimension of this space.

How to minimise AX-B in such a space will not be detailed here. We shall just consider 2
consequences of the method:

1) At every iteration, we have k matrix-vector to build, compared to 1 with the conjugate

gradient method, and 2 with the Normal equation technique.

ACCESSIBILITE : FREE Page 116/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

2) If A is a diagonal, the Krylov space will degenerate and the method will fail.

ACCESSIBILITE : FREE Page 117/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

DIAGONAL PRECONDITIONING

The problem here involves solving a linear system of the form MX=B.

"Point diagonal" preconditioning means preconditioning in the etymological sense of the

term, as it really applies before the system is solved. The diagonal matrix D is formed,
such that:

1 1
D (i, i ) = (PRECON = 2 or 3) D(i, i ) = (PRECON = 5)
M (i, i ) M (i, i )

M(i,i) must therefore be non-zero or even positive, as appropriate.

The following equation is then solved:

DMDD-1X = DB

This produces:

a new matrix: M' = DMD

a new unknown vector: X' = D-1X
a new right hand side: B' = DB

By construction in cases where M(i,i) is always positive, the diagonal of M' consists of
only 1 (this fact may be exploited by SOLVE for optimisation purposes). The effect of
preconditioning is thus to assign a comparable importance to all the equations.

Once the system M'X' = B' has been solved, it is easy to find X, which is equal to DX'.

This illustrates the advantage, with the EBE storage system, of having assembled the
matrix diagonal, which makes it easy to calculate D.

N.B. Other choices could be made for the diagonal D. This possibility is exploited
internally in BIEF, for example for block-diagonal preconditioning.

BLOCK-DIAGONAL PRECONDITIONING

This type of preconditioning is only meaningful when the matrix M is a block of squared
matrices. Detailed explanations are given below for an example with a block of 4 matrices:

Case of a block of 4 matrices

ACCESSIBILITE : FREE Page 118/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

The problem is to solve a system MX=B, in which:

M = M11 M12 , X= X1 and B B1

M21 M22 X2 B2

D11, D12, D21, and D22 will be used to designate the respective diagonals of M11, M12,
M21, and M22.

The basic idea is to obtain an approximate solution for M using the matrix:
~ D D12
M = 11 and an LDU decomposition of M in the form L D DU . The initial
D21 D22
system MX=B is thus changed into: L D ( ) M(
−1
DU )
−1
(
DU X = L D )−1
B

By expansion, this system can also be written as:

1 L-1 M U-1 1 D U X = 1 L-1 B

D D D

In this form, the system appears as a diagonal preconditioning of the system AX' = B', with
a given preconditioning diagonal D and assuming:

A = L-1 M U-1.

X' = U X.

B' = L-1 B

Having solved the system, the unknown X can be obtained by the formula X = U-1 X'.

The following operations must therefore be carried out in sequence:

~ D D12
1) Calculation of L, D and U by LDU decomposition of M = 11
D21 D22

2) Calculation of A, X' and B'

3) Solution of the system A X' = B' with simple diagonal preconditioning, in which the
diagonal D is specified (see previous section).

4) Calculation of X as a function of X'.

ACCESSIBILITE : FREE Page 119/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Operations 1, 2 and 4 will now be described in detail:

~ D D12
1) LDU decomposition of M = 11
D21 D22

I 0 D'11 0 I U12
M is broken down in the form
L21 I 0 D'22 0 I
By identification:

D'11 = D11

L21 = D21
D11

U12 = D12
D11

D'22 = D22 - L21 D11 U12

In practice, programming will be done by combining the following diagonals in the

memory:

D’11 and D11 D’22 and D22 L21 and D21 U12 and D12

This is done with the successive operations:

D21 = D21
D11

D22 = D22 - D21 D12

D12 = D12
D11

I 0 D11 0 I D12
M is thus
D21 I 0 D22 0 I

The diagonals D11 and D22 are inverted and the square root extracted. They are then kept
for subsequent diagonal preconditioning (operation 3). They are no longer used for
operations 2 and 4.

ACCESSIBILITE : FREE Page 120/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

2) Calculation of A, X' and B'

The following formulae are used:

I 0 -1 I 0
=
D21 I -D21 I

and :

I D12 -1 I -D12
=
0 I 0 I

The product I 0 M11 M12 is equal to M11 M12

-D21 I M21 M22 M21 - D21 M11 M22 - D21 M12

As for LDU decomposition, A will be calculated "in situ" by using M.

The following operations are therefore performed first of all:

M21 = M21 - D21 M11 and M22 = M22 - D21 M12

Right-hand multiplication by U-1 is then done by the following operations:

M12 = M12 - M11 U12 and M22 = M22 - M21 U 12

On completion of these operations, the matrix A takes the place of M.

X' is also calculated in situ by the operation: X1 = X1 + D12 X2 (X2 remains unchanged).

B' is calculated by the operation: B2 = B2 - D21 B1 (B1 remains unchanged).

4) Calculation of X

This is done by the single operation: X1 = X1 - D12 X2 (X2 remains unchanged).

Case of a block of 9 matrices

The problem is to solve the system MX=B, in which:

M11 M12 M13 X1 B1

M = M21 M22 M23 , X = X2 et B = B2
M31 M32 M33 X3 B3

ACCESSIBILITE : FREE Page 121/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Dij will be used to designate the respective diagonals Mij.

The preconditioning principle is exactly the same as for a block of 4 matrices.

The following operations must therefore be carried out in sequence:

D11 D12 D13

~
1) Calculation of L, D and U by LDU decomposition of: M = D21 D22 D23
D31 D32 D33

2) Calculation of A, X' and B'

3) Solution of the system A X' = B' with a single preconditioning diagonal, in which the
diagonal D is specified (see previous section).

4) Calculation of X as a function of X'.

Operations 1, 2 and 4 will now be described in detail:

D11 D12 D13

~
1) LDU decomposition of M = D21 D22 D23
D31 D32 D33

I 0 0 D' 11 0 0 I D' 12 D' 13

M is broken down in the form D' 21 I 0 0 D' 22 0 0 I D' 23
D' 31 D' 32 I 0 0 D' 33 0 0 I

In situ decomposition, in which the values D' and D are combined, involves the following
operations:

D11 is unchanged.

D21
D21 is replaced by
D11

D31 is replaced by D31

D11

ACCESSIBILITE : FREE Page 122/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

D22 is replaced by D22 - D21 D11 D12

D32 is replaced by D32 - D31 D12

D22

D23 is replaced by D23 - D13 D21

(division by D22 deliberately omitted)

D33 is replaced by D33 - D31 D13 - D32 D23

(D23 is in fact D22 D23 here)

D12 is replaced by D12

D11

D13
D13 is replaced by
D11

D23
D23 is replaced by (to rectify previous omission)
D22

The divisions are in fact replaced by multiplications by prior inversion of the diagonals
D11, D22 and D33, which will only be used in this form afterwards. The square root is then
extracted after inversion and they are kept for diagonal preconditioning.

2) Calculation of A, X' and B'

The following formulae are used:

I 0 0 -1 I 0 0 I 0 0
D21 I 0 = 0 I 0 - D21 I 0
D31 D32 I - D31 - D32 I 0 0 I

and

I D12 D13 -1 I - D12 0 I 0 - D13

0 I D23 = 0 I 0 0 I - D23
0 0 I 0 0 I 0 0 I

These two breakdown operations are used to calculate A, bearing in mind that M is
multiplied on the left by the lower part and on the right by the upper part. In situ
modifications are made to the matrix:

Left-hand multiplication is done by means of the following operations:

ACCESSIBILITE : FREE Page 123/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

M21 is replaced by M21 - D21 M11

M22 is replaced by M22 - D21 M12
M23 is replaced by M23 - D21 M13
M31 is replaced by M31 - D31 M11 - D32 M21
M32 is replaced by M32 - D31 M12 - D32 M22
M33 is replaced by M33 - D31 M13 - D32 M23

Right-hand multiplication is done by means of the following operations:

M12 is replaced by M12 - M11 D12

M22 is replaced by M22 - M21 D12
M32 is replaced by M32 - M31 D12
M13 is replaced by M13 - M11 D13 - M12 D23
M23 is replaced by M23 - M21 D13 - M22 D23
M33 is replaced by M33 - M31 D13 - M32 D23
On completion of these operations, the matrix A thus takes the place of M.

X' is also calculated in situ by the operations:

X1 = X1 + D12 X2 + D13 X3
X2 = X2 + D23 X3
X3 remains unchanged.

B' is calculated by the operations:

B1 remains unchanged.
B2 = B2 - D21 B1
B3 = B3 - D31 B1 - D32 B2

4) Calculation of X

This is done by the operations:

X3 remains unchanged.
X2 = X2 - D23 X3
X1 = X1 - D12 X2 - D13 X3.

ACCESSIBILITE : FREE Page 124/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

LU PRECONDITIONING

Two matrices L and U (lower and upper) are chosen so that the product LU is close to A.
The choice of L and U of course determines the efficiency of preconditioning and
examples will be given in the following sections. For the moment, L and U will be
assumed to have known values.

In place of the system M X = B, the following equivalent system is solved:

L-1 M U-1 U X = L-1 B

This produces:

a new matrix: M' = L-1 M U-1

a new unknown vector: X' = U X
a new second member: B' = L-1 B

After solving this system, X is obtained by the formula X = U-1 X'

When M is symmetrical, it is preferable to choose an LU breakdown in which L and U are

each transposed from the other. In the case of LU = LtL iterative methods such as that of
the conjugate gradient (see B.IV.1) may be adapted to produce only one inversion by
(LtL)-1 . See [3] on this subject.

CROUT PRECONDITIONING

Principle

In this case, the aim is to obtain a decomposition close to M in the form N = LDU, in
which L and U are respectively lower and upper, with the identity as diagonal.

Assuming that the diagonal of M is the identity (if this is not the case, it is simply a
question of applying a diagonal preconditioning before Crout preconditioning, provided
that the diagonal of M allows this). M is then written as a function of the elementary
matrices Ee:
NELEM
M =I+ ∑P E P
e =1
e e e
t

ACCESSIBILITE : FREE Page 125/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

To obtain an approximation of M, the aim is to apply the identity: 1 + ∑ ε i ≈ ∏ (1 + ε i )

i i
NELEM
with small values of εi. This gives: M = ∏ (I + P E P )
e =1
e e e
t

Ee is a zero-diagonal matrix. Introducing:

E e with the diagonal as identity, equal to the matrix Ee for the off-diagonal terms.
E e = Ee + I e (Ie elementary-level identity).
I e equal to I with zeros on the diagonal at positions corresponding to the nodes of element
e. I e = I − Pe Le Pet .
Crout's decomposition is then applied to E e , hence: E e = Le De E e .
in which Le is a lower triangular matrix with the identity as diagonal, De a diagonal matrix
and Ue an upper triangular matrix with the identity as diagonal. The approximate
expression for M becomes:
NELEM
~
M= ∏ (I
e =1
e + Pe ( Le DeU e ) Pet )
Lastly, a similar expression, written symmetrically, is used for N:
1
~
NELEM NELEM
~ ~
N= ∏ e e e e ∏ ( I e + Pe ( De ) Pet )
( I
e =1
+ P ( L ) P t
)
e =1
∏ (I
e = NELEM
e + Pe (U e ) Pet )

NELEM
~
The product ∏ (I
e =1
e + Pe ( De ) Pet ) which is a diagonal matrix that will by designated D, is

easy to calculate.

A linear system of the form N.X = B is thus solved by a succession of forward and
backward sweeps, firstly on the upper triangular matrices Ue and then, having inverted the
diagonal matrix D, on the lower triangular matrices Le.

Example with triangles P1.

The matrix M is given by its diagonal DM(NPOIN), which is the identity, and its off-
diagonal terms XM(NELEM,6) (M is not assumed to be symmetrical).

LDU breakdown

The elementary matrices are broken down into LDU products by applying Crout's
algorithm. The result is stored for the matrices De in DN(NPOIN) after assembly by
multiplication and for Le and Ue in XN(NELEM,6).

ACCESSIBILITE : FREE Page 126/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Crout's algorithm applied to a matrix (aij) (1≤i,j≤n) is then written as follows:

If j=1,n then:
If i=1,j then:
i −1
β ij = aij − ∑ α ik β kj (if i=1, the summation is 0)
k =1
and
If i=j+1,n then:
j −1
1
α ij = (aij − ∑ α ik β kj ) (if i=1, the summation is 0)
β jj k =1

An LU breakdown is thus obtained (L consisting of the αij and U of the βij values). LDU
breakdown is then obtained by dividing each βij by βii:
L lower triangular matrix: Lij = αij (j<i), Lii = 1, Lij = 0 (i<j)
D diagonal matrix: Dii = βii
U upper triangular matrix: Uij = βij (j<i), Uii = 1, Uij = βij / βii (i<j)

In FORTRAN, this gives:

C
DO 200 IELEM=1,NELEM
C
C MATRIX TO BE BROKEN DOWN ( WITH VALUES 1 ON THE DIAGONAL)
C
C LINE 1
A11 = 1.D0
A12 = XM(IELEM,1)
A13 = XM(IELEM,2)
C LINE 2
A21 = XM(IELEM,4)
A22 = 1.D0
A23 = XM(IELEM,3)
C LINE 3
A31 = XM(IELEM,5)
A32 = XM(IELEM,6)
A33 = 1.D0
C
C CROUT L*U DECOMPOSITION
C
C ROW 1 (BETA11=1)
ALFA21 = A21
ALFA31 = A31
C
C ROW 2
BETA12 = A12
BETA22 = A22 - ALFA21*BETA12
ALFA32 = (A32 - ALFA31*BETA12)/BETA22
C
C ROW 3
BETA13 = A13
BETA23 = A23 - ALFA21*BETA13
BETA33 = A33 - ALFA31*BETA13 - ALFA32*BETA23
C
C L*D*U BREAK DOWN
C THE EXTRA DIADONAL TERMS AND W2,W3 ARE STORED IN XN (W1 IS NOT
C USED BECAUSE BETA11=1)

ACCESSIBILITE : FREE Page 127/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

C
XN(IELEM,1) = BETA12
XN(IELEM,2) = BETA13
XN(IELEM,3) = BETA23/BETA22
C
XN(IELEM,4) = ALFA21
XN(IELEM,5) = ALFA31
XN(IELEM,6) = ALFA32
C
W2(IELEM) = BETA22
W3(IELEM) = BETA33
C
200 CONTINUE
C

The matrix L is stored in XN(IELEM,4), XN(IELEM,5) and XN(IELEM,6), matrix U in

XN(IELEM,1), XN(IELEM,2) and XN(IELEM,3) and arrays W2 and W3 are assembled
by multiplication in DN (previously initialised at 1) as follows:
C---------------------------------------------------------------------
C LOOP WITH FORCED VECTORISATION
C---------------------------------------------------------------------
C
CDIR$ IVDEP
DO 10 IELEM = 1 , NELEM
DN(IKLE(IELEM,2)) = DN(IKLE(IELEM,2)) * W2(IELEM)
10 CONTINUE
C
CDIR$ IVDEP
DO 20 IELEM = 1 , NELEM
DN(IKLE(IELEM,3)) = DN(IKLE(IELEM,3)) * W3(IELEM)
20 CONTINUE
C

The loop appearing in the multiplying assembly may be vectorised for the same reasons as
in a conventional assembly.
The vector DN is then inverted, as N-1 is the point of interest.
C
C DN INVERSION
C
CALL OV( 'X=1/Y ' , DN , DN , Z , C , NPOIN )

Inversion of system N.X = B

C-----------------------------------------------------------------------
C
C INITIALISATION: X = RIGHT HAND SIDE
C
CALL OV( 'X=Y ' , X , B , Z , C , NPOIN )
C
C-----------------------------------------------------------------------
C
C SERIE OF LOWER TRIANGULAR MATRICES INVERSION
C
CDIR$ IVDEP
DO 30 IELEM = 1 , NELEM
C
X(IKLE(IELEM,2)) = (X(IKLE(IELEM,2))
* - XN(IELEM,4) * X(IKLE(IELEM,1)) )
C
X(IKLE(IELEM,3)) = ( X(IKLE(IELEM,3))

ACCESSIBILITE : FREE Page 128/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

* - XN(IELEM,5) * X(IKLE(IELEM,1))
* - XN(IELEM,6) * X(IKLE(IELEM,2)) )
C
30 CONTINUE
C
C MULTIPLICATION BY DN (ALREADY INVERTED)
CALL OV( 'X=XY ' , X , DN , Z , C , NPOIN )
C
C SERIE OF UPPER TRIANGULAR MATRICES INVERSION
C
CDIR$ IVDEP
DO 40 IELEM = NELEM , 1 , -1
C
X(IKLE(IELEM,2)) = ( X(IKLE(IELEM,2))
* - XN(IELEM,3) * X(IKLE(IELEM,3)) )
C
X(IKLE(IELEM,1)) = ( X(IKLE(IELEM,1))
* - XN(IELEM,1) * X(IKLE(IELEM,2))
* - XN(IELEM,2) * X(IKLE(IELEM,3)),)
C
40 CONTINUE
C
C-----------------------------------------------------------------------
C
Loops 30 and 40 cannot normally be vectorised, even with the precautions taken to
vectorise the vector assembly. Indeed, this would require IKLE(IELEM1,I) ≠
IKLE(IELEM2,J) for I,J = 1,2,3 for all different elements IELEM1, IELEM2 taken in a
cluster of e.g. 64 elements , and this condition is only achieved for I=J in the grids used
here. Nevertheless, forced vectorisation may be considered. The result obtained in this way
will certainly not be a solution of N.X = B, but it should not be forgotten that the aim of
constructing N was to obtain an approximation of M, i.e. an approximate solution of M.X
= B. It is therefore quite acceptable to take the result with forced vectorisation for this
purpose. In any case, as will be seen below, there is stop test at the end of any iterative
method, ensuring that a good solution has been obtained. Tests show that Crout's
preconditioner is particularly effective when it can be applied. For diffusion matrices, the
computation cost can be reduced by 50% in spite of the time spent in constructing the
preconditioner.

GAUSS-SEIDEL EBE PRECONDITIONING

The principle is similar to that of Crout preconditioning. Assuming that the diagonal of M
is the identity, L is chosen equal to the lower part of M and with an identity diagonal, and
U equal to the upper part of M, with an identity diagonal. Thus:

L+U=M+I

Once this choice has been made, the forward and backward sweep principle is the same as
for Crout preconditioning.

ACCESSIBILITE : FREE Page 129/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

BIBLIOGRAPHY

[01] J.-M. HERVOUET

TELEMAC 2D Version 3.0 Principal note.
Rapport EDF HE43/94.051

[02] J.-M. HERVOUET

Vectorisation et simplification des algorithmes en éléments finis.
E.D.F. Bulletin de la Direction des Etudes and Recherches. Série C
Mathématiques, Informatique n°1, 1991, pp. 1-37.

[03] J.-M. HERVOUET

Méthodes itératives pour la solution des systèmes matriciels.
Rapport EDF HE43/93.049/A

[04] J.-M. JANIN, J.-M. HERVOUET, C. MOULIN

A positive conservative scheme for scalar advection using the M.U.R.D.
technique in 3D free-surface flow problems. XIth International Conference on
Computional methods in water resources" - Cancun, Mexico - Juillet 96
Also available as EDF report HE-42/96 41

[05] M. METCALF, J. REID.

Fortran 90 explained. Oxford Science Publications.1990.

[06] J.-M. HERVOUET, C. LE NORMANT

Symbolic computation of Finite Element matrices with MAPLE V.
Rapport EDF HE-43/97/048/A

[07] J.-M. HERVOUET

Hydrodynamique des écoulements à surface libre. Modélisation numérique
avec la méthode des éléments finis.
Presses de l’Ecole Nationale des Ponts et Chaussées. 2003.
[08] J.-M. HERVOUET
Hydrodynamics of free.surface flows, modelling with the finite element method
Wiley. 2007.

ISBN 2-85978-379-2

ACCESSIBILITE : FREE Page 130/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

APPENDIX 1: MATRIX STORAGE CONVENTIONS

The off-diagonal terms of a matrix A are placed in a two-dimensional array, the first dimension being
NELMAX, the maximum number of elements (the second dimension depends on the type of matrix
and storage). The following conventions are written in the form of rows, such that:

XA(IELEM,01) = XA12

This row means the following:

The contribution of element IELEM to the coefficient of point 2 in the equation for point 1 is placed
in XA(IELEM,01). 1 and 2 refer to the local numbering of element IELEM, and so the general
number of point 1 is IKLE(IELEM,1).

The location is also given in the form of a matrix whose elements give the second dimension of XA
in which the corresponding term is placed. These matrices are indeed used in BIEF, in which they are
given in the form of DATA tables. In view of FORTRAN placing notation for two-dimensional
arrays, the matrices appear in transposed form. For this reason, the transposed form of the matrices is
also given here.

Triangle P1-P1 EBE:

⎛− 1 2⎞ ⎛− 4 5⎞
⎜ ⎟ ⎜ ⎟
⎜ 4 − 3⎟ transposed form: ⎜ 1 − 6 ⎟
⎜ 5 6 −⎟ ⎜ 2 3 −⎟
⎝ ⎠ ⎝ ⎠

XA(IELEM,01) = XA12
XA(IELEM,02) = XA13
XA(IELEM,03) = XA23

If A is asymmetrical:

XA(IELEM,04) = XA21
XA(IELEM,05) = XA31
XA(IELEM,06) = XA32

Triangle P1-Quasi-bubble EBE:

ACCESSIBILITE : FREE Page 131/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

⎛− 4 7⎞
⎛ − 1 2 3⎞ ⎜ ⎟
⎜ ⎟ ⎜1 − 8⎟
⎜ 4 − 5 6 ⎟ transposed form: ⎜2
⎜ 7 8 − 9⎟ 5 −⎟
⎝ ⎠ ⎜ ⎟
⎜3 6 9 ⎟⎠
⎝

XA(IELEM,01) = XA12
XA(IELEM,02) = XA13
XA(IELEM,03) = XA14
XA(IELEM,04) = XA21
XA(IELEM,05) = XA23
XA(IELEM,06) = XA24
XA(IELEM,07) = XA31
XA(IELEM,08) = XA32
XA(IELEM,09) = XA34

Triangle Quasi-bubble-P1 EBE:

⎛− 1 2⎞
⎜ ⎟ ⎛ − 3 5 7⎞
⎜3 − 4⎟ ⎜ ⎟
⎜5 transposed form: ⎜ 1 − 6 8⎟
6 −⎟ ⎜ 2 4 − 9⎟
⎜ ⎟ ⎝ ⎠
⎜7 8 9 ⎟⎠
⎝

XA(IELEM,01) = XA12
XA(IELEM,02) = XA13
XA(IELEM,03) = XA21
XA(IELEM,04) = XA23
XA(IELEM,05) = XA31
XA(IELEM,06) = XA32
XA(IELEM,07) = XA41
XA(IELEM,08) = XA42
XA(IELEM,09) = XA43

Triangle Quasi-bubble Quasi-bubble or Quadrilateral Q1-Q1 EBE:

⎛− 1 2 3⎞ ⎛− 7 8 9⎞
⎜ ⎟ ⎜ ⎟
⎜7 − 4 5⎟ ⎜1 − 10 11⎟
⎜ 8 10 − transposed form :
6⎟ ⎜2 4 − 12 ⎟
⎜ ⎟ ⎜ ⎟
⎜ 9 11 12 − ⎟⎠ ⎜3 5 6 − ⎟⎠
⎝ ⎝

XA(IELEM,01) = XA12

ACCESSIBILITE : FREE Page 132/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

XA(IELEM,02) = XA13
XA(IELEM,03) = XA14
XA(IELEM,04) = XA23
XA(IELEM,05) = XA24
XA(IELEM,06) = XA34

If A is asymmetrical:

XA(IELEM,07) = XA21
XA(IELEM,08) = XA31
XA(IELEM,09) = XA41
XA(IELEM,10) = XA32
XA(IELEM,11) = XA42
XA(IELEM,12) = XA43

Triangle P1 EBE - Quadratic triangle EBE:

. 1 2 3 4 5
6 . 7 8 9 10
11 12 . 13 14 15

XA(IELEM,01) = XA12
XA(IELEM,02) = XA13
XA(IELEM,03) = XA14
XA(IELEM,04) = XA15
XA(IELEM,05) = XA16
XA(IELEM,06) = XA21
XA(IELEM,07) = XA23
XA(IELEM,08) = XA24
XA(IELEM,09) = XA25
XA(IELEM,10) = XA26
XA(IELEM,11) = XA31
XA(IELEM,12) = XA32
XA(IELEM,13) = XA34
XA(IELEM,14) = XA35
XA(IELEM,15) = XA36

Quadratic triangle EBE - Triangle P1 EBE:

ACCESSIBILITE : FREE Page 133/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

. 1 2
3 . 4
5 6 .
7 8 9
10 11 12
13 14 15
XA(IELEM,01) = XA12
XA(IELEM,02) = XA13
XA(IELEM,03) = XA21
XA(IELEM,04) = XA23
XA(IELEM,05) = XA31
XA(IELEM,06) = XA32
XA(IELEM,07) = XA41
XA(IELEM,08) = XA42
XA(IELEM,09) = XA43
XA(IELEM,10) = XA51
XA(IELEM,11) = XA52
XA(IELEM,12) = XA53
XA(IELEM,13) = XA61
XA(IELEM,14) = XA62
XA(IELEM,15) = XA63

Prism P1-P1 EBE or Quadratic triangle EBE:

- 1 2 3 4 5
16 - 6 7 8 9
17 21 - 10 11 12
18 22 25 - 13 14
19 23 26 28 - 15
20 24 27 29 30 -

transposed form:

- 16 17 18 19 20
1 - 21 22 23 24
2 6 - 25 26 27
3 7 10 - 28 29
4 8 11 13 - 30
5 9 12 14 15 -
XA(IELEM,01) = XA12

ACCESSIBILITE : FREE Page 134/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

XA(IELEM,02) = XA13
XA(IELEM,03) = XA14
XA(IELEM,04) = XA15
XA(IELEM,05) = XA16
XA(IELEM,06) = XA23
XA(IELEM,07) = XA24
XA(IELEM,08) = XA25
XA(IELEM,09) = XA26
XA(IELEM,10) = XA34
XA(IELEM,11) = XA35
XA(IELEM,12) = XA36
XA(IELEM,13) = XA45
XA(IELEM,14) = XA46
XA(IELEM,15) = XA56

If A is asymmetrical:

XA(IELEM,16) = XA21
XA(IELEM,17) = XA31
XA(IELEM,18) = XA41
XA(IELEM,19) = XA51
XA(IELEM,20) = XA61
XA(IELEM,21) = XA32
XA(IELEM,22) = XA42
XA(IELEM,23) = XA52
XA(IELEM,24) = XA62
XA(IELEM,25) = XA43
XA(IELEM,26) = XA53
XA(IELEM,27) = XA63
XA(IELEM,28) = XA54
XA(IELEM,29) = XA64
XA(IELEM,30) = XA65

ACCESSIBILITE : FREE Page 135/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

APPENDIX 2: THE SELAFIN FORMAT

Note : for unclear historical reasons this format is also sometimes called SERAFIN

This is a binary file.

The records are listed below. Records are given in the FORTRAN sense. It means that every
record corresponds to a FORTRAN WRITE.:

1 record containing the title of the study (80 characters),

1 record containing the two integers NBV(1) and NBV(2) (NBV(1) the number of variables,
NBV(2) with the value of 0),

NBV(1) records containing the names and units of each variable (over 32 characters),

1 record containing the integers table IPARAM (10 integers, of which only 4 are currently
being used).

If IPARAM (7) is not 0: the value corresponds to the number of planes on the vertical (in prisms.)
If IPARAM (8) is not 0: the value corresponds to the number of boundary points (in parallel).
If IPARAM (9) is not 0: the value corresponds to the number of interface points (in parallel).

if IPARAM (10) = 1: a record containing the computation starting date in 6 integers : year,
month, day, hour, minute, second

1 record containing the integers NELEM,NPOIN,NDP,1 (number of elements, number of

points, number of points per element and the value 1),

1 record containing table IKLE (integer array of dimension (NDP,NELEM) which is the
connectivity table. beware: in TELEMAC-2D, the dimensions of this array are (NELEM,NDP)),

1 record containing table IPOBO (integer array of dimension NPOIN); the value is 0 for an
internal point, and gives the numbering of boundary points for the others. This array is never used (its
data can be retrieved by another way). In parallel the table KNOLG is given instead, keeping track of
the global numbers of points in the original mesh.

1 record containing table X (real array of dimension NPOIN containing the abscissas of the
points),

1 record containing table Y (real array of dimension NPOIN containing the ordinates of the
points),

ACCESSIBILITE : FREE Page 136/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

Next, for each time step, the following are found:

1 record containing time T (real),

NBV(1)+NBV(2) records containing the results arrays for each variable at time T.

ACCESSIBILITE : FREE Page 137/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

APPENDIX 3: PROGRAMMING RULES

We give here a number of programming rules that are meant to facilitate understanding and
debugging, as well as a patron for subroutine header.

Subroutine header:
C ****************
SUBROUTINE METEO
C ****************
C
*(PATMOS,WINDX,WINDY,FUAIR,FVAIR,X,Y,AT,LT,NPOIN,VENT,ATMOS,
* HN,TRA01,GRAV,ROEAU,NORD,PRIVE)
C
C***********************************************************************
C TELEMAC 2D VERSION 6.0 02/01/04 J-M HERVOUET (LNH) 01 30 87 80 18
C
C***********************************************************************
C
C FONCTION : CALCUL DES CHAMPS DE VENT ET DE PRESSION
C EN GENERAL A PARTIR DE FICHIERS DE DONNEES
C
C CE SOUS-PROGRAMME PEUT ETRE COMPLETE PAR L'UTILISATEUR
C
C-----------------------------------------------------------------------
C
C FUNCTION: SETTING ATMOSPHERIC PRESSURE AND WIND VELOCITIES
C
C MUST BE ADAPTED BY USER.
C
C-----------------------------------------------------------------------
C ARGUMENTS
C .________________.____.______________________________________________.
C | NOM |MODE| ROLE |
C |________________|____|______________________________________________|
C | PATMOS |<-- | ATMOSPHERIC PRESSURE
C | WINDX,Y |<-- | TWO COMPONENTS OF WIND VELOCITY
C | FUAIR,FVAIR | -->| IDEM IF WIND CONSTANT.
C | X , Y | -->| COORDINATES OF POINTS IN THE MESH
C | AT,LT | -->| TIME, ITERATION NUMBER
C | NPOIN | -->| NUMBER OF POINTS IN THE MESH
C | VENT | -->| YES IF WIND TAKEN INTO ACCOUNT
C | ATMOS | -->| YES IF PRESSURE TAKEN INTO ACCOUNT
C | HN | -->| DEPTH
C | TRA01 | -->| WORKING ARRAY
C | GRAV | -->| GRAVITY ACCELERATION
C | ROEAU | -->| WATER DENSITY
C | NORD | -->| DIRECTION OF NORTH, COUNTER-CLOCK-WISE
C | | | STARTING FROM VERTICAL AXIS
C | PRIVE | -->| USER WORKING ARRAYS (BIEF_OBJ BLOCK)
C |________________|____|_______________________________________________
C MODE : -->(DONNEE NON MODIFIEE), <--(RESULTAT), <-->(DONNEE MODIFIEE)
C
C-----------------------------------------------------------------------
C
C APPELE PAR : TELMAC
C
C SOUS PROGRAMME APPELE : OV
C
C***********************************************************************
C
USE BIEF
C

ACCESSIBILITE : FREE Page 138/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

IMPLICIT NONE
INTEGER LNG,LU
COMMON/INFO/LNG,LU
C
INTEGER LT,NPOIN
C
DOUBLE PRECISION PATMOS(NPOIN),X(NPOIN),Y(NPOIN)
DOUBLE PRECISION WINDX(NPOIN),WINDY(NPOIN)
DOUBLE PRECISION HN(NPOIN),TRA01(NPOIN)
DOUBLE PRECISION FUAIR,FVAIR,AT,GRAV,ROEAU,P0,Z(1),NORD
C
LOGICAL ATMOS,VENT
C
TYPE(BIEF_OBJ) :: PRIVE
C
C-----------------------------------------------------------------------
C

Programming rules

General rules

- All subroutines and functions must conform to the subroutine header given in the previous
paragraph.

- All subroutines and functions must be protected by an IMPLICIT NONE statement. Their
arguments types must be given with their INTENT.

- Error messages: they must be given in French and English, using logical unit LU taken in
COMMON block INFO. LNG = 1 is French, LNG = 2 is English. Parameterising the listing
logical unit is necessary because it is not always 6 in parallel, as the listing of slave processors
does not appear on the screen but is redirected to files.

- Lines must be limited to a size of 72 characters, and only in UPPERCASE. Spaces must be
only one blank, for example between a CALL and the name of a subroutine. This is to
facilitate research of character string in source code.

- Indents in IF statements and nested loops are of 2 blanks.

- Tabs for indenting are forbidden. The reason is that depending on compilers they represent a
random number of blanks (6, 8, etc.) and that it is not standard Fortran.

- Blank lines are better started by a “!” or a “C”.

Defensive programming

When programming, one has always to keep in mind that wrong information may have been
given by the user, or that some memory fault has corrupted the data. Hence when an integer

ACCESSIBILITE : FREE Page 139/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

OPT may only have 2 values, say 1 and 2 for option 1 and option 2, always organise the tests
as follows:
IF(OPT.EQ.1) THEN
! here option 1 is applied
ELSEIF(OPT.EQ.2) THEN
! here option 2 is applied
ELSE
! here something wrong happened, it is dangerous to go further, we stop.
IF(LNG.EQ.1) THEN
WRITE(LU,*) ‘OPT=’,OPT,’ OPTION INCONNUE DANS LE SOUS-PROGRAMME…’
ENDIF
IF(LNG.EQ.2) THEN
WRITE(LU,*) ‘OPT=’,OPT,’ IS AN UNKNOWN OPTION IN SUBROUTINE…’
ENDIF
CALL PLANTE(1)
STOP
ENDIF

Use of modules
Modules are very useful but used in excess they may become very tricky to handle without
recompiling the whole libraries. For example the declaration modules containing all the
global data of a program cannot be changed without recompiling all subroutines that use it.

A common way of developing software in the Telemac system is to add modified subroutines
in the user FORTRAN FILE. This will sometimes be precluded for modules as some conflicts
with already compiled modules in libraries will appear.

A moderate use of modules is thus prescribed (though a number of inner subroutines in BIEF
would deserve inclusion in modules).

ACCESSIBILITE : FREE Page 140/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

APPENDIX 4: INDEX

ADDBLO....................................25, 29, 83 DIM1 .............................. 15, 26, 28, 29, 46

ALLBLO ..........................................25, 83 DIM1_EXT............................................. 29
ALLMAT .........................................25, 83 DIM2 .............................. 15, 24, 28, 29, 33
ALLOCATE ...........................................10 DIM2_EXT............................................. 29
ALLVEC ....................................24, 26, 83 DIMDISC ......................................... 28, 33
ALLVEC_IN_BLOCK .........................24 DIMENS ............................... 61, 80, 81, 82
ATANC ..............................................72, 73 DIRICH ............................................ 13, 51
BIEF_CLOSE_FILES .....63, 64, 79, 85, 86 Dirichlet.......................... 51, 108, 115, 116
BIEF_DEF ........................................11, 14 DIVQ ...................................................... 42
BIEF_DESIMP .......................................70 DOTS ................................................ 61, 62
BIEF_FILE ...........................13, 22, 63, 85 ECRGEO .......................................... 67, 69
BIEF_MESH...........................................60 ELM............................................ 15, 28, 33
BIEF_MESH 13, 14, 16, 22, 23, 31, 51, 66, ELTSEG ........................................... 18, 98
67, 68, 83, 92 EOF................................................... 11, 62
BIEF_OBJ....10, 12, 13, 14, 15, 16, 17, 18, EXTERNAL ..................................... 11, 27
19, 20, 21, 22, 24, 25, 26, 28, 30, 32, 44, FAC ............................................ 20, 55, 57
45, 49, 53, 64, 66, 67, 68, 70, 72, 76, 79, FFBT....................................................... 37
82, 83, 146, 147 FILPOL................................................... 67
BIEF_OPEN_FILES .64, 66, 76, 78, 79, 85 FILTER ................................................... 64
BIEF_SUITE ...........................................70 FIND_IN_SEL ........................................ 68
BIEF_SUM..............................................62 FLUBDF................................................. 41
BIEF_VALIDA ........................................71 FLUBOR ................................................ 40
BLOCK ..13, 14, 15, 16, 24, 25, 26, 29, 51, FLUDIF .................................................. 42
52, 83, 125, 146 FMATMA......................................... 34, 64
CHARAC .................................................73 FONSTR ................................................. 68
CHGDIS..................................................27 Gauss-Seidel ......................................... 118
CLIP........................................................63 GGRADF................................................ 41
CMPOBJ .................................................27 GLOSEG ........................................ 98, 117
CONFIG_CODE.....................................66 GMRES ............................ 21, 52, 118, 124
conjugate gradient.........118, 121, 124, 132 GRADF................................................... 41
conjugate residual .................................118 HUGRADP............................................. 43
CORLAT..................................................74 IELBOR ...................................... 62, 82, 95
CORRXY .................................................74 IFAPAR............................................ 19, 55
CPSTMT .................................................28 IKLBOR ........................................... 93, 94
CPSTVC ...........................................28, 44 IKLE ...... 23, 67, 83, 92, 93, 94, 95, 96, 98,
CREATE_DATASET.................69, 71, 72 109, 110, 111, 112, 113, 115, 116, 117,
Crout .....118, 119, 132, 133, 134, 136, 137 135, 136, 139, 144
CVDFTR .................................................73 IKM .................................................. 58, 59
DAMOCLES.....................................80, 81 IKP.................................................... 58, 59
DECLARATIONS_TELEMAC 63, 75, 76, ILMAX ................................................... 58
80, 82 INBIEF ................................. 23, 66, 74, 83

ACCESSIBILITE : FREE Page 141/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

INDPU ........................................19, 55, 59 NBPEL.................................................... 62

INTENT ....................................11, 12, 147 NBPTS.................................................... 62
ISEG..................................................18, 55 NELBOR .......................................... 93, 94
JULTIM...................................................73 NELEM ..... 17, 67, 83, 92, 95, 96, 98, 109,
KNOGL.................................18, 19, 54, 55 110, 111, 112, 113, 115, 116, 117, 133,
KNOLG.........................18, 54, 55, 67, 144 134, 135, 136, 144
KRYLOV............................21, 52, 53, 124 NHM........................................... 19, 58, 59
LECDON_TELEMAC2D....66, 77, 79, 80, NHP ............................................ 19, 58, 59
84 normal equation .................................... 118
LEGO................................................49, 50 NPOIN... 17, 45, 46, 54, 57, 63, 64, 67, 69,
LITENR .............................................69, 70 70, 74, 92, 95, 96, 98, 109, 112, 113, 116,
LUMP .....................................................49 133, 134, 135, 136, 144, 146, 147
MAMURD ..............................................36 NPTFR...................... 17, 47, 48, 67, 93, 98
MAPLE V .....................................101, 138 NPTIR............................. 19, 55, 58, 59, 67
MASBAS ................................................39 NULONE.................................... 93, 94, 95
MASKEL ..............................30, 31, 38, 64 NUMLIQ ................................................ 55
MASUPG................................................33 OM.................................................... 31, 48
MASVEC................................................39 ORISEG.................................................. 98
MATDIF ...........................................32, 33 OS ........... 11, 12, 13, 26, 27, 28, 44, 45, 46
MATFGR................................................35 OSBD ............................................... 46, 47
MATGRF................................................35 OSD .................................................. 11, 12
MATMAS .........................................32, 64 OSDB ..................................................... 47
MATQGR ...............................................35 OSDBIF.................................................. 48
MATRBL................................................50 OV ............................ 45, 46, 135, 136, 146
MATRIX 13, 14, 30, 38, 49, 51, 52, 64, 82, OV_2 ...................................................... 46
83, 101, 103, 108, 112, 114, 116, 117, 134, OVBD..................................................... 47
139 OVD ....................................................... 46
MATUGH ...............................................36 OVD_2 ................................................... 46
MATVEC..........................................49, 50 OVDB..................................................... 48
MATVGR ...............................................34 P_DMAX................................................ 56
MAUGUG...............................................34 P_DMIN ................................................. 56
MED......................................22, 70, 71, 72 P_DOT.................................................... 57
minimum error ......................................118 P_DOTS.................................................. 62
MOTCAR .......................77, 78, 80, 81, 82 P_DSUM .......................................... 56, 57
MOTINT ...........................................80, 81 P_IMAX ................................................. 56
MOTLOG .........................................80, 81 P_IMIN................................................... 56
MOTREA....................................80, 81, 82 P_ISUM.................................................. 57
MPI .......................................21, 56, 58, 63 P_MAIL.................................................. 57
MSK................................30, 31, 38, 51, 64 P_READ ........................................... 57, 59
MSLUMP................................................35 P_SYNC ................................................. 57
NACHB.......................................18, 55, 59 P_WRIT............................................ 57, 59
NBFEL ....................................................62 PARCOM................................................ 66
NBMPTS .................................................62 POINT_TELEMAC2D..................... 78, 82
NBOR .......................18, 47, 48, 67, 93, 94 POINTER ................................................. 9

ACCESSIBILITE : FREE Page 142/143 Copyright EDF 2010

EDF R&D Guide to programming in the Telemac system version 6.0 H-P74-2009-00801-EN

Version 1.0

POINTER_TO_BIEF_OBJ .....14, 15, 30 SUPG.......................................... 34, 36, 39

PRECON...........................21, 52, 118, 125 SUPGDIVU............................................ 42
PRECONDITIONING.....21, 52, 118, 125, Telemac-2D .. 28, 53, 65, 66, 70, 71, 84, 85
132, 136 TSLOC .................................................... 73
PRODF....................................................41 TYPDIA ........................................... 25, 29
PVM........................................................56 TYPEXT........................................... 25, 29
QGRADF ................................................40 VECTOR13, 30, 38, 49, 82, 109, 112, 114,
READ....................................22, 65, 81, 84 117
READWRITE ...................................22, 84 vectorisation ......... 110, 111, 112, 113, 136
SELAFIN65, 66, 68, 69, 70, 71, 72, 84, 85, VGRADF................................................ 40
144 VGRADF2.............................................. 42
SELAFIND .................................70, 71, 72 VGRADP.......................................... 39, 40
Sisyphe..............................................28, 85 WRITE ....................... 22, 69, 84, 144, 148
SKIPGEO..........................................69, 70 WRITE_DATA ................................ 70, 72
SLVCFG .................13, 14, 21, 22, 52, 124 WRITE_MESH........................................ 72
SOLVE..................13, 14, 51, 53, 118, 125 XSEG................................................ 20, 55
STRCHE ...........................................69, 74 YSEG................................................ 20, 55
SUBMIT ...........................................65, 84

ACCESSIBILITE : FREE Page 143/143 Copyright EDF 2010