Encyclopaedia Index



  1. Introduction
  2. User-accessible modules
  3. The MAIN program
  4. Control of GROUND
  5. The GROUND subroutine
  6. The group arrangement and internal flow control
  7. The groups and their functions
  8. Summary


Purpose: to present the structure and functions of the user-accessible part of Earth, and particularly of the Ground Stations.

A related lecture entitled "Using Ground", provides guidance on how to retrieve information from Earth, how to manipulate it in GROUND and how to send it back to Earth.

The listing of the FORTRAN modules described in this lecture can be found through POLIS.

Note that Satellite also has a user-accessible section. However, this is seldom used, and is not dealt with in the present course.

User-Accessible Modules

Two kinds of FORTRAN modules are accessible to the user of PHOENICS:

Their functions are:

EARTH calls GREX, and GREX calls GROUND

The MAIN Program

The MAIN program is made accessible to the user for the modification of array dimensions. This is done by resetting PARAMETER statements.

The arrays whose dimensions can be modified fall into 4 categories:

  1. Arrays which hold information about the 50 PHOENICS variables (the f's), the dimensions of which can be altered if more than 50 f's are needed
  2. Arrays used in the Q1 file to transmit data to Ground (arrays RG, IG, LG, CG)
  3. Character array where the PATCH names are held
  4. F-array, the large, central array used in PHOENICS as storage

Increasing The Number Of Variables

The number of variables (f's) that can be SOLVEd or STOREd at any time (50 by default) can be increased by changing the value of the parameter NUMPHI. NOTE that a similar modification has to be made in the MAIN program of the Satellite, otherwise the extra variables cannot be accessed.

Increasing of the number of variables is seldom needed.

Q1-To-Ground Arrays

The following arrays are available both in the Q1 file and in the GROUND subroutine; they can therefore be used for the transmission of data from the Q1 file to a user-written Ground Station:

Array Name Type Default dimension PARAMETER
RG real 200 NRG
IG Integer 200 NIG
LG Logical 100 NLG
CG Character*4 100 NCG

The default dimensions of these arrays can be changed by resetting the relevant parameter. NOTE that a similar modification has to be made in the MAIN program of the Satellite, and also in the GROUND subroutine.

Number Of Patches

If the maximum number of PATCHes has to be increased beyond its default of 5000, then the dimension of the NAMPAT array (which holds the names of the patches) has to be increased.

This is done by resetting the PARAMETER NPNAM. NOTE that a similar modification has to be made in the MAIN program of the Satellite, otherwise the extra patches cannot be set.

Increasing The Dimension Of The F-Array

The F-array is the central storage array.

Among other things, the F-array stores the cell values of all the SOLVEd and STOREd variables (the f's). It stores also properties, geometrical quantities and PATCH data.

The needs of F-array memory vary from problem to problem. The default F-array dimension (600000) suffices for many problems.

When the number of variables is large, and/or the grid is fine, the default dimension might not suffice to hold all the data.

In these circumstances, PHOENICS switches automatically to "out-of core" mode. The non-essential data are dumped onto disc (freeing F-array memory), and retrieved when needed. This, of course, slows down the performance of PHOENICS, because of the disc-access overhead.

In some occasions, the F-array size might not suffice, even in out-of-core mode.

In either case PHOENICS provides, in the file RESULT, an estimate of the F-array size required for in-core operation. Warning messages are also written to the VDU, informing the user that disk-files are being used.

In both circumstances (unwanted out-of-core mode or insufficient F-array storage), corrective action can be taken by enlarging the F-array (subject, of course, to the availability of computer memory).

This is done by resetting the parameter NFDIM. NOTE that modification of the Satellite is not needed.

Controlling The Ground Station

GREX is called from Earth at many well defined stages in the computation. GREX then acts as a "junction box", which determines which Ground Stations are active, and calls them.

Three PIL variables can be used in the Q1 file to activate (and deactivate) Ground Stations:

  1. The logical variable USEGRX activates, when TRUE, the use of GREX itself.
  2. The logical variable USEGRD activates, if TRUE, the call to the Ground Station called GROUND. This is supplied as an empty "form" where users can write their coding.
  3. The character variable NAMGRD, which allows the attachment and activation of Ground Stations with names other than GROUND or GREX.

The Ground Subroutine

The GROUND subroutine is just an [empty] example of Ground Station.

It is provided for the user to insert coding, which supplements, or even replaces, the built-in features.

At this point, it is important to stress that GROUND is not called directly by EARTH: EARTH calls GREX, from where ALL the active Ground Stations are called in order.

The Group Arrangement And Flow Control

The Ground Station is arranged in groups, reflecting the group structure of input file Q1.

These groups are visited at specific times during the computational procedure. Some of them are visited always, others, only when the user instructs PHOENICS to do so by way of settings in the Q1 file.

In GROUND, some groups are, for convenience, further organized into sections.

WHICH group and section is to be visited is controlled, in GROUND by two integer variables:

These are set within Earth, and passed onto GROUND via a COMMON statement.

IGR and ISC are thereafter used in GROUND for flow control, via GO TO statements such as:

   GO TO (1,2,3,4,5,6,7,8,9,10,11,12,13,14,25,25,25,25,19,20,25,

1 125,23,24,) IGR





C--- GROUP 1. Run title and other preliminaries


1 GO TO (1001,1002), ISC


The Groups and their functions

Group 1: Preliminaries

Group 1 of GROUND is ALWAYS VISITED at the beginning of each run.

Section 1 is used for the initialization of local variables; and in general, for any operation that has to be performed only once at the beginning of the computation.

Note that the user can, in this section, change the identification message written to the VDU. This is a wise, strongly-recommended practice, which allows to distinguish private versions of Earth from the public task.

Section 2 is used, on some machines, for special overlay practices. It is otherwise seldom used.


Groups 2 To 5: Grid Specification

Group 2 (time) is visited only when TLAST has been set to GRNDn in the Q1 file. The time-step size, DT, can be set in this group.

Group 3 (x-direction grid) is visited only in parabolic calculations (PARAB=T), when AZXU=GRNDn.

The x-extent of the domain can then be modified in GROUND as the computation proceeds downstream, by setting XRAT to the ratio of XULAST's between the previous and the current slab.

This is adequate, for instance, for the simulation of jets and boundary layers in parabolic mode.

GROUP 4 (y-direction grid) is visited only in parabolic calculations (PARAB=T), when AZYU=GRNDn. See Group 3 above for details

GROUP 5 (z-direction grid) is visited only in parabolic calculations (PARAB=T), when AZDZ=GRNDn. The current-slab width (DZ) can then be set in this group (e.g., as a function of the width of the boundary layer).

Examples of the use of Groups 3 - 5 can be found in GREX.


Group 6 (BFCs) And Group 7 (Variables)

GROUP 6 is called at the start of the current IZ slab when UGEOM=T (whether BFC=T or not), just after the geometrical quantities (inter-nodal distances, cell-face areas, etc.) have been set, thus allowing their modification.

GROUP 7 (variables) is inactive: it is not possible to change solver options at this stage.


Group 8: Terms And Devices

GROUP 8 is intended for the expert user with special needs. It provides extensive intervention in the finite-volume equation for each variable, and in the solution procedure.

The group is divided into 15 sections. The purpose of each section is indicated in the GREX listing, as well as the conditions for the section to be visited. Examples of use are also provided.

Novice users are strongly advised not to use this group.


Group 9: Properties

Group 9 is the place where the user can insert coding for the calculation of properties (e.g., density, temperature, etc.).

Because there is a large number of properties to set, this Group is subdivided into Sections, one for each property.

Each section is visited ONLY when the user instructs PHOENICS to do so, normally through Q1 settings of the kind: property=GRNDn

This group is within the IZ loop of Earth, which means that PHOENICS expects the values for the WHOLE CURRENT SLAB to be set here.

Many examples of Group-9 coding are provided, as for other groups, in GREX.


Group 10: Interphase Processes

Group 10 has a similar function to that of Group 9, this time in respect of inter-phase-transfer processes.

Inter-phase friction, heat-transfer coefficients, mass-transfer rates and interface (saturation) values are all calculated here, each in a separate section, and only if the appropriate variable has been set to GRNDn in Q1.

The variable is also slab-wise: values must be set, in each visit, for the whole of the current slab.


Group 11: Initial Conditions And Porosity

In Group 11, PHOENICS allows for the specification of complex initial fields for any variable or porosity type.

Access to Group 11 is gained through the use of a GRND flag in the value slot of a INIT command in the Q1 file. The values for the patch cells on the current slab are expected to be here.

A typical PATCH command for access to Group 11 of GROUND would be:

PATCH (name, INIVAL, ixf,ixl, iyf,iyl, izf,izl, 1,1)

INIT (name, PHI, 0, GRNDn)

Group 13: Boundary Conditions And Sources

Complex boundary conditions and sources can be specified in Group 13.

Specific sections of Group 13 are visited when GRNDn numbers are used in the coefficient/value slots of the COVAL command. Each GRND number corresponds to a particular section number.

The PATCH name and the variable index being dealt with are available and can be used as further criteria for flow control within each section (the lecture "Using GROUND" will provide details).

The coefficients/value for the patch cells on the current slab are expected to be set here.


Group 19: Special Visits

Group 19 is always visited.

Group 19 comprises several special calls from within Earth, which take place at well defined stages during the computation.

Earth does not expect any particular action - these visits are to allow the user to perform any additional calculations he may wish.

A typical use for Group 19 is to introduce additional output or printout - e.g. derivation of Mach Number.

Order of calling

DO ISTEP=1, LSTEP ! Transience loop

! Visit Sec 1: start of time-step

! DO ISWEEP=1, LSWEEP ! Outer-iteration loop

! ! Visit Sec 2: start of sweep

! ! DO IZ=1, NZ ! Slab loop

! ! ! Visit Sec 3: start of IZ slab

! ! ! DO ITHYD=1, LITHYD ! Hydrodynamic loop

! ! ! ! Visit Sec 4: start of iteration

! ! ! ! ...........

! ! ! ! Visit Sec 5: finish of iteration

! ! ! END DO

! ! ! Visit Sec 6: finish of IZ slab

! ! END DO

! ! Visit Sec 7: finish of sweep


! Visit Sec 8: finish of time step



Groups 20-24

Group 20 (Preliminary print-out) is visited at the beginning of the run, after the visit to Group 1 Section 1. Groups 23 and 24 are visited at the end of the run.

Summary Of Main Points

This lecture has reviewed the structure of Earth, and of its user-accessible FORTRAN modules.

Two different kinds of module are accessible in Earth for user modification:

A second lecture, "Using GROUND", explains how GROUND can be used for the addition of new features.