Click below for Contents Lists.
Brief or extended
or on the right for a power-point presentation about In-Form.

Summary

• space and time discretization,
• material properties,
• initial values,
• sources,
• boundary conditions,
• body shapes and motions, or
• special print-out features.

The formulae are placed in the data-input file, Q1 by way of a text editor, or via the graphical user interface of PHOENICS, the Virtual-Reality Editor.

The PHOENICS input module, Satellite, thereafter transmits the implications of the formulae to the solver module, EARTH. There they are recognised as instructions to perform the appropriate computations. The user has nothing more to do except await and inspect the computed results.

Note to users of earlier versions of PHOENICS:

PLANT still exists and functions as before, for users who have become accustomed to it; but In-Form can now do all that PLANT can do, and more.

Moreover, In-Form not only greatly the range of admissible new-to-PHOENICS features: it also allows already existing features to be introduced in simpler ways. In particular, it renders unnecessary the use of GRNDx as an option indicator; and even the long-established COVAL command can often be replaced by a simpler statement.

Contents

Brief contents list

1. Why In-Form has been created
2. Introduction: settings; statements; formulae; objects
3. Grid specification
4. Material properties in general
5. Auxiliary variables
6. Initial values
7. Sources and boundary conditions
8. Moving objects
9. Print-out-related capabilities
10. Replacing READQ1
11. In-Form and the VR-Editor
12. Adjustment of terms in differential equations
13. The use of In-Form with parallel PHOENICS

• Appendix 1: In-Form functions
• Appendix 2: In-Form statements
• Appendix 3: In-Form options
• Appendix 4: In-Form operands

Extended contents list

1. Why In-Form has been created
   1. PIL, GROUND coding and PLANT
   2. The new capabilities supplied by In-Form
   3. How In-Form works
2. Introduction to In-Form
   1. The setting of density, as an example
      1. The PIL method
      2. The In-Form alternative
      3. Answers to initial questions about In-Form
      4. What has appeared in Q1EAR and EARDAT
   2. The In-Form Statement
      1. General description
      2. Keywords
      3. Pre-formula conditions; 'at'
      4. The formula
      5. Post-formula options; 'with' and 'if'
   3. Allowable formulae
      1. General description
      2. Operators
      3. Functions
      4. Operands
      5. Further examples
   4. In-Form Objects
      1. Definition
      2. The basic cell-enclosing (i.e. volumetric) shapes
      3. The basic cell-cutting (i.e. sub-grid) shapes
      4. Shapes made by restricting the PATCH size
      5. Shapes made by using non-constant parameters
      6. Shapes made by adding and subtracting
      7. 'Negative' objects
      8. Positions varying with time
      9. Shapes varying with time
3. Grid specification
   1. Time discretization
   2. Geometric grids for parabolic flows
4. Material properties in general
   1. The PROPERTY keyword
   2. Individual properties
      • RHO1 DRH1DP RHO2 DRH2DP
      • ENUT ENUL PRNDTL PHINT TMP1 TMP2 EL1 EL2
      • CP1 CP2 DVO1DT DVO2DT
      • CFIPS CMDOT CINT CVM
   3. Further examples
   4. Choosing a fluid
5. Auxiliary variables
   1. Whole-field, for viewing and post-processing
   2. Whole-field, for participation in the calculation
   3. Other (MAKE, STORE1)
6. Initial values
   1. The INITIAL keyword
   2. Initial values for patches
   3. Initial values for VR-objects
   4. Initial values for In-Form objects
7. Sources and boundary conditions
   1. The SOURCE keyword
   2. Sources for patches
      1. Sources of scalar quantities
      2. Mass sources
      3. Momentum sources
      4. Other sources
   3. Sources for VR-objects
      1. Sources of scalar quantities
      2. Mass sources
      3. Momentum sources
      4. Other sources
   4. Sources for In-Form objects
      1. Sources of scalar quantities
      2. Mass sources
      3. Momentum sources
      4. Other sources
   5. Sources for Sub-Grid objects
      1. Syntax
      2. Momentum sources
      3. Heat flux
   6. The COVAL function
      1. Syntax
      2. Sources of scalar quantities
      3. Mass sources
      4. Momentum sources
8. Moving objects
   1. Distinction between VR and In-Form objects
   2. VR objects
   3. In-Form objects
9. Print-out-related capabilities
   1. The LONGNAME keyword
   2. The PRINT keyword
   3. Coefficients, residuals, corrections and exchange coefficients (gammas)
   4. Eliciting debug
10. Replacing READQ1
11. In-Form and the VR-Editor
12. Adjustment of terms in differential equations
    1. How to modify diffusion and convection terms
    2. How to modify built-in source terms
13. The use of In-Form with parallel PHOENICS
    1. Relevant features of parallel PHOENICS
    2. In-Form statements which can be used
    3. In-Form statements which can not yet be used

• Appendix 1: In-Form functions
• Appendix 2: In-Form statements
• Appendix 3: In-Form options
• Appendix 4: In-Form operands

1. Why In-Form has been created

1.1 Pre-In-Form methods of specifying flow-simulation tasks

1.1 PIL, GROUND coding and PLANT

1. by writing PHOENICS-Input-Language (PIL) statements in a Q1 file, so as to activate selected built-in features of the solver module, EARTH; this was always used, whether the Q1 was created by:
   • selection from a library of such files,
   • use of a text editor,
   • use of the Graphical User Interface, or
   • some combination of the above three;

2. by providing additional problem-specific Fortran-code modules, the so-called 'GROUND coding', which could be compiled and linked into a new EARTH executable;

3. by adding supplementary PLANT-activating statements to the Q1 file, which caused appropriate new Fortran to be written automatically, where after the new executable was created and run.

Method 1 has sufficed for the majority of users for most of their requirements, not least because the standard solver module is richly endowed with already-prepared GROUND-type sub-routines which can be switched on or off by pointers (the GRNDx flags) placed in Q1.

However, it is impossible to provide sufficient of these to satisfy all the needs which users may at some time express; therefore methods 2 or 3 have been extensively and successfully employed by many users throughout the years. Besides, keeping track of what all the GRNDx pointers mean is rather tiresome.

Method 2, of course, is accessible only to users with sufficient knowledge of Fortran, and the leisure to exploit it.

Method 3 requires no such knowledge; so it can be used by a wider circle of users. Nevertheless, like Method 2, it does necessitate the possession of a re-compilable version of PHOENICS, and of a compiler, both of which entail extra expense.

This is why In-Form has been introduced. It provides:

• the unlimited extensibility of simulation power which GROUND and PLANT were designed to supply; but
• it does so with the standard executable, and so necessitates neither new coding, nor compilation, nor new executable.

1.2 The new capabilities supplied by In-Form

• In-Form has thus been created in order to provide the advantages of PLANT without the disadvantages. Specifically, the expressions placed in the Q1 file are now transmitted directly to EARTH; and EARTH has been equipped to interpret and work with them.

• Moreover, the syntax of an In-Form expression, for a given requirement, is easier to read and write than that of the corresponding PLANT one.

• Further, In-Form statements can do what was never possible for PLANT, namely apply initial values, sources and other attributes including those of motion, to Virtual-Reality objects.

• Finally, pre-In-Form PIL-using practices which were satisfactory but clumsy, for example the long-established practice of using GRNDx pointers, can be replaced and generalised by easier-to-understand In-Form equivalents.

1.3 How In-Form works

1. In-Form statements placed in the Q1 file have the typical form:

   (keyword what_where_when_indicators formula optional_conditions)

   English words such as 'at', 'of', 'is' and 'with' appear as meaningful separators.

2. There are only a few keywords, of which 'initial', 'property', 'source' and 'stored' are the most commonly used. A full list if supplied in section 2.2b .

3. The what_where_when items indicate, for example, to what VR-object and to what solved-for variable, the formula is to be applied.

4. The user's main concern is therefore to understand the syntax of In-Form sufficiently for the statement both to be accepted by PHOENICS and to express his or her intentions.

