SATLIT is a name used both for a file, ie SATLIT.F (or .FOR or .FTN according to the operating system or compiler), and for a Fortran subroutine within that file.
The file named SATLIT contains several Fortran-coding sequences:
These will be described in turn.
The MAIN program of the SATELLITE may be inspected via POLIS (PHOENICS-2/Fortran), where the defaults of the various parameters, appearing simply as .. below, may be seen.
The major reason for making MAIN accessible is that, prompted perhaps by a message concerning the insufficiency of dimensions which has appeared at the VDU, the user may wish to extend the dimensions of some of the arrays which appear in it.
For example, the user may desire to employ more than the 50 variables which are allowed by the settings in the COMMON block which starts with COMMON/LDB1/, on the first page of the listing. If so, users should change the parameter NUMPHI to whatever larger number of variables he wishes to use. The following statement would increase the number to 60 PARAMETER (NUMPHI=60, NM=NUMPHI),
This automatically re-dimensions all those arrays that contain data items or flags related to each field variable.
PARAMETER statements are also provided for the dimensions of data- for-GROUND arrays, in the statement:
PARAMETER (NLG=.., NIG=.., NRG=.., NCG=..)
and for the data-for-GREX arrays in the statement:
PARAMETER(NLSG=.., NISG=.., NRSG=.., NCSG=.., NPNAM=..)
All of the parameters mentioned above also occur in the MAIN program of EARTH; if any of these are changed in the SATELLITE MAIN program, then identical changes must be made in the EARTH MAIN program. Similarly, the data-for-GROUND dimension parameters must be changed in subroutines GROUND and SATLIT and the DATA-for-GREX parameters in subroutine GREX3.
The following set of parameters is specified only in the SATELLITE MAIN program: MAXRUN, the maximum number of runs; NIPIL, NRPIL, NLPIL and NCPIL, the maximum numbers of PIL variables of types integer, real, logical and character, defaulted to .., .., .., and .., respectively.
The user may also wish to extend the dimensions of the SATELLITE F-array, by changing the following parameters:-
MAXTCV, which governs the size of the part of the array for storing information about boundary and other conditions associated with PATCHes;
MAXFRC, which governs the amount of storage for x, y, z and time- wise grid data; and
NBFC, which allocates storage for BFC grid data;
MAXFRC, which limits the combined size of the XFRAC, YFRAC, ZFRAC and TFRAC arrays.
The indices KTFR, KXFR, KYFR and KZFR in the SATEAR common block IDATA can be used in FORTRAN in SATLIT coding to locate values in the F-array corresponding to the PIL arrays TFRAC, XFRAC, YFRAC and ZFRAC. For instance, the value assigned to ZFRAC(I) through PIL is stored in F(KZFR+I).
A complete list of arrays that can be re-dimensioned, with their associated dimension-indicating parameters, is supplied in the table which concludes this sub-section.
The fourth column of the table indicates the corresponding array that appears in the MAIN program of EARTH, so that, if it is re-dimensioned in the MAIN program of the SATELLITE, it must also be re-dimensioned in the MAIN program of EARTH.
Once a change to the FORTRAN has been made, the SATLIT file must be re-compiled, and the SATELLITE task re-linked, for the changes to have effect. The same comment applies to any corresponding changes made to the MAIN program of EARTH.
Table
Notes
Array
name Dimension parameter Associated
EARTH array
F
NFDIM=MAXTCV+
MAXFRC+NBFC None
RUN MAXRUN= 500 None
* LG NLG= 20 LG
* IG NIG= 20 IG
* RG NRG= 100 RG
* CG NCG= 10 CG
LSGD NLSG= 20 LSGD
ISGD NISG= 20 ISGD
RSGD NRSG= 100 RSGD
CSGD NCSG= 10 CSGD
INDEC NIPIL= 45 None
INVAL " None
REDEC NRPIL= 45 None
REVAL " None
STACK NSTACK= 500 None
DBGPHI NUMPHI= 50 L5
ITERMS " I1
LITER " I2
I0RCVF " I3
I0RCVL " I4
ISLN " I5
IPRN " I6
NAME " IH1
DTFALS " R1
RESREF " R2
PRNDTL " R3
PRT " R4
ENDIT " R5
VARMIN " R6
VARMAX " R7
FIINIT " R8
PHINT " R9
CINT " R10
EX " R11
IP1 " IP1
IHP2 " IHP2
RVAL " RVAL
LVAL " LVAL
-----------------------------------
The following account is intended to assist those PHOENICS users who wish to insert coding into SATLIT, for example in order to read data from a file, or to make one set of data items depend upon others in complex ways, involving mathematical operations which PIL may not be able to handle as expeditiously as Fortran.
The listing of SATLIT can be viewed via POLIS/PHOENICS-2/Fortran.
Study of the SATLIT listing reveals that it consists mainly of a series of 24 groups of statements, beginning with a comment followed by a CONTINUE and one or more RETURNs. Which group is activated during execution at any time is controlled by a 'computed GO TO', just below the common blocks.
The titles of the groups are the same as those which are used in Q1 files, and which recur in GROUND and related files. No coding appears between the CONTINUEs and the RETURNs; for SATLIT is provided as an empty shell, into which the user can introduce whatever coding he desires.
The user should note the following important point: SATLIT is always called, during execution of the SATELLITE program, after the Q1 file has been processed, but before the interactive (TALK=T) session starts
The user can cause additional execution of the SATLIT, either in Q1 or interactively, by means of the command SATRUN(NAMSAT). This may be necessary when SATLIT coding makes reference to PIL variables. Once the coding has been inserted, it is the user's responsibility to arrange for compilation of the SATLIT, and its linking into the SATELLITE load module.
Examples of possible SATLIT coding are:-
LSWEEP can be set in SATLIT by the arithmetic statement: LSWEEP=integer and the arguments of OUTPUT can be set by a call to the OUTPUT subroutine thus: CALL OUTPUT(H1,Y,Y,Y,Y,N,N)
Further, where a Q1 file might contain the statements:
PATCH(PART1,INIVAL,1,10,1,10,1,10,1,1)
COVAL(PART1,U1,0.0,0.2)
the SATLIT equivalent is:
CALL PATCH('PART1',INIVAL,1,10,1,10,1,10,1,1)
CALL COVAL('PART1',U1,0.0,0.2)
The advantage of using SATLIT is the greater speed of execution of FORTRAN as compared with PIL; but this must be set against the additional time needed to recompile SATLIT and to relink the SATELLITE program each time a data change is made.
The amount of coding which the user introduces may be reduced, if he wishes, by the use of the 'service' subroutines. (See PHENC: SUBROUTINES).
PHOENICS subroutines which can be called from SATLIT and whose names match those of the equivalent PIL commands are:
CONPOR, COVAL, GRDPWR, OUTPUT, PATCH, RADIAT, SOLUTN, TERMS, TEXT,
the BFC routines SETPT etc, and those further ones referred to as "Service subroutines" in the PHENC entry: SUBROUTINES.
The arguments of these subroutines are to be entered in precisely the same way as are those of the corresponding commands in PIL. There are, however, some exceptions to this, in which case the differences are explained in the help entry for the relevant PIL command (in particular see CONPOR, PATCH and SETLIN). Also, since FORTRAN is being used, character data such as patch names must be in single quotation marks eg 'BAFFLE'.
STKJB sets the size of the in-core stack which is used to hold PIL instructions. If the stack is too short, instructions will page to disk, increasing the reponse time. If the stack is much too big, memory will be wasted.
In general, the stack should be able to accommodate the largest Q1 files expected. The stack is defaulted to... (see listing) to accommodate the PHOENICS Input Menu. If memory limitations preclude this, it may be reset to a smaller number by the procedure described below.
Subroutine ARRJB controls the total space available for user- declared arrays. The number of arrays is limited to 100, but the sums of their dimensions are controlled by the PARAMETERs: MXISP, MXRSP, MXCSP and MXLSP for integer, real character and logical arrays respectively. These are defaulted to ... (see listing).
Subroutine GEOSTK performs a similar function for the storage of graphics elements, such as lines and text, generated by the various PIL graphics commands. The PARAMETER MXGLIN, defaulted to ... (see listing), controls the number of line segments that can be displayed at one time. This may need to be increased when fine BFC grids are to be viewed in their entirety.
(see
SATRUN)(see NAMSAT)
wbs