The XENIOS code HB
The XENIOS code hand-book
Index
1 Foreword
2 The code base structure
3 XENIOS flow chart
4 XENIOS input file and cards
5 How to run XENIOS with sequential solver
6 How to run XENIOS with parallel solver
7 Appendices. A, B, C
1 Foreword
The present handbook describes the finite-element computer code XENIOS, written in FORTRAN, devoted to the analysis of viscous, steady (statistically steady when considering turbulent flows) and unsteady flows.
The program features a modular structure, aimed at making future developments easier; initially developed for two-dimensional laminar flows, it is now capable of handling chemically reacting turbulent flows in two- and three-dimensional geometries.
XENIOS has represented a useful testbed to test improved numerical techniques. The program, originally conceived as a classical finite-element method, has later adopted stabilization techniques based on the Petrov - Galerkin formulation (Streamline Upwind/Petrov-Galerkin, and Pressure Stabilized /Petrov-Galerkin) which proved capable of containing instability effects typical of the classical Galerkin method, while at the same time ensuring a high degree of accuracy.
Further, the push to increase the complexity of test cases that can be tackled has led to the application of single and multiple level parallel solution strategies, based on Generalized Minimal Residual techniques (GMRES) like linear solver with building procedures of the stiffness matrix based on unassembled structures.
The first version of the code was laid in 1991, and focused on two aspects: the modularity of the base structure, so as to allow straightforward code extensions, and the memory management through dynamic allocation techniques. The latter aspect allows handling problems involving a very large number of unknowns while reducing the memory storage to a minimum.
In the following, a detailed flow-chart of the code in its current version is reported, with a description of the main subroutines is given.
Further, the meaning of the individual cards comprising an input file in its most general form is made clear. Finally, two “How to” sections give the protocols for running XENIOS with sequential and parallel solution techniques.
2 The code base structure
The basic code structure is given in Fig. 1.
Fig. 1 - Basic structure of the finite elent code XENIOS
Actually, the code is interfaced with mesh data file formats provided by the most popular commercial grid-generator (e.g. GAMBIT).
2.1 Memory management
Within XENIOS, all data are stored in central memory via the FORTRAN statement:
COMMON / BLANK / A (MTOT)
where the array dimension MTOT must be specified once and for allin the main program routine, named XENIOS; this in turn calls subroutines INPUT and DRIVER/DRIVEI which handle the two dashed box in Fig. 1.
Vector A is used to store all variables required for problem solution. The dimension of each variable is assigned while executing the probgram trough a technique named "Dynamic Memory Allocation”. Each variable in A can be addressed through appropriate pointers, also contained in vector A.
It is noted that, before subdividing the integration domain in elements, it is first subdivided in groups of elements, in order to make grid generation easier in complex flows, and to allow interfacing zones with different physical characteristics, and discretized with elements of different form (this features enables using unstructured meshes, by refining the computational grid only where strictly required).
The structure of vector A in a case where the integration domain consists of two groups only is given in Fig. 2.
Fig. 2 - Structure of the global vector A
It is noted that the top of vector A contains the initial addresses of variables of groups 1 and 2, plus a series of vectors referring to the whole problem. Then, the parts referring to each group first feature a series of integer variables, and then the pointers to the arrays in the group.
Should, for a given problem, the value chosen for MTOT turn out to be too low, the code signals that the memory boundaries have been violated, and allows restarting the simulation by specifying a new value of MTOT; if this is not the case, PRTDC prints out a dictionary listing all variables with their pointers and the memory required by the whole program. This enables making the most appropriate choice for the value of A.
3 XENIOS flow chart
Figure 1 stresses that the preprocessing and solution are held distinct in the program. The XENIOS code could simulate several flow conditions, by using different fluid modelling for turbulence and combustion phenomena. The set of flow problems and active degrees of freedom (DOF) are below resumed:
Problem code
/ Problem type / DOFsIopt1 / laminar iso-thermal / velocity components: UX, UY, UZ
pressure: PR
Iopt2 / laminar thermal / velocity components: UX, UY, UZ
pressure: PR
temperature: TE
Iopt3 / turbulent iso-thermal
(first order turbulence closures) / velocity components: UX, UY, UZ
pressure: PR
turbulent kinetic energy: KI
dissipation variable: DI
Iopt4 / turbulent reacting / velocity components: UX, UY, UZ
pressure: PR
temperatureor conserved scalar: TE
turbulent kinetic energy: KI
dissipation variable: DI
conserved scalar variance: G1
iopt5 / turbulent iso-thermal
(second order turbulence closures) / velocity components: UX, UY, UZ
pressure: PR
turbulent kinetic energy: KI
dissipation variable: DI
turbulent stress tensor components: T1 – T6
elliptic blending variable: AA
In what follow, Figures 3 and 4 report a detailed flow chart of the two phases, with reference to the solution of a turbulent flow (IOPT3). In this chart, small letters denote "functions", and capital letters denote “subroutines".
7
DMA – University of Rome “La Sapienza”, September 2003
XENIOS Hand book
inpkeyINPJOB / INPDYM / mpoint
clear
inpclr / dctnry
SETTRB / mpoint
rdfext / dctnry
INPAV
INPMH
INPCV / inpkey
INPBC / iclear
clear
inpkey
BCGEN
INPIC / clear
inpkey
ICGEN
INPUT / INPRL / clear
inpkey
mpoint
ELCARD / dctnry
INPEL / SETEL / INP3Q9 / mpoint
INPWRK
NWL927
IWL927
NFL927
IFL927
NPE927
IPE927 / dctnry
¾¾® / JACB27
PROP2D
GENEL
SFGL / GENEL1 / GENELD / GENELI
XENIOS / INPNR / inpkey
iclear
clear
NRGEN
ctrky1
INPPL
INPTC
INPOR / inpkey
mpoint
iclear
clear / dctnry
INPNRM / SETNR1
SETNR2 / SETNRM / local
JACB9 / move
clear
rowdot
INPID / IDPRE
SETID
mpoint
iclear / IDPRE27
dctnry
INPLM / INPLM1 / FORMLM
COLHT
RESIN
EQSET / DIAG
mpoint / dctnry
Fig. 3. - Flow chart of code XENIOS, data pre-processing for a turbulent flow problem
7
DMA – University of Rome “La Sapienza”, September 2003
XENIOS Hand book
clearITRUP1
COMBC
ELEMWL / WLLIB / WALL9 / DISSBC
ELEMNT / ELMLIB / QUADC9 / QDC293 / QDFLUX
QDWALL
XYDOF
clear
local
SFGD / move
rowdot
XENIOS / DRIVER / NINTCL
RHOBIN
DIFFTE
EMCNNR
EMDFT2
EMDFTR
EMCV
TRBDIS
TRBPRO
MOMROT
ADDLHS
ADDRHS
LOADBC
RESGEN
NRMGEN
NRMDOF
CONVER
GMRES
TIMING
PIVOTS
PRINTP
BACK
TIMING
RLXGEN
ITRCLP
NRMGEN
NRMGEN
ITERUP
ELEMWL
RESOUT
XYDOF
PRINTD / BASIS
WLLIB / UPDATE
WALL9 / DISSBC
TIMING
Fig. 4- Flow chart of code XENIOS, solution of a turbulent flow problem
25
DMA – University of Rome “La Sapienza”, September 2003
XENIOS Hand book
The main objectives of the most important subroutines used during the pre-processing and solution phases (which appear in Figs. 3 and 4) are outlined in the following.
INPUT: Manages the data acquisition, and in part their pre-processing.
INPJOB: Selects default values of cards identyifying the problem under consideration, and replaces them with values specified in input file, when appropriate.
On the basis of the nature of the problem to be solved, sets up arrays LNDOF and LPOINT containing the active degrees of freedom and the position of each degree of freeedom in the element stiffness matrix.
INPAV: Reads from input file the values of multiplicative factors in the expression of the perturbatting function of SU/PG and PS/PG.
INPMH: Reads information concerning the computational grid and sets up the cordinate array.
INPCV: Reads from input file the value of the maximum error allowed for the solution and residual, for convergence check.
INPBC: Reads from input file the Dirichlet’s boundary conditions and sets uo array F , containing them.
INPIC: Reads from input file the initial conditions for the problem, and feeds them into the solution array D.
INPRL: Reads the relaxation factor assigned to each degree of freedom, and feeds them to array RLX.
INPEL: Manages the subroutines For processing the information relevant to each element group.
Calls subroutine ELCARD reading and checking "minor-cards" characterizing the element type.
Through subroutine SETEL selects the element form; for instance, if elements with a second-order shape function have been chosen, calls subroutine INP3Q9.
INP3Q9: Sets up pointers to the position the arrays occupy in the dynamic memory, calls INPWRK which in turn manages the shape function computation, feed the element physical properties into array AMAT, genererates connection matrix IEN. Further, INP3Q9 generates the wall elements, elements where flux-type boundary conditions are enforced, and periodic elements..
INPNR: Allocates pointers for the dynamic memory of arrays DCNRM and NTD , which contains the director cosines of unit tensors both normal and tangent, and the numbering of node elements, for which a local reference set has to be identified..
In INPNR only set values are allocated in the above vectors.
INPPL: Constitutes the link between program XENIOS and the graphycal post-processing program XEGRAF (See Fig. 1.).
INPTC: Reads turbulence model constants.
INPOR: Selects and manages the model for optimal equation renumbering
INPNRM: Computes director cosines of the local reference set Edefined at wall elements, and fedds computed values in arrays DCNRM and NTD.
INPID: Manages the creation of array ID , containing equation numbering, and allocates the dynamic memory of arrays DPRED (solution at previous iteration), RESID (residual of algebraic system of discrete equations); IDIAG (addresses of diagonal elements of global stiffness matrix).
INPLM: Manages arrays LM of each group; they contain numbering of equations associated with local element node numbering.
RESIN: Reads restart file.
EQSET: Allocates the dynamical memory of arrays ALHS (memory space of GMRES vectors) and BRHS (array of global forcing terms); determines the stiffness matrix coefficients.
DRIVER: Controls all subroutine of solution-printout phase.
ITRUP1: Sets up the array containing the solution at previous iteration DPRED before initiating the iteration cycle, on the basis of initial conditions.
COMPBC: Transfer boundary conditions from array F to array D.
ELEMWL: Before initiating the iteration cycle, computes boundary conditions and viscous dissipation rate for wall elements in the computational domain (through a call to DISSBC).
Updates boundary conditions for viscous dissipation rate within the iteration cycle.
ELEMNT: Controls the generation of the element stiffness matrices, and forcing term arrays, and their assembly..
For instance, in the case of elements with second order shape functions and turbulent flows, it calls subroutine QUADC9.
QDC293: Computes the elements of the forcing term array corresponding to flux-type boundary conditions (FLUX).
Computes the shear stress boundary conditions applied to wall elements (WALL).
Rotates wall element velocities from local to global reference sete (XYDOF).
Computes the derivatives of shape functions with respect to coordinates X, Y, Z of the global reference set.
Determines the values of the degree of freedom in integration points at previous iteration wit respect to current one (NINTCL).
Computes diffusive properties (DIFFT1).
Computes diffuse and convective components of elelement stiffness matrix, and production terms to be allocated in the array of element forcing terms.
For wall nodes, rotates the equation set from global to local reference set (MOMROT).
Assembles element matrices and vectors (ADDLHS and ADDRHS) and inserts Dirichlet boundary conditions (LOADBC).
RESGEN: Generates the equation set residual vector.
NRMGEN: Computes Euclidean norms of sultion residual.
NRMDOF: Computes Euclidean norm for each degree of freedom.
CONVER: Checks solution convergence or divergence at each iteration.
GMRES: Solution routine
TIMING: Determines CPU time for computations.
PIVOTS: Locates and prints the number of negative or null entries in the global factorized stiffness matrix (such values are replaced with a small nonzero default value).
PRINTP: Prints factorized stiffness matrix when required in input file.matrix.
RLXGEN: Relaxes solution on the basis of values specified in input file (retain a fraction of solution at previous iteration).
ITRCLP: Clips turbulent quantities k and e.
ITERUP: Updates array D after each iteration; in the next iteration it will be used as previous solution.
RESOUT: Prints resul file.
PRINTD: Prints solution array after rotation of velocity components into global reference set x, y, z , at walls (XYDOF).
4 XENIOS input cards
In this Section the cards available as input to the XENIOS code, both for sequential and parallel runs, are individually described.
Before commenting on single cards, the general structure of an input file is shown.
@ JOB
TITLE =
IECHO =
IEXEC =
IACODE =
IREADR =
IWRITR =
IPRTIN =
IRANK =
NUMITE =
NSD =
NUMNP =
NUMEG =
ICOMPR =
ITURB =
ITHERM =
LINEAR =
DNTYPE =
IAXISY =
KEMOD=
@ CV
EPSRES =
EPSSOL =
@ MESH??????????????????
@ EL
GR = group no.
NTYPE =
NPRES=
LOWRE=
NICODE =
NUMAT =
MT
DENS =
VISC =
CONDC =
SP =
FL = no. of trailing strings NODE+ELEMENT
first key-point last key-point flux value
WL = no. of trailing strings
first key-point lastkey-point value of yn (boundary layer thickness)
PE = no. of trailing strings
first key-point last key-point flux value
SL = no. of trailing strings
first key-point lastkey-point value of yn (boundary layer thickness)
@ IC
UX = ALL or no. of trailing strings
only value for ALL option, or first node-last node-generation-value
UY = as above
UZ = as above
PR = as above
TE = as above
KI = as above
DI = as above
G1 = as above
+ SMC variables
@ BC = CONSTANT/PARABOLIC/HALFPARABOLIC/NODES/KFREE/FREE
to specify degrees of freedom, see comment to card IC
+ NODE&ELEMENT
@ TC
CMU =
CE1 =
CE2 =
SIGMAK =
SIGMAE =