Users do not need, but may be interested, to know what SATELLITE does when it has read the statement. This is as follows:

• SATELLITE first subjects the statement to some legality checks; then, if satisfied, it creates a corresponding special-data (i.e. SPEDAT) statement of character-string type; this is passed to EARTH, via EARDAT, in the usual way.

• When EARTH begins execution, its first task is to read the SPEDATs and convert them, if it can, into instructions (to itself) to perform the corresponding mathematical operations.

• If it cannot, because of some illegality in the setting which SATELLITE could not detect, it will report what error it has found.

• Unless there is an error, little of this is visible to the user. However, the SPEDATs are written into, and can be inspected in, the files Q1EAR, EARDAT and (if accepted by EARTH) in RESULT also. To look at these files may be useful when all has not proceeded as expected.

Back to main contents

2. Introduction to In-Form

1. The setting of density, as an example
2. The In-Form Statement
3. Allowable formulae
4. In-Form Objects

2.1 The setting of density, as an example

a. The PIL method

The line in Q1:
RHO1 = 1.189
sets its value to a constant, namely that of 1-atmosphere 20-degree-Celsius air.

If some other setting is needed the Encyclopaedia article on RHO1 shows how alternative settings may be made.

For example, the setting:
RHO1=GRND1
leads to four options, the selection from which is effected by ascribing values to one or more of the PIL variables: RHO1A, RHO1B, RHO1C, IBUOYA, IBUOYB etc.

Further opportunities are opened by the settings: RHO1=GRND2
RHO1=GRND3
until
RHO1=GRND10

The choice is thus rich, if somewhat bewildering; but, inevitably, it is still limited.

The dialog boxes of the PHOENICS Graphical User Interface, of course, are designed to reduce the bewilderment, by presenting the alternatives in a systematic way; but they can do nothing to overcome the limitations.

b. The In-Form alternative

• The In-form equivalent of the first of the above settings is:
  (property RHO1 is 1.189)
  the meaning of which is obvious enough.

• Let us now consider the first of the GRND1 options, which the Encyclopaedia states to be:
  RHO1 = RHO1 + RHO1B * H1
  where RHO1A and RHO1B are constants to be set in the Q1 file, and H1 is the first-phase enthalpy which, it is supposed, is a solved-for variable.

  Let its definition be such that H1 is zero at 20 degrees Celsius.

  This option might be selected if one were seeking to represent the dependence on temperature of the density of atmospheric pressure air, which is most naturally expressed as:
  RHO1 = 1.189 * [ 1.0 + H1 / ( 1005.0 * 293.0 ) ]
  wherein:
  1005.0 is the constant-pressure specific heat of air, and
  293.0 is the absolute temperature corresponding to 20 degrees Celsius.

  Of course, RHO1A and RHO1B have to be calculated as 1.0 and 1.0/(1005.0*293.0) respectively.

• The In-Form equivalent of the above setting is simply:
  (PROPERTY RHO1 IS 1.189*(1.0 + H1/(1005.0*293.0)))

  This is easily written and easily understood; and its writer needs to make no visit to the Encyclopaedia in order to check that the right GRND number has been chosen.

  In-Form thus allows users to express their requirements in a natural manner.

• Moreover, if the user, enlarging his demands, wished to take into account a quadratic dependence of density on temperature, he would not need to search the Encyclopaedia for that option (which he would not find, as it happens).

  Instead he could simply extend his formula thus:
  (property RHO1 is 1.189*(1.0 + H1/(1005.0*293.0) + 1.e-6*H1^2))

  [Here 1.e-6 is just an example, of course; any value could be used. The ^ is the In-Form symbol for exponentiation.]

• Thus the word 'alternative' in the above title is an In-Form-underestimating misnomer; for In-Form, as well as providing an alternative way of doing what PIL can do, does also much that PIL can not.

c. Answers to initial questions about In-Form

• Both upper- and lower-case characters have appeared in the above In-Form statements. Is this significant?

  No. The Satellite converts all characters to upper-case before processing them. Some users prefer to place the In-Form-specific words 'property' and 'is' in lower case, and the ones which they have introduced (here 'RHO1' and 'H1') in upper case. Or they may use the opposite rule; or none at all. It is their choice.

• If the formula became very long, the 68-character limit to Q1-file lines would be exceeded. What then?

  Insertion of a $ sign in or before the 68th column will be interpreted by SATELLITE as an append-next-line command; so In-Form statements consisting of two lines (but no more) are allowed. However, if the formula is so long as to exceed this limit, it is necessary to construct it out of several smaller parts, as shown here.

• All constants in the above examples have appeared in numerical form. Can symbols be employed?

  Yes. For example the PIL variable RHO1A could be introduced in place of the 1.189 of the formulae, if the setting:
  RHO1A=1.189 preceded the In-Form statement thus:
  (property RHO1 is RHO1A)

• We have seen a keyword (property) and some formulae; and we suppose that RHO1 is a what_when_where example. What about showing some conditions?

  Good question! The answer will be provided in section 2.2 .

• Three ways of setting the value of RHO1 have been described. Suppose that all three were included in the Q1 file; would the information about all three be transmitted to EARTH? And which one would be used to define the density?

  The answer is that all three specifications would be transmitted to and processed by EARTH; but it is only the last to appear in the Q1 which would actually be used for the flow-simulating calculation.

• The SATELLITE ordinarily gives RHO1 the default value 1.0 before the Q1 is read; so this is presumably superseded by the In-Form specification. Suppose however that a PIL statement appeared in the Q1 after, i.e. below, the In-Form statement(s). Would this supersede the latter?

  The answer is negative: it is in EARTH that the decision is made; and it is always the In-Form statements EARTH which chooses to follow.

  The reader may care to check these statements by running PHOENICS with the following Q1:

  TALK=f;RUN(1,1)
  store(rho1)
  (property rho1 is 1.0)
  (property rho1 is 2.0)
  (property rho1 is 3.0)
  rho1=4.0
  STOP
  

  The RESULT file will show RHO1=4.0 in the GROUP 9 print-out; but the field print-out will show RHO1 to be 3.0.

  It will also carry the printed line: "Formula used for setting RHO1" .

d. What has appeared in Q1EAR and EARDAT

New users will find it helpful to inspect the Encyclopaedia article on SPEDAT first.

• The first setting (namely of RHO1 to 1.189) leads to:

   SPEDAT(SET,PROPERTY,RHO1,C,=1.189)

  in Q1EAR ( and later in RESULT),

  wherein the 'C,' is a reminder that what follows it must be treated as a character string.

  The solver module, EARTH, does not read this however. It reads instead the EARDAT file, where the corresponding entry is:

  PROPERTY  RHO1           C=1.189 

• The second setting (of RHO1 as linear in H1) places:

  SPEDAT(SET,PROPERTY,RHO1,C,=1.189*(1.0+H1/(1005.0*293.0)))

  in Q1EAR, and

  PROPERTY  RHO1           C=1.189*(1.0+H1/(1005.0*293.0))

  in EARDAT.

• The third setting (of RHO1 as quadratic in H1) places:

  SPEDAT(SET,PROPERTY,RHO1,C,=1.189*(1.0+H1/(1005.0*293.0)+1.E$)
  SPEDAT(SET,PROPERTY,RHO1,C,-6*H1^2))

  in Q1EAR, and

  PROPERTY  RHO1           C=1.189*(1.0+H1/(1005.0*293.0)+1.E$
  PROPERTY  RHO1           C-6*H1^2)

  in EARDAT.

The following comments are appropriate:

• The entries in spedat and eardat are a little harder to read than the original statements, but not much.
• The line-break ($) sign is placed somewhat differently; but otherwise spedat and eardat reproduce faithfully the character strings in the originals.
• The SATELLITE (which wrote Q1EAR and EARDAT) performed no numerical evaluations, for example of 1005.0*293.0, leaving EARTH to do so later.
• The reader is reminded that there is no necessity to inspect Q1EAR or EARDAT, which can be regarded as belonging to transactions which are internal to PHOENICS.

2.2 The In-Form statement

