1. Format of the PHI(DA) file
The PHI(DA) file created by EARTH ver 3.1 can be divided into three parts:
* header with some general information;
* fields of stored variables grouped by domains; and
* the block of auxiliary information normally used only for an EARTH restart.
Depending on the settings in the section [Compression] of the CHAM.INI file, EARTH can use
compression when writing the PHI file. The direct-access PHIDA file is created using
records of a fixed length, thus it is impossible to apply compression. The compression
algorithm is described in more detail in the appropriate document.
The PHI(DA) file is structured as follows:
A. PHI(DA) file header
--------------------------------------------------------------------------
Record |
Data written to
PHI file
--------------------------------------------------------------------------
1. | (
MESS(I),I=1,10 ), ( CTMP(I),I=1,5 )
2. | CARTES,
ONEPHS, BFC.OR.LSG59, XCYCLE, CCM.OR.CCV, LCMPRS
3. | NX, NY, NZ,
NPHI, DEN1, DEN2, EPOR, NPOR, HPOR, VPOR,
| LENREC, NUMBLK, NMATST, NFMAK1
4. | RINNER,
FLOAT(NPRPHI), FLOAT(NCSPAT), FLOAT(NFMAK2),
| FLOAT(IDMAT1), FLOAT(IDMAT2)
5. | (
NAME(I),I=1,NPHI )
6. | (
F(KXXU+I),I=1,NX )
7. | (
F(KYYV+I),I=1,NY )
8. | (
F(KZZW+I),I=1,NZ )
9. | Either
(F(KZZW+I),I=1,NZ), or (F(KZP+I),I=1,NZ) if KZP.NE.0
10. | ( LWORK(I),I=1,NPHI )
B. Fields of stored variables grouped by domains
--------------------------------------------------------------------------
Record | Data written to PHI file
--------------------------------------------------------------------------
Domain header for the 2nd, 3rd, etc. domains
DO IDMN= 1, NUMDMN
IF(IDMN.GT.1) THEN
11m NXDMN(IDMN), NYDMN(IDMN), NZDMN(IDMN)
12m ( F(ICLCR(IDMN,3)+I),I=1,NXDMN(IDMN) )
13m ( F(ICLCR(IDMN,1)+I),I=1,NYDMN(IDMN) )
14m ( F(ICLCR(IDMN,5)+I),I=1,NZDMN(IDMN) )
15m ( F(ICLSZ(IDMN,3)+I),I=1,NXDMN(IDMN) )
16m ( F(ICLSZ(IDMN,1)+I),I=1,NYDMN(IDMN) )
17m ( F(ICLSZ(IDMN,5)+I),I=1,NZDMN(IDMN) )
18m ( LFCLNG(IDMN,IDR),IDR=1,6 )
ENDIF
Fields of stored
variables in NXNY chunks
DO IZ= 1,NZDMN(IDMN)
DO MPHI= 1, NPHI
IF(STORE(MPHI)) THEN
19. (
F(MPHI0+I),I=1,NXNYDMN(IDMN) )
ENDIF
ENDDO
ENDDO
ENDDO
C. Block of auxiliary infromation for EARTH restart.
--------------------------------------------------------------------------
Record| Data written to PHI file
--------------------------------------------------------------------------
Property table
IF(NPRPHI.GT.0)
20. ( F(NFMAK1+I),I=1,NPRPHI )
Header to provide "old" NFUSER and
NFGMAK at restart
21. NFPWVT, NFUSER, NFGMAK
Patch-wise variables look up table
IF(NFPWVT.GT.0)
22. ( F(NFMAK1+NPRPHI+I),I=1,NFPWVT )
The NFUSER segment
IF(NFUSER.GT.0)
23. ( F(NFMAK1+NPRPHI+NFPWVT+I),I=1,NFUSER )
Memory segment allocated by the user in GR(1,1)
IF(NFGMAK.GT.0)
24. ( F(NFMAK1+NPRPHI+NFPWVT+NFUSER+I),I=1,NFGMAK )
Patch-wise variables
IF(NFMAK2-(NFMAK1+NPRPHI+NFPWVT+NFUSER).GT.0)
25. ( F(NFMAK1+NPRPHI+NFPWVT+NFUSER+NFGMAK+I),I=1,NFTPWV )
--------------------------------------------------------------------------
Note, that for the sequential access PHI file, records 1 and 5 are written using
FORMAT(1X,19A4); records 2,10,18m are written using FORMAT(1X,79L1); record 3,11m and 21
are written using FORMAT(1X,7I10); record 4 is written using FORMAT(6(1PE13.6)). Other
records are either compressed and then written as character strings with a variable
length; or written using FORMAT(6(1PE13.6)).
2. Header of the PHI(DA) file
-------------------------
The header of the PHI(DA) file consists of constants which provide additionalinformation
necessary either for EARTH, or PHOTON to process the file. The latest version of the
PHI(DA) file includes one more record which can be attributed to the header (record 21).
The only reason why it appears at the bottom part of the PHI(DA) file, is due to the
consideration of compatibility with earlier versions.
Constants written into the header of the PHI(DA) file created by PHOENICS ver. 3.1 have
the following meaning:
--------------------------------------------------------------------------
Ident. | Type | Meaning
--------------------------------------------------------------------------
MESS | CHARACTER*4 | Stores the run title
(total 40 characters)
CTMP | CHARACTER*4 | Stores version string
(total 20 characters).
|
| Version number is retrieved from VER.
CARTES | LOGICAL
| See POLIS
ONEPHS | LOGICAL
| See POLIS
BFC | LOGICAL
| See POLIS
XCYCLE | LOGICAL
| See POLIS
CCM | LOGICAL
| See POLIS
CCV | LOGICAL
| See POLIS
LCMPRS | LOGICAL
| Set to TRUE for
the compressed PHI file.
|
| Note, that if LCMPRS is TRUE, EARTH will
|
| read PHI file as compressed ignoring the
|
| setting in CHAM.INI
Well known NX,NY,NZ,NPHI,DEN1,DEN2,EPOR,NPOR,HPOR,VPOR,LENREC,
|
|
NUMBLK | INTEGER
| NUMBLK number of domains (applicable to
|
| MBFGE and new multi-domain EARTH 3.0).
NMATST | INTEGER
| Number of
entries (materials) into the
|
| property table.
NFMAK1 | INTEGER
| Starting index
of the F-array segment
|
| written after dependent variables.
RINNER | REAL
| See POLIS
Next three variables are in fact integers, but written as reals
NPRPHI | INTEGER
| Length of the
property table
NCSPAT | INTEGER
| Control Sum for
patches. It is compared to
|
| the that calculated at the restart to check
|
| for the PATCH consistency.
NFMAK2 | INTEGER
| End of the
F-array segment written after the
|
| dependent variables
IDMAT1 |
IDMAT2 |
Well known NAME, KXXU, KYYV, KZZW, KZP
LWORK | LOGICAL
| It
is set as LWORK(I)= STORE(I).AND.
|
| ISLN(I).GT.0.AND.MOD(IPRN(I),5).EQ.0
--------------------------------------------------------------------------
3. Fields of stored variables grouped by domains
------------------------------------------------
The set of integer arrays describing domains, as well as the structure of the F-array
allocated for domains are applicable only to the multi-domain EARTH version 3.0 and
higher. The MBFGE approach to multi-domain problems is based on "carving"
domains from a single grid, thus fields of stored variables must be dumped into the
PHI(DA) file as for one domain.
4. Segment of F-array dumped into the PHI(DA) file
----------------------------------------------
This segment, sometimes referred to as the "user allocated" segment, is the part
of the F-array between NFMAK1 and NFMAK2 (common block /GENI/). At present it incorporates
the following memory groups:
* The Property table;
* Patch-wise variables look up table (details of the PWV look up table, as well as
patch-wise storage can be found in the 'Patch-wise variables' document);
* The NFUSER-segment is allocated by the direct call to the ADDL1 if NFUSER (common block
/IDATA/ in 'satear') is greater than zero. It is up to the user to introduce a structure
of that segment.
* Memory segment allocated by the user in GR(1,1). This segment is the part of the F-array
allocated by calls to the GXMAKE subroutine.
* Patch-wise variables form a segment of the F-array, the structure of which is described
by the PWV look up table.
EARTH versions prior to 3.1 dumped the "user allocated" segment as a single
chunk of the F-array. As a result, the information stored in that segment could be read in
by EARTH at the restart only if the structure of the segment was exactly the same as that
created for the original run. There are many situations when that structure is different
at the restart. For example, an additional material entry, or even a new material, changes
the length of the property table.
Starting from the EARTH version 3.1, the "user allocated" segment is divided
into parts according to the logical structure described above. Each part is written
separately. This enabled to take from the PHI file at the restart as much information as
possible, even if the structure of the segment is different.
5. Work performed with the PHI(DA) file in EARTH (background information)
----------------------------------
The PHI(DA) file is created in EARTH by the DUMP subroutine which resides in the file
E2EAIO.FOR. Unfortunately, this FORTRAN file is not provided with the installation as it
forms part of the PHOENICS EARTH source code, which is confidential. Normally DUMP is
called from MAIN3, but it can be also called from the EXPST subroutine to provide
intermediate files for the EXPERT system; and from DUMPS for the IDISPA-controlled dumps.
EARTH reads the PHI(DA) file in the READFL subroutine (E2EAIO.FOR). READFL can be called
to perform three distinctive jobs:
A. Process the header of the PHI(DA) file, when called with MPHI=-1.
That call is made from the INDX subroutine, right after the PHI(DA) file is open for
reading which happens if at least for one variable FIINIT(MPHI)=READFI.
First EARTH tests for the version of the PHI(DA) file. Files created by PHOENICS older
than 3.0 are "old-formattted". Currently the test consists in the check for the
presence of the version string in the first line of the file. If it is found that the file
is in old format; OLDVER is set to TRUE. As a result only fields of stored variables will
be read in. There is also a difference between versions 3.0 and 3.1. in the format of the
"user segment" dumping. PHOENICS version 3.0 dumps that segment as a single
chunk, while version 3.1 divides it into logical groups (see the description in paragraph
4). Thus if EARTH 3.1 encounters the PHI-file created by EARTH 3.0; only the property
table is taken from the bottom of the PHI(DA)-file (RSTPRP is set to TRUE). At the second
step EARTH carries out few more consistency checks on the PHI(DA) file, including the
check whether it is compressed or not. If the file is compressed, but compression is
OFF in CHAM.INI file, EARTH makes the initialization necessary to use the decompression.
B. Read in the field of MPHI variable for a current slab.
That is a group of calls made from the START subroutine. READFL is called to retrieve the
field of a variable MPHI necessary for its initialization. Note, that starting from EARTH
version 2.2.1, the order in which variables had been written into the PHI(DA) file can
differ from the current order of variables.
C. Read in the information stored at the bottom of the PHI(DA) file.
This call to READFL is also done from the START. The purpose of this call is to read in
the look up table of patch-wise variables; contents of the storage allocated by the user
in Group 1 Section 1 at the previous run; contents of the NFUSER segment; and the fields
of patch-wise variables. Note, that the property table, which is also stored at the bottom
of the PHI(DA) file, is not processed by READFL. At restart it is either taken from the
PHI file by the GETABL, or recreated by the SETABL and REDPRP subroutines. These
subroutines are called from INDX.
Before reading any segment from the file EARTH checks its length. If "old" and
"new" lengths are the same the segment is read in. Note that no check of the
segment internal structure is performed.