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.
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 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 2 categories:
Increasing The Number Of Variables
The number of variables (φ's) that can be SOLVEd or STOREd at any time (150 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.
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:
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 25 CONTINUE RETURN C******************************************************************* C C--- GROUP 1. Run title and other preliminaries C 1 GO TO (1001,1002,1003), ISC 1001 CONTINUE
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.
Section 3 is used for memory allocation through GXMAKE for data which does not need to be written to PHI(DA).
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 ! END DO ! Visit Sec 8: finish of time step END DO
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.
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.