1. General description
2. Keywords
3. Pre-formula conditions; 'at'
4. The formula
5. Post-formula options; 'with' and 'if'

a. General description

This will now be explained, under the headings:

• keywords
• pre-formula conditions, i.e. what_where_when_indicators
• the formula, containing the expression to be evaluated by the solver
• post-formula options, i.e. optional_conditions

It should be noted that:

• The opening and closing brackets of the statement must always be present.
• The opening bracket must start in the first or second column.
• Lines must not extend beyond the 68th column; but a dollar sign, $, in or before the 68th column will be taken as an append-next-line instruction.
• Lines can contain symbols, specifically any of the following symbols: .0123456789+-*/^()&%ABCDEFGHIJKLMNOPQRSTUVWXYZ[]{}'_# but no others.
• Characters may be upper- or lower-case without consequences.
• Blank spaces separate the items, several successive spaces having the same effect as one.

See also Appendix 2 for a succinct summary of In-Form-statement features, in which it will be seen (from the appearance of [] brackets, which items may be dispensed with).

b. Keywords

• PROPERTY: This has already been encountered in section 2.1. It will be explained in connection with all material properties used by PHOENICS in section 4.

• STORED: This keyword is used for the creation of auxiliary variables which can have distinct values for each cell in the domain.

  Such variables are of two main kinds, namely:

  • those which are used only for post-processing purposes, as when exact solutions are computed for comparison with the numerically-derived values: and
  • those which require to be updated continually during the computations because their values influence how the computation proceeds.

  These will be discussed in section 5.

• MAKE: This keyword is also concerned with the creation of auxiliary variables but of lesser dimensionality. It is also discussed in section 5.

• STORE1: This keyword concerns what is to be done with single auxiliary variables introduced by MAKE. It is also discussed in section 5.

• INITIAL: This is concerned with the setting of initial values of solved-for or auxiliary values. Initial values can be set for:
  • the whole domain,
  • for limited volumes defined by patches (i.e. those of which the 'bounding boxes' are aligned with the computational grid)
  • for limited volumes defined by faceted objects (i.e. those of which the 'bounding boxes' are not wholly aligned with the computational grid)
  • for limited volumes defined by 'In-Form objects' the shapes and positions of which are defined by formulae.

  This keyword is discussed in section 6.

• INFOB: As its name suggests, this keyword indicates that the position and shape of an 'In-Form object' are to be defined. It also is discussed in section 6.

• SOURCE: This extremely important keyword, the subject of section 7. is used for introducing formulae defining the sources of mass, momentum, energy and other conserved properties.

  In accordance with the usual PHOENICS practices, boundary conditions are also introduced by its means.

  Sources may, like initial values, be applied to the whole domain or to variously-defined limited spaces.

• MOVOB: This keyword represents In-Form's contribution to MOFOR, the moving-frame-of-reference feature of PHOENICS.

  As originally introduced, the motion of objects had to be specified by way of a .bvh (later .mof) file. Whereas this was necessary and convenient for complex motions of articulated objects such as the 'dancing man', it was over-complicated for others, for which formulae suffice.

  The MOVOB keyword, discussed in section 8.1, makes this possible, indeed easy.

• TGRID, XGRID, YGRID, ZGRID: These four keywords, concerned with the specification of time intervals for transient calculations, and of longitudinal-distance interval and lateral grid expansion or contraction in steady parabolic flows, are discussed together in section 3.

• PRINT and LONGNAME: In-Form has greatly extended the ability of the user to print useful and easily-understandable information, whether to the RESULT file or to a special one called INFOROUT. The relevant keywords are explained in section 9.

• REALREAD, INTREAD, LOGREAD: These keywords provide the opportunity to convey to EARTH more information than SPEDAT can. It is described in section 10.

c. Pre-formula conditions; 'var', 'at'

'var', the 'what' indicator

Here RHO1 is of the 'what_where_when' kind, and specifically 'what': it says: 'this formula applies to the variable with name RHO1' and, by implication, to no other. It can thus be regarded as a pre-formula condition.

As it happens the words: 'of RHO1 is', or 'var RHO1 is' would have had the same effect; but, since the 'of' and 'var' add little to the understandability of the statement, they are best omitted.

The word 'is' is a signal that the formula follows. It must not be omitted.

'at', the 'where_when' indicator applied to a patch

An example of a Q1 file which defines density differently for each of four different patches (SW, NW, NE, SW) now follows.

    #249
   case 249 (square cavity with moving lid) has now been loaded
 STORE(RHO1)  ! in order that PHOTON will be able to display it
              ! now declare the patches to which 'at' can refer.
 PATCH(SW,CELL,1,NX/2,1,NY/2,1,1,1,1)       ! south-west quadrant
 (property RHO1 at SW is 2.0)

 PATCH(NW,CELL,1,NX/2,NY/2+1,NY,1,1,1,1)    ! north-west quadrant
 (property RHO1 at NW is 3.0)

 PATCH(NE,CELL,NX/2+1,NX,NY/2+1,NY,1,1,1,1) ! north-east quadrant
 (property RHO1 at NE is 4.0)

 PATCH(SE,CELL,NX/2+1,NX,1,NY/2,1,1,1,1)    ! south-east quadrant
 (property RHO1 at SE is 5.0) 

The result is as shown (with the smearing engendered by the very-coarse grid) in the following PHOTON plot.

Readers interested in the transmission details may like to know that the relevant EARDAT contains the lines:

    PROPERTY  RHO1!SW        C=2.0
    PROPERTY  RHO1!NW        C=3.0
    PROPERTY  RHO1!NE        C=4.0
    PROPERTY  RHO1!SE        C=5.0

the corresponding lines in the Q1EAR and RESULT files are:

    SPEDAT(SET,PROPERTY,RHO1!SW,C,=2.0)
    SPEDAT(SET,PROPERTY,RHO1!NW,C,=3.0)
    SPEDAT(SET,PROPERTY,RHO1!NE,C,=4.0)
    SPEDAT(SET,PROPERTY,RHO1!SE,C,=5.0) 

The same with more complex formulae

However, INIVAL patches allow only uniform (or linear in x or y or z, via LINVLX, LINVLY and LINVLZ) values to be set, whereas In-Form can set any non-uniform ones which can be described by formulae, for example:

    (property rho1 at sw is 100*(xg + yg))
    (property rho1 at nw is 1.0 + 1.e-1*(u1+v1))
    (property rho1 at ne is 10.0 + 0.0001*p1/h1)
    (property rho1 at se is 5.0+0.1*((xg)^2 + (yg)^2)) 

[It should be noted, however, that the ability to set density freely in this manner does not signify that the setting makes physical sense, or that a converged solution will be obtained.]

A 'when' example

In association with In-Form SOURCE settings which depend upon the PRPS value, to be described below, the fluid is set in motion as seen here.

'at', the 'where_when' indicator, applied to a faceted object

Input-Library case 764 shows how the viscosity can be set at different values according to whether the cell in question lies inside or outside a sphere defined by way of facets.

The sphere object is of course that defined by the line:
> OBJ, NAME, SPHERE
near the bottom of the Q1 file.

The resulting viscosity distribution is here shown in a VR-Viewer contour plot.

Further scrutiny of the Q1 file for case 764 reveals the 'at' condition in use also for statements with the keywords PROPERTY, INITIAL, STORED and SOURCE,in each case showing that the formula is to be applied to the sphere. Evidently it is very versatile.

A question of order

This appeared natural, and conducive to orderly thought; but was it necessary?

In case 764, the lines with 'at sphere' all appear above the line which defines the sphere object. This suggests that the patch-first-at-later principle may not a necessity; and the suggestion can be proved to be correct by running the following Q1:

