2. The 1984 PIL

Preliminary remarks

The PHOENICS Input Language, here called PIL for short, is a simple language employed by the PHOENICS user for "conversing" with the SATELLITE program and for inserting instructions into Q1 files; and it is also used by EARTH for recording what instructions have been received, at the top of the RESULT file, when ECHO is set = T.

Like other languages, it is best learned by observation and practical exercise. However, the following summary will provide guidance as to what can most profitably be observed and practised; and the PHOENICS Encyclopaedia serves as a complete dictionary and grammar book.

PIL is a "command language"; and the various commands which it contains are best classified as:

• variable-setting commands,
• argument-setting commands,
• declaration commands,
• data-display commands,
• termination commands,
• information-seeking commands.

These will be discussed, in turn, below. Before this, however it will be explained how "comments", ie NON-commands can also be entered.

Introducing comments into Q1 files

Statements for interpretation by the SATELLITE must begin in the first or second columns, thus, either of the following TEXT commands will be interpreted by SATELLITE:

    column 
    1
     2

    TEXT(SIMULATION OF HEAT EXCHANGER) or
     TEXT(SIMULATION OF HEAT EXCHANGER)

PIL ignores all other statements. Thus:

           THIS IS Q1 OF 7 OCTOBER.

can be inserted as a useful comment in a Q1 file without its being noticed by SATELLITE except as something to be copied faithfully into the COPY file, because it does not start in the first or second column.

If, during interactive (TALK = T) working, the user forgets to return the cursor completely to the left before he enters a command, and therefore starts typing in column 3 or beyond, SATELLITE will take no notice of what he types.

The variable-setting commands of PIL

• Assignment statements of the type 'this = that' are recognised, if 'this' is one of the names recognised by PHOENICS, and if:
  1. for names of integer quantities, 'that' is an integer value or expression, eg:

     NX=25
     IPLTL=LSWEEP
     NY=NX/2
     or:

  2. for names of real quantities, 'that' is a floating-point quantity or expression, eg:

     RHO2=1.E3
     PRNDTL(H1)=0.7
     RHO1A=PRESS0**(-RHO1B)
     or:

  3. for names of logical variables, 'that' is T (ie true) or F (ie false), or another logical variable, or a logical expression, eg:

     ECHO=T
     PARAB=F
     YZPR=CARTES
     ONEPHS=ISLN(R2).EQ.1
     or:

• for names which are to be printed, 'that' is a string of (no more than) four characters, eg: NAME(14)=TEMP
• A recognised assignment statement, followed by a semi-colon preceding a second statement, results in both statements being attended to. Thus:

  RHO1=1.0; RHO2=1.E3

  will set both the first-phase and the second-phase densities.

The argument-setting commands of PIL

• Important information can be conveyed to PHOENICS by way of statements such as:

  command (argument 1, argument 2, argument 3, etc).