#249
   case 249 (square cavity with moving lid) has now been loaded
 STORE(RHO1)  ! in order that PHOTON will be able to display it
              ! now declare the patches to which 'at' can refer.
 (property RHO1 at SW is 2.0)
 (property RHO1 at NW is 3.0)
 (property RHO1 at NE is 4.0)
 (property RHO1 at SE is 5.0)
 PATCH(SW,CELL,1,NX/2,1,NY/2,1,1,1,1)       ! south-west quadrant
 PATCH(NW,CELL,1,NX/2,NY/2+1,NY,1,1,1,1)    ! north-west quadrant
 PATCH(NE,CELL,NX/2+1,NX,NY/2+1,NY,1,1,1,1) ! north-east quadrant
 PATCH(SE,CELL,NX/2+1,NX,1,NY/2,1,1,1,1)    ! south-east quadrant

The patch-first-at-later prescription is a good rule to follow; but it is not required by In-Form.

d. The formula

• Suppose that one wished to specify the density as proportional to the inverse square of the distance from the origin of the coordinate system.

  Then any algebraically-literate person would recognise this as being expressed symbolically, with x, y and z as the Cartesian coordinates, by:

  density = 1 / ( x**2 + y**2 + z**2 )**0.5

  with ** signifying exponentiation.

  This is (almost) exactly how it is expressed in an In-Form statement, which might be:
  (property RHO1 is 1/(XG^2 + YG^2 + ZG^2)^0.5)

  wherein xg, yg and zg denote the Cartesian coordinates of the cell centres, and ^ replaces ** as the exponentiation sign.

• If the distances were to be measured not from the origin but from some point with coordinates x0,y0,z0, these values would need to be declared in the Q1 file, and given some values, for example by:
  REAL(X0,Y0,Z0)
  X0=1.2; Y0=2.2; Z0=3.3

  Then the formula could be expressed as:
  1/((XG-X0)^2 + (YG-Y0)^2 + (ZG-Z0)^2)^0.5

• This is still easy to read; but, if the pre-formula and post-formula options were at all extensive, the In-Form statement would have more than one line; then ease of reading would be diminished.

  It is therefore useful to recognise that PIL is flexible enough to allow the formula to be built up in stages, each one being brief enough be easily understood.

• For example, one might declare and define the character variables XDSQ, YDSQ and ZDSQ thus:
  CHAR(XDSG,YDSQ,ZDSQ)
  XDSQ=(XG-X0)^2
  YDSQ=(YG-Y0)^2
  ZDSQ=(ZG-Z0)^2

  Then the formula could be abbreviated to:
  1/(:XDSQ: + :YDSQ: + :ZDSQ:)^0.5

  wherein the colons signify that, because XDSQ etc are character variables, they must be evaluated as soon as read by SATELLITE.

• Finally, one might decide to declare and define the character variable FORM thus:
  CHAR(FORM)
  FORM=1/(:XDSQ: + :YDSQ: + :ZDSQ:)^0.5

  whereupon the whole In-Form statement would be reduced to:
  (property RHO1 is :FORM:)

• The equivalence of all these statements can be tested by running PHOENICS from the following Q1 file, which contains all four of the above specifications:

  talk=t;run(1,1)
  store(rho1)
  nx=50;ny=50;nz=50
  xulast=2.4;yvlast=4.4;zwlast=6.6
  #unigrid
    inform9begin
  REAL(X0,Y0,Z0)
  X0=1.2; Y0=2.2; Z0=3.3
    Case 1
  (property of RHO1 is 1/((XG-X0)^2 + (YG-Y0)^2 + (ZG-Z0)^2)^0.5)
    Case 2
  CHAR(XDSQ,YDSQ,ZDSQ)
  XDSQ=(XG-X0)^2
  YDSQ=(YG-Y0)^2
  ZDSQ=(ZG-Z0)^2
  (property of RHO1 is 1/(:XDSQ: + :YDSQ: + :ZDSQ:)^0.50
    Case 3
  CHAR(FORM)
  FORM=1/(:XDSQ: + :YDSQ: + :ZDSQ:)^0.5 ! colons are needed here too
        FORM=1/(XDSQ + YDSQ + ZDSQ)^0.5 ! This would be incorrect
  (property of RHO1 is :FORM:)
    inform9end

  If Group 19 of the RESULT file is examined, it will be seen that all four of the formulae have been converted into identical SPEDAT lines; and the VR-Viewer plot shown here indicates (qualitatively) that the resulting density field is as expected.

• A comprehensive discussion of the many types of formulae allowed by In-Form is given in section 2.3 below. The present preliminary discussion, now concluded, has been inserted so as to make clear that even the most complex formulae, of which several will be shown below, can be broken into more easily digested fragments.

e. Post-formula options; 'with', '!', 'if' and 'infob'

Keyword-specific options will be dealt with keyword-by-keyword in section 4. However there are three which apply to many keywords, being characterised by IMAT, IF and INFOB.

These will be dealt with, in order, here.

Limitation to a particular material by use of 'with IMAT' etc

• It is possible to limit the action of a formula to those locations at which the material-property index, IMAT (alias PRPS), has a specific value.

• Core-library case 756, for example, uses this technique so as to apply a momentum source only to those cells, within the space occupied by the associated patch, in which the material-designating property PRPS (alias IMAT), is in excess of a prescribed value (namely 100).

  The flow is transient; so this is a 'when' as well as a 'where' condition.

  'with IMAT>=100.0' is what appears in the In-Form statement in question.

• The complete set of 'with IMAT' conditions allowable in In-Form statements is:

  'with IMAT>value'

  means 'for PRPS greater than value'

  'with IMAT<value'

  means 'for PRPS less than value'

  'with IMAT>=value'

  means 'for PRPS greater than or equal to value'

  'with IMAT<=value'

  means 'for PRPS less than or equal to value'

  'with IMAT=value'

  means 'for PRPS equal to value'

  'with IMAT!=value'

  means 'for PRPS not equal to value'

EARDAT manifestations; the use of '!'

(SOURCE of U1 at I is 1.E5*(VEL*(YIC-YG)-U1) with IMAT>=100!LINE)
(SOURCE of V1 at I is 1.E5*(VEL*(XG-XIC)-V1) with IMAT>=100!LINE)

 SOURCE U1!I  C=1.E5*(7.8540E-01*(10-YG)-U1)!IMAT>=100!LINE
 SOURCE V1!I  C=1.E5*(7.8540E-01*(XG-10)-V1)!IMAT>=100!LINE 

Evidently the ' with ' has been replaced by an exclamation mark.

Consider now the '!LINE' which follows 100 in both the In-Form statements and their EARDAT counterparts. The following needs to be noted:

1. LINE is a further post-formula option, applicable only to the 'source' keyword;
2. its meaning is 'linearize the source', i.e. express it as:
   constant1*(constant2 - the as-yet-unknown value of the dependent variable in the cell in question);
3. despite the apparent equivalence of ' with ' and '!', substitution of the former for the latter in this In-Form statement is not allowed;
4. it can be concluded that, although several post-formula options can be applied simultaneously, only the first can be preceded by a ' with ', and the following ones must be separated by exclamation marks.

Other variables than PRPS can be used in a similar way. Thus, it is possible to:

• define a new whole-field-stored "MARK" variable;
• use In-Form to ascribe values for it over the whole field;
• ascribe to density one value where (and when) the marker exceeds a prescribed value, and another when it falls below the prescribed value.

IF

Another generally-applicable post-formula option is the "IF( condition)" construct, wherein condition can be a Fortran-like expression, as exemplified in library cases:

• 776, in connection with the ZGRID keyword;
• 777, in connection with the YGRID keyword;
• 778, in connection with the STORE1 keyword;
• 779, in connection with the SOURCE keyword;
• 781, in connection with the STORED keyword;
• 783, in connection with the several keywords;
• 785, in conjunction with INFOB; and
• 786, in connection with the SOURCE keyword;

It should be noted that either ' with ' or '!' must always precede the 'IF'.

INFOB_N

This value is usually 1, 2, 3 or other integer. Then the post-formula option 'with INFOB_BALL', say, signifies that the formula is to be applied to cells where MARK has the value 2 (strictly 2.0, because 'real' values are in question).

Library case 768 illustrates its use.

Specifically, 'with INFOB_1' will be seen to modify

• INITIAL of MARK, and
• SOURCE of TEM1; while
• 'with LINE!INFOB_1' will be seen to modify SOURCEs of U1,V1 and W1.

It should be noted that it is no longer necessary, as it was when case 768 was created, that 'INFOB_' should be followed by a numeral. Now any string of characters can be used, as in 'BALL' above.

It may be asked why, since this condition is of the 'what_where_when' variety, it is not among the 'pre-formula' options. The answer is that 'at' has already been used for a different purpose; for an In-Form object itself requires to be 'localised', which is why 'at PATCH1' appears in each of the In-Form statements in question.

2.3 Allowable formulae

Contents

• General description
• Operators
• Functions
• Operands
• Further examples

a. General description

No significance attaches to whether upper- or lower-case characters are used.

b. Operators

• = + - * / ( ) , all of which have their usual significances; and
• ^, which represents exponentiation, thereby replacing the ** of Fortran;

c. Functions

The syntax of all In-Form functions corresponds to Fortran. At first the function name is specified. Further in brackets the its arguments follow separated from each other by commas (or ampersands).

Note: When written in the Q1EAR, EARDAT and RESULT files, only ampersands appear; but commas are preferable in Q1 files, because they are easier to read.

In general case arguments of many functions can be the formulas containing constants and names of solved, stored and user-defined variables or any variables from list in Appendix 4: In-Form operands . Except for some functions of which will be commented specially below.

The functions, listed in alphabetical order in Appendix 1, are as follows:

conventional mathematical functions:

• ABS(), ACOS(), ASIN(), ATAN(), COS(), COSH(), EXP(), MAX(), MIN(), MOD(), SIN(), SINH(), SQRT(), TAN(), TANH(), which have their Fortran significances, except that it should be noted that:
  • MAX() and MIN() operate on real values, thereby replacing the AMAX1() and AMIN1() of Fortran;
  • MOD() returns a real or integer value, depending on the type of the target variable.

• LOGE() which stands for the natural logarithm, with base e;

• LOG10() which stands for the Napierian logarithm, with base 10.0 .

• Special mathematical function ARR() for calculation of "Arrhenius" value from next formulae

    EXP(arg1/(R*T))

  where R is the universal gas constant = 8314.31, T is the absolute temperature and arg1 is a formula.

The mathematical functions can be used in any In-Form statements. In general case their arguments can be the formulas containing constants and names of any variables.

The examples of use are specified in Appendix 1: In-Form functions .

formula-name functions:

• POL2(), POL3(), POL4(), POL5(), POL6(), which signify that a polynomial of the appropriate order is to be used. These functions are used usually for calculation stored or solved variables in (STORED or (PROPERTY statements.

  Syntax of POLx()

  POLx is followed by a bracket, then the name of the variable in question, then a comma or ampersand (i.e. , or &) followed by the requisite number, separated by further commas (or ampersands).

  Thus:

  POL2(x , a0 , a1 , a2)

  signifies a0+x*(a1+x*a2)

  POL3(x , a0 , a1 , a2 , a3)

  signifies a0+x*(a1+x*(a2+x*a3))

  POL4(x , a0 , a1 , a2 , a3 , a4)

  signifies a0+x*(a1+x*(a2+x*(a3+x*a4)))

  POL5(x , a0 , a1 , a2 , a3 , a4 , a5)

  signifies a0+x*(a1+x*(a2+x*(a3+x*(a4+x*a5))))

  POL6(x , a0 , a1 , a2 , a3 , a4 , a5 , a6)

  signifies a0+x*(a1+x*(a2+x*(a3+x*(a4+x*(a5+x*a6)))))

  where:
  • x may be a constant or a solved/stored variable, but
  • a0, a1, a2, etc must be constants.

  Examples of use of polynomial functions are to be found in library cases:
  701 for POL3(); 345 for POL4(); 089 for POL6() and POL5(), whereby it may be remarked that the practice of case 345, in which the coefficients are declared and allocated before being placed as symbols in the In-Form statement, is preferable from the view-point of clarity.

• PWL3(), which signifies a piece-wise-linear function, with three parts.

  Syntax of PWL3()

  The syntax of PWL3() is similarly constructed. Thus, PWL3 is followed by a bracket, then the name of the variable in question, followed by a comma or an ampersand.

  Thereafter follow pairs of numbers, of which the first is the abscissa and the second is the corresponding ordinate, thus:

  PWL3(x , x0 , y0 , x1 , y1 , x2 , y2 , x3 , y3 )

  represents y as a function of x consisting of straight lines which pass through
  (x0,y0), (x1,y1), (x2,y3), (x3,y3). Here x may be a constant or a solved/stored variable and x0 , y0 , x1 , y1 , x2 , y2 , x3 , y3 are constants.

  Library case 763 illustrates the use of this function. It enables different formulae for setting each of four fluid properties to be compared.

  It calculates the four relevant properties of the fluid (ethylene glycol) in four different ways, namely by way of:

  • the polynomial formulae in macro 089,
  • three-part patchwise linear formulae,
  • five-point cubic-spline formulae, and
  • multi-part piece-wise linear formulae.

• SPL5(), which signifies a cubic-interpolation spline function passing through five points.

  Syntax of SPL5()

  The syntax of SPL5() is similarly constructed. Thus, SPL5 is followed by a bracket, then the name of the variable in question, followed by a comma or an ampersand.

  Thereafter follow pairs of numbers, of which the first is the abscissa and the second is the corresponding ordinate, thus:

  SPL5(x , x0 , y0 , x1 , y1 , x2 , y2 , x3 , y3 , x4 , y4 , x5 , y5 )

  represents y as a spline function of x which passes through
  (x0,y0), (x1,y1), (x2,y2), (x3,y3), (x4,y4), (x5,y5)

  As in the previous function x may be a constant or a solved/stored variable and x0 , y0 , x1 , y1, etc are constants.

  Library case 763 illustrates the use of this function also.

• PWLF(,), which signifies a piece-wise linear function of which the defining points are specified in a file containing two columns of values.

  Syntax of PWLF()

  PWLF is followed by;

  • an opening bracket,
  • the name of the file (with full path, if it is not in the working directory).
  • a comma,
  • the name of the independent variable, and
  • a closing bracket.

  Examples of the use of PWLF can be found in library case 763, in which the property values at a range of values are read from the files:

  • denprp for density
  • enuprp for kinematic viscosity
  • cpprp for specific heat, and
  • cndprp for thermal conductivity.

  The file is a free-format ASCII file which can be created with any convenient file editor. Lines starting with # or * are ignored. Anything following a ! (including the !) is ignored.

  The first active line may optionally contain the names of the columns. These names are not actually used.

  The following lines contain the numerical values of the variables. The file can contain any number of lines, each line containing two values.

  The values of the first (X) column must always increase or always decrease, as otherwise it is not possible to obtain a unique value for the interpolation.

  A space, comma, semi-colon (;) or tab can be used to separate the columns.

• INTPOL(,,,), which signifies a piece-wise linear function of which the defining points are specified in a file containing several columns of values.

  Syntax of INTPOL()

  INTPOL is followed by;

  • an opening bracket,
  • the name of the file (with full path, if it is not in the working directory).
  • a comma,
  • the name of the column in the file to be used as the dependent (X) variable,
  • a comma,
  • the name of the column in the file to be used as the independent (Y) variable,
  • the name of the variable to be used as the independent (X) variable, and
  • a closing bracket.

  The file is a free-format ASCII file which can be created with any convenient file editor. Lines starting with # or * are ignored. Anything following a ! (including the !) is ignored.

  The first active line must contain the names of the columns. These names are used as the second and third arguments of the command.

  The following lines contain the numerical values of the variables. The file can contain any number of columns and lines, with the restriction that all lines must contain the same number of columns.

  The values of the column designated as the dependent (X) variable must either always increase or always decrease, otherwise it is not possible to obtain a unique value for the interpolation.

  A space, comma, semi-colon (;) or tab can be used to separate the columns.

• RANDOM(), which signifies a random number in the range 0.0 to 1.0, not including the end points.

  Syntax of RANDOM()

  The single argument of RANDOM is used as the seed for the random number sequence.

  • The argument is not equal to zero: The random number sequence is restarted using the argument as the seed value. The first random number in the new sequence is returned. The same seed value will always produce the same sequence of random numbers.
  • The argument is zero: the next random number in the current sequence is returned.

  The argument can be a single value or a 3D array (STOREd/SOLVEd variable) or the result of an expression. The value will be turned into an integer (using the FORTRAN INT() function) before use.

  The algorithm used is a "Prime Modulus M Multiplicative Linear Congruential Generator," a modified version of the random number generator by Park and Miller in "Random Number Generators: Good Ones Are Hard to Find," CACM, October 1988, Vol. 31, No. 10.

neighbour-location functions:

• EAST(), WEST(), NORTH(), SOUTH(), HIGH(), LOW() and OLD(), which have meanings which are conventional in PHOENICS.

  They calculate of variable value at neighbouring cell beside appropriate face and at previous time step.

  Syntax of neighbour-location functions is conventional in PHOENICS. The function name is followed by a bracket, then the name of the variable in question.

  Examples of the use of neighbour-location functions may be found

  • for EAST() in 367 and 368 cases;
  • for WEST() in 367, 368, 710, 722 and 735 cases;
  • for HIGH() in 710, 722 and 735 cases;
  • for LOW() in 366, 710, 722 and 735 cases;
  • for OLD() in 360, 365, 368 and 786 cases.

special functions:

• ALL, BOX(), SPHERE(), LINE() and POINT(), which can be used in INFOB statements with 'infob_n' flag for making geometrical shapes (more numerous than the names suggest); They will be discussed in Object-related functions .

  ALL function sets BOX In-Form object which fills the whole boundary box limited by PATCH command connected with current INFOB statement. Unlike other this function has not arguments and therefore brackets. See more

  BOX(x0,y0,z0,xsize,ysize,zsize,alpha,beta,theta) function sets BOX In-Form object which lies in the boundary box limited by PATCH command connected with current INFOB statement. The position and size of the box are defined in its nine parameters. The syntax of BOX in more details can be found in section 6.4.b

  SPHERE(xc,yc,zc,radius) function sets SPHERE In-Form object which lies in the boundary box limited by appropriate PATCH. The position and size of the sphere are defined in its four parameters. The syntax of SPHERE in more details is described in section 6.4.c

  POINT(x,y,z,diam) function creates the point sub-grid object which lies in the boundary box limited by appropriate PATCH. The position and size of the point object are defined in its four parameters. The syntax of POINT in more details can be found in section 6.4.a

  LINE(xf,yf,zf,xl,yl,zl,diam) function creates the line sub-grid object which lies in the boundary box limited by appropriate PATCH. The position and size of the line are defined in its seven parameters. The syntax of LINE in more details is described in section 6.4.a

  It is exemplified in core library

  • for BOX() in 375, 383, 754, 769, 770, 783 and 784 cases;
  • for SPHERE() in 360, 765, 766, 767, 768 and 772 cases.

• SUM() and SSUM(), which perform special summation operations.

  The SUM() and SSUM() functions are used for summation of results of the formula calculation on all cells inside the area of which can be limited by Patch command connected with current In-Form statement.

  The result of summation is a real number. Therefore as a rule the summation result is assigned to real user-defined variable connected with current In-Form statement and previously to described by '(make' In-form statement.

  The SUM() function is operation of the global summation at all IZ slabs inside Patch region. Before each fulfillment of sum operation the sum is zeroized and accumulates results of summation on all iz-slabs.

  The SSUM() function is operation of the slab summation at one current IZ-slab lying inside Patch region. At each iz-slab before performance of SSUM operation the sum is zeroized and accumulates result of summation at current iz-slabs only.

  Syntax of SUM()

  SUM is followed by ( formula ) with condition where the formula is a expression containing the constants or any variables.

  For example in 786 case the SUM() function is used for setting the bulk room temperature where TEM1 is temperature, VOL is cell volume and YVLAST & XULAST are y & x sizes of domain. The summation is executed at finish of each iz-slab calculation on all domain area and is assigned to user-defined variable TBUL.

  
  (MAKE of TBUL is 0)
  (STORE1 TBUL is SUM(TEM1*VOL/(YVLAST*XULAST)) with ZSLFIN)
  

  In 785 case the SUM() function is used for definition the sum of factors on which inlet mass fluxes should be multiplied. Here AEAST is east face area of calculation grid and (:PI:*:RAD1:^2) is real inlet area from task.

  
  PATCH(PATCH1,INIVAL,1,1,1,NY,1,NZ,1,1)
     *** Primary inlet mass flux coefficient
  (MAKE PRIMF is 1.)
  (STORE1 PRIMF at PATCH1 is SUM(AEAST/(:PI:*:RAD1:^2)) w$
  ith INFOB_1!IF(ISWEEP.LE.2))
     *** Secondary inlet mass flux coefficient
  (MAKE SECNF is 1.)
  (STORE1 SECNF at PATCH1 is SUM(AEAST/(:PI:*(:RAD2:^2-:RAD1:^2))) w$
  ith INFOB_2!IF(ISWEEP.LE.2))
  

  Here the Patch command with PATCH1 name contained any IZ-slabs. If the Patch command contained one IZ-slab then it was possible to use for these purposes other function SSUM() as will be shown below .

  In 781 case the SUM() function provide the re-calculation of reference residuals for G solved variable. The summation is executed on all domain area and is assigned to the PIL real array, RESREF.

  
  (STORE1 of RESREF(G) is SUM(VOL*(GENG-2.*:RHO1:*EPKE*G)/(NY*NZ)))
  

  In 345 case the SUM() function calculate the surface heat flux where TEM1 and TCOLD are temperatures at cell and cold wall accordingly.

  
  WALL(COLD,EAST,NX,NX,1,NY,1,NZ,1,LSTEP)
  (STORED of QWAL at COLD is SUM(PART*(TEM1-TCOLD))/(NZ*NY) with IF(I$
  SWEEP.EQ.LSWEEP))
  

  The result of summation is assigned the QWAL stored variable which is used hereinafter calculation the bulk heat-transfer coefficient. However will more economically use for these purposes single user-defined variable.

  In 362 case the SUM() function calculate the average temperature at each IZ-slab where ASUM and TSUM user-defined variables are sums at one IZ-slab of high cell face areas and the cell temperatures accordingly.

  
  (MAKE TSUM is 0.)
  (MAKE ASUM is 0.)
  DO II=1,NZ                                       !  ** Start of IZ cycle
   PATCH(PATCH:II:,CELL,1,NX,1,NY,:II:,:II:,1,1)   ! One PATCH per slab
    ** Summation of HIGH area for each IZ slab
   (STORE1 ASUM at PATCH:II: is SUM(AHIGH))
    ** Summation of temperature multiplied by HIGH area for each IZ slab
   (STORE1 TSUM at PATCH:II: is SUM(AHIGH*TEM1))
    ** Determination of average temperature for each IZ slab
       and storage inside 3D variable TAVE
   (STORED TAVE at PATCH:II: is TSUM/ASUM)
  ENDDO        ! End of DO loop
  

  The calculations are executed within the limits of one IZ-slab of which set by Patch command with PATCH:II: name. The DO command of cycle is used for fulfillment of calculation in all domain area.

  Syntax of SSUM()

  The syntax of SSUM() is similarly constructed. Thus, SSUM is followed by ( formula ) with condition where the formula is a expression containing the constants or any variables.

  Example of SSUM() use for calculation the average temperature at each IZ-slab may be found in 363 case which is identical to 362.

  
  PATCH(PATCH1,CELL,1,NX,1,NY,1,NZ,1,LSTEP) ! One PATCH per whole domain
    ** Summation of HIGH area for each IZ slab
  (STORE1 ASUM at PATCH1 is SSUM(AHIGH))
    ** Summation of temperature multiplied by HIGH area for each IZ slab
  (STORE1 TSUM at PATCH1 is SSUM(AHIGH*TEM1))
    ** Determination of average temperature for each IZ slab
       and storage inside 3D variable TSLB
  (STORED TAVE at PATCH1 is TSUM/ASUM)
  

  The use of SSUM() function permits to avoid the creation iz-slab loop as in 362 case. Here the summation operations of are executed consistently for each iz-slab for calculation of the total area, total temperature multiplied by high area and average temperature.

• AECO(), AWCO(), ANCO(), ASCO(), AHCO(), ALCO(), APCO(), GAMM(), RESI(), SORC() and CORR(), which can used for extraction of some terms in the finite-volume equations according to function name.

  AECO(), AWCO(), ANCO(), ASCO(), AHCO(), ALCO(), APCO() functions get coefficients of the finite-volume equation. See more.

• RESI() function stores residuals. See more.

• CORR() function extracts corrections. See more.

• GAMM() function gets exchange coefficients. See more.

• SORC() function gets sources values.

Examples of the use may be found

• for AECO(), AWCO(), ANCO(), ASCO(), APCO() in 703 and 788 cases;
• for AHCO(), ALCO() in 788 case;
• for RESI() in 249, 768 and 788 cases;
• for CORR() in 064, 249, and 768 cases.
• for GAMM() in 703 and 788 cases.

COVAL(), which can used for linearized source setting in the (SOURCE statement. The functions has two arguments which in general case can be the formulas for calculation coefficient and value.

Examples of the use may be found in 737, 745, 746, 747, 774 and 789 core-library cases. In more details it will be discussed and exemplified in section 7.1 and section 7.6

POS(), OFFSET() which can used for mofor purposes in the (MOVOB In-Form statement.

POS(Xpos,Ypos,Zpos,Xang,Yang,Zang) function describes the coordinates of position of moving object. Its six parameters can be formulas. If they are functions of the TIM current time then the object will be moved during time steps.

Examples of the use may be found in 360, 365, 369, 370, 371, 372, 373, 376, 378, 379, 380, 381 and 382 core-library cases. More details see section 8 .

OFFSET(Xorigin,Yorigin,Zorigin) function declares the frames of reference of object-related coordinate systems. In general case its three parameters can be formulas also.

Examples of the use may be found in 381 and 382 core-library cases. See more

d. Operands

See also Appendix 4

1. Names of stored and solved variables

   The NAME of any SOLVEd or STOREd variable, e.g. P1, H2, KE, ENUL or RH01, may be an operand.

   If no square or curly brackets follow the name of the variable, the value prevailing at the current cell is intended.

   However neighbour-cell or more-distant-cell values may be referred to, either in terms of their indices, IX, IY, IZ, or of their geometric coordinates, x, y, z.

   Square brackets are used for the former and curly brackets for the latter, in accordance with the following conventions:

   (a) Use of indices

   • These may be either fixed indices, whereby:
     • PHI[1&2&3] is the value of the dependent variable PHI at the cell
       IX = 1; IY = 2 and IZ = 3.
     • PHI[1] (or PHI[1&&]) is the value of the dependent variable at the cells of
       IX = 1; IY = IY and IZ = IZ.
     • PHI[&3] (or PHI[&3&]) is the value of the dependent variable at the cells of
       IX = IX; IY = 3 and IZ = IZ.

     A core-library example which makes extensive use of indexing is case 759, where it is used for the creation of the pressure-gradient sources which are needed for the solution of the 'collocated-velocities' equations.

     Another is case 758, where it is used for the creation of an initial-value field on one slab by the superposition of the initial-value fields on two lower slabs.

     Another example is case 710, where indexing is used to enable the flow of tube-side fluid to be simulated for a shell-and-tube heat exchanger.

   • or relative indices, whereby:
     • PHI[+1] corresponds to EAST(PHI)
     • PHI[&+1] corresponds to NORTH(PHI)
     • PHI[&&+1] corresponds to HIGH(PHI)
     • PHI[-1] corresponds to WEST(PHI)
     • PHI[&-1] corresponds to SOUTH(PHI)
     • PHI[&&-1] corresponds to LOW(PHI)

     Relative indices are used in case 368, as a substitute for the 'neighbour-patch' technique which had been employed in an earlier PLANT-based solution of the same problem.

   (b) Use of coordinates

   The situations described above use the values of variables in cells, at positions defined by the indices: ix, iy, iz. However, in practice it is more usual to require values at specific distances, defined via the cartesian coordinates: x, y and z. Their locations will not in general coincide with cell centres. Therefore the values prevailing there must be derived via interpolation

   Use of curly brackets in the formulas after the variable name effects this interpolation domain.

   The curly brackets, like the square ones, are placed after the variable name in the formula. They are intended for the description of x, y and z coordinates of the point inside the domain and consequently should not exceed the domain sizes. The coordinates are separated by & symbols.
   In one- or two-dimensional problems, the coordinate appropriate to the missing dimension(s) may be omitted.

   The core-library case v152 sets the x and y coordinates of the temperature sensor to 0.05 m. by means of the specification:TEM1{0.05,0.05}.

2. Variables pertaining to a cartesian or cylindrical-polar grid

   Any of the following may be an operand:

   NX, NY, NZ

   the number of intervals in the space directions

   XG, YG, ZG

   the coordinates of the centre point of a grid cell

   XU, YV, ZW

   the distances from the origin of the corresponding velocity-storage points

   ZZW, ZWADD

   quantities used in z-wise grid-expansion formulae

   RG and RV

   (for polar-coordinate grids) the radii of the cell centre and v-velocity node respectively

   DXG, DYG, DZG

   the distances between the cell centres in the three coordinate directions

   DXU, DVY, DZW

   the corresponding distances between the velocity nodes; and

   VOL

   the volume of the cell

   AEAST, ANORTH, AHIGH

   the east, north and high areas of a cell

   XULAST, YVLAST, ZWLAST

   the total extents of the domain in the three coordinate directions

   IXF, IXL, IYF, IYL, IZF, IZL

   The first and last cells of a patch in the x- and y-directions

   RINNER

   The inner radius of a polar-coordinate grid velocity-storage points

3. Variables pertaining to expanding or contracting grids for parabolic flows

   These operands are the following:

   IZ, IZSTEP

   both of which represent the z-wise cell index number

   XRAT, YRAT

   the x- and y-wise expansion ratios

   DZRAT

   the corresponding z-step expansion ratio

   DZ, DZL, DZGL

   the z step size, its previous value, and the distance between the cell centres corresponding

   AZDZ, AZXU, AZYV, AZPH

   various factors relating to non-uniform parabolic grids

   SNALFA

   grid-edge slope in parabolic grids

4. Variables for time-dependent flow simulations

   Any of the following may be used as operands:

   TIM

   the time from the start of the flow process

   DT

   the current time step

   TFIRST, TLAST

   the starting and finishing times

5. Indices and counters

   Any of the following indices and counters may be used as operands:

   INDVAR

   the index of the currently-solved variable, eg 3 for U1 or 14 for H1

   FSWEEP, ISWEEP, LSWEEP

   the first, current and last sweep number

   FSTEP, ISTEP, LSTEP

   the first, current and last time step

   ITHYD, LITHYD

   the current hydrodynamic iteration number and its upper limit

   IRUN, NRUN

   the current run number (in a multi-run calculation) and its upper limit

6. Miscellaneous

   The final set of operands comprises:

   TSURR

   the temperature of the surroundings

   PBAR

   the average downstream pressure in a parabolic calculation

   MASS1

   The mass of first- (or only-) phase material in the cell

   MASS2

   the mass of second-phase material in the cell.

   TINY, GREAT

   very small and very large numbers

All operands, used in In-Form formulas, listed in alphabetical order in Appendix 4.

e. Further examples

This permits cases to be selected which exemplify the use of In-Form in combination with selected other PHOENICS features.

Back to main contents

3. Grid specification

3.1 Time discretization

3.2 Geometric grids for parabolic flows

The variable XRAT can be set for each z-location. An example is:

(XGRID of XRAT is 1.+:POWER:*DZ/(ZWADD+ZZW))

Likewise, YRAT can be specified, for example as in case 777 as follows:

(YGRID of YRAT is 1.+:POWER:*DZ/(ZWADD+ZZW) with IF(IZ.LE ..20.OR.IZ.GT.40))

Finally, In-Form can specify the forward step, DZ, as for example in case 776:

(ZGRID of DZ is 0.1*YVLAST with IF(IZ.LE.2))

a. Overview

A new class of object

Now In-Form allows the use of its own objects, the positions and shapes of which are marked by the cells which they occupy; and it provides formula-based means for defining those cells.

It should be recognised from the start that In-Form objects occupy cells either wholly or not at all; they cannot at present, as facet-described (i.e. 'VR') objects can, occupy only part of a cell. This limitation may be removed in the future.

A change of syntax

For example, an initial value is attached to an In-Form object by way of a statement such as:
(INITIAL of PRPS at PATCH1 is 0.0 with INFOB_1)

wherein it can be seen that In-Form objects, here INFOB_1, are always associated with patches.

All this will be explained below. What must first be described however is how In-Form objects, of which the user is at present allowed up to eight in a given flow simulation, are actually created,

Object creation

(INFOB at PATCHNAME is Formula with INFOB_N)

Here:

• 'INFOB' is a keyword which indicates what is to follow;

• 'PATCHNAME' is the name of a patch defined by a preceding (in the q1 file) PATCH statement, which defines the limits, in terms of ixf, ixl, iyf, iyl, izf, izl, itf and itl, within which the object may exist;

• N is the index of the object (from 1 to 8); and

• 'formula' is a character string which defines the shape and position of the object in space and time.

The INFOB statement acts by 'tagging' the cells of which the centre lies within the object, recording at the same time which object is in question.

Additionally and optionally, if it is desired to indicate these cells via the RESULT file or PHOTON display, a 3D-stored variable (usually, but not necessarily, called 'MARK') is also given the infob index as its value.

To ensure this, the INFOB statement needs to be preceded by one such as:
   (STORED of MARK at PATCH1 is 1.0 with INFOB_1)
which ensures that:

1. the variable MARK is indeed stored; and
2. that the value 1.0 is assigned to it in cells which are to be regarded as part of INFOB object number 1.

Is an INFOB PATCH a 'bounding box'?

The patch associated with an In-Form object, however, is usually larger than would be the bounding box of the cells comprising the objects. It is the volume within which such cells may exist; but it is rare for any of these cells to touch the bounding surfaces of the patch.

In one sense the INFOB PATCH is unnecessary; for, if the PATCH were always defined as the whole domain, the effects of the object would be the same. However its existence acts as an economy measure; it tells PHOENICS where searching for parts of the object would be a waste of time.

That each In-Form object should have a distinct PATCHNAME is important; for it is this which is used, rather than INFOB_1, INFOB_2, etc when initial values and sources are ascribed.

New functions

These may create directly objects having the shapes suggested by their names; but, with appropriately devised arguments, they may also be used for the creation of objects of much more complex shape.

It should be noted that both these functions can be used with cylindrical-polar and body-fitted coordinate grids as well as cartesian ones.

In the last respect they are superior to Virtual-Reality objects; for the latter can not be used with BFCs.

b. The BOX function

This, in conjunction with the (STORED of MARK.... statement, uses BOX(arguments) to indicate which are the cells in question.

Also permissible is the statement:
   (INFOB at PATCH1 is ALL - BOX(arguments) with INFOB_1)

This indicates that the said value of MARK is to be placed at all cells in the patch except those within the space defined by BOX.

'ALL' can here be regarded as a function which has no arguments.

The arguments in question are as follows:
    BOX(x0,y0,z0,xsize,ysize,zsize,alpha,beta,theta)
where
x0 = X-coordinate of west south low corner of box, in meters
y0 = Y-coordinate of west south low corner of box, in meters
z0 = Z-coordinate of west south low corner of box, in meters
xsize = X-size of box side, in meters
ysize = Y-size of box side, in meters
zsize = Z-size of box side, in meters
alpha = angle rotating around x axis, in radians
beta = angle rotating around y axis, in radians
theta = angle rotating around z axis, in radians

Any one of the nine arguments can be expressed by way of a formula which may itself contain functions and constants.

Library case 383 illustrates the use of the box function for the creation of a box in a cubical domain, with all its rotations equal to 0.25 radians. A photon plot is shown here, created by the sur mark x 0.99 and sur mark y 0.99 commands.

c. The SPHERE function

It has fewer arguments however, namely:
    SPHERE(xc, yc, zc, radius)
where
    xc = x coordinate of the centre, in meters
    yc = y coordinate of the centre, in meters
    zc = z coordinate of the centre, in meters
    radius = radius of the sphere, in meters
because rotations about its centre cannot change its shape.

When the calculation is being carried out with a cartesian grid, the coordinate system of the sphere coincides with the coordinate system of the calculation domain.

When the calculation is being carried out with a polar-coordinate grid, the cartesian coordinate system of the sphere has its origin at the bottom left-hand corner of a square which circumscribes a circle of radius RINNER+YVLAST.

Therefore the cartesian coordinates xc and yc are related to the polar coordinates xp and yp by the relations:

xc=(yvlast+rinner) + (yp + rinner) * sin(xp)
and
yc=(yvlast+rinner) + (yp + rinner) * cos(xp)

The Z coordinates of the origins and the directions of Z axes of both coordinate systems coincide with one another.

'ALL - SPHERE' has the same significance as for 'BOX'.

Library case 772 creates an In-Form object, namely a sphere with its centre on the axis of a polar grid, by means of:
(INFOB at PATCH1 is SPHERE(10, 10, 10, 5) with INFOB_1)

The PHOTON plot displayed here reveals the result.

d. Simple shapes made with BOX

A pyramid

The pyramid is made in four parts, each of which is rotated around the vertical edge which they share.

The following images show: the whole pyramid, then part 1, part 2, part 3 and part 4.

Inspection of the q1 file shows that each part of the pyramid is made by a different Infob statement, each of which however refers to the same PATCH1 and the same INFOB_1. The differences reside in their zangle arguments.

An x-direction pyramid

The pyramids have been created, as other examples will be, by making one or more arguments of the box function depend the grid-point coordinate.

The information is used at the time that each grid-point is visited at infob-scanning time; and it implies that the question "is this cell-centre in the box?" refers, in general, to a different box for each cell.

A single infob in more than one patch

Library case 783 illustrates this, wherein PISTON1 is a patch which is active for the first time step only, while PISTON2 is used for describing the position of the same In-Form object at later times.

Other simple shapes made by use of BOX

e. Simple shapes made with SPHERE

f. Some more-complex examples

Sphere connecting two tubes

(INFOB at PATCH1 is SPHERE(10., 10., 10., 8.) with INFOB_1)

(INFOB at PATCH2 is SPHERE(XG, 16., 10., 2.) with INFOB_1)

(INFOB at PATCH3 is SPHERE(XG, 4., 10., 2.) with INFOB_1)

The first statement describes the central sphere, second - the top horizontal cylinder and third - the bottom cylinder.

Spheres inside wide channel

The creation of complex duct by means drilling of In-Form object in BFC is shown in 787 library case. At first a wide bent channel is created by means of BFC. The narrow channel is created from it by blocking any cells. Then two In-Form objects are described as spheres inside a wide channel.

(INFOB at PATCH1 is SPHERE(:XPP1:,:YPP1:,:ZPP1:,:RADIUS:) with INFOB_1)

(INFOB at PATCH2 is SPHERE(:XPP2:,:YPP2:,:ZPP2:,:RADIUS:) with INFOB_2)

Further inside each sphere values of PRPS variable are filled in with zero

(INITIAL of PRPS at PATCH1 is 0. with INFOB_1)

(INITIAL of PRPS at PATCH2 is 0. with INFOB_2)

See also the description of spiral-shape creation in section 7.4b below.