• Some argument-setting commands employ the arguments Y (for 'yes'), N (for 'no'), or P (for 'pass', ie use the current setting, whatever it is). Thus:

  SOLUTN(U1,Y,Y,N,N,N,N)

  informs the SATELLITE program that:

  • (first Y) storage is to be allocated to the variable U1;
  • (second Y) that it is to be solved for;
  • (the four N's) none of the other options are to be activated.
• Other argument-setting commands may have integer arguments, for example:

  PATCH(REGION1,INIVAL,1,4,2,8,1,10,1,1)

  which indicates that:

  • the first piece of regional information (argument 1) concerns
  • initial values (argument 2), for a region stretching from
  • the first to the fourth x-direction cell (arguments 3 and 4),
  • from the second to the eighth y-direction cell (arguments 5 & 6)
  • from the first to the tenth z-direction cell (arguments 7 & 8),
  • and at the first time step only (arguments 9 & 10).
• Yet other commands employ both integer and real arguments, such as:

  COVAL (REGION1,U1,0.0,3.2)

  the meaning of which can be learned by typing simply:

  COVAL?

  during an interactive session.

• The PIL-writer is free to introduce, on the right-hand side of any =, or in an argument location of a command, expressions involving certain arithmetic operators, namely: +, -, *, / and **.

  These operators have the same significances as in FORTRAN, ie they add, subtract, multiply, divide and exponentiate.

  He or she may also make use of the following arithmetic functions, all of which have the same significances as their Fortran counter-parts. With the exception of IABS, all take a single REAL argument and return a REAL value (implicit "floating" being performed on INTEGER arguments):

For example:

after:
REAL(XX,YY,ZZ); INTEGER(II,JJ): XX=4.0

YY=SQRT(XX)	is equivalent to	YY=2.0
YY=2*6+(4/LOG10(100)	is equivalent to	YY=14.0
ZZ=COS(0)	is equivalent to	ZZ=1.0
II=IABS(3)	is equivalent to	II=3

Declaration commands

• Users can enable SATELLITE to understand and work with variables which are not in its vocabulary by declaring them as reals or integers. Thus:

  REAL(windvel,angle)

  would allow SATELLITE to accept statements such as:

  angle=1.0; windvel=10.0*cos(angle); and

  INTEGER(extraswp)

  would permit use of statements such as:

  LSWEEP= LSWEEP + extraswp

• Further examples are:-

  REAL (DENSTY,WIDTH,POWER) INTEGER (NGRID)

  Unless subsequently assigned by the user, DENSTY, WIDTH and POWER default to 0.0; and NGRID to 0.
  Up to 150 integer and 300 real variables may be declared in this way; should more be needed, the corresponding arrays in the MAIN program of SATELLITE can be re-dimensioned.

• Further examples of the use of PIL-arithmetic, combined with the use of user-declared variables, now follow:

  REAL(DENSTY,WIDTH,POWER,GAM) INTEGER(NGRID) DENSITY=1.2; WIDTH=0.012; POWER=1.0
  GAM=1.2; NGRID=3; RH01=2.0*DENSTY; RH02=1000.0*RH01
  PRNDTL(VI)=PRNDTL(HI)*GAM
  NX=NY/2+1
  GRDPWR(Z,NGRID+3,6.0*WIDTH/2.0,POWER)
  PATCH(4,CELL,1,1,NY/2,NY,1,1,1,1)

  The coefficient 0.023 * rho * u * (rho*u*d/mu) ** (-0.2) which can arise in studies of turbulent pipe flow, might be set as follows:

  REAL(COEF,DIST,DENS,VELCTY,VIS RHOU) DIST=0.0254; DENS=1.2; VELCTY=4.2; VIS=1.E-5 RHOU=DENS*VELCTY COEF=.023*RHOU*(RHOU*DIST/VIS)**(-0.2)

• In interactive mode, users can display the real and integer variables which have been set by means of the commands:

  SEE R (or SEE REAL) SEE I (or SEE INTEGER)

The data-display commands of PIL

• If, during an interactive session, it is desired to learn what is the value of a single variable, typing it name will elicit its echo to the screen, with its current value. Thus, typing :

  LSWEEP 

  will cause to appear on the screen:

  Command>echo
  LSWEEP  = 100 

  or, rather, whatever is the current value.

• The same will be printed to the file satlog.txt. Moreover, if the line containing simply LSWEEP (or any other variable) is present in the q1, the same print-out to satlog.txt will occur, whether the satellite is being operated in interactive mode or not.

• Should the user wish to see the current values of all the variables, including the defaults, he or she should type:

  SEE

  This will exhibit on the screen, and print to satlog.txt, group-by-group, all the active variables, with their values.

• In order to 'SEE' the settings of a particular data-Group, 7 for example, the user should type:

  SEE7

  or

  SEE 7

  which gives information about what variables are solved for, or stored. Typing:

  SEE13

  correspondingly shows the entries of Group 13, which is concerned with boundary conditions and special sources.

• Settings can be changed at any time. Thus the screen may be displaying the settings appropriate to Data Group 23; yet the user may make a setting appropriate to Group 9 and have it immediately accepted, as can be checked by typing:

  SEE9

• Which variables are stored and solved can be displayed by typing:

  STORED

  and

  SOLVED

  respectively.

• Typing

  VARIABLES

  provides a list of the available field variables and their names, of which there are 50 by default (although this number can be indefinitely enlarged by making modifications to the main programs of the SATELLITE and EARTH).

• It is important to understand that SEE displays the interpreted values of the PIL commands, not the commands themselves. If it is the latter which it is desired to view, the PHOENICS EDITOR may be employed (see PHENC entry); alternatively, the View Q1 command can be activated from the top-level menu of SATELLITE.

The information-seeking commands of PIL

All help entries are placed in the POLIS Encyclopedia. Users wishing to know what a variable or command mean should look them in the alphabetical list. There are several ways of getting to the Encyclopaedia:

• Clicking the POLIS icon on the desktop
• Clicking 'Help, POLIS' on the VR-Editor menu bar
• Clicking or pressing F1 in the Satellite text-mode
• From within PHOENICS Commander

Termination commands of PIL

• The end of the interactive session is signalled by typing END; alternatively, typing ABORT will end it without copying the COPYQ1 into Q1 or writing an EARDAT file.
• In Q1-files, problem definitions are terminated by STOP.

wbs