Encyclopaedia Index

In-Form; the Input of Data by way of Formulae

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

Summary

In-Form is a supplement to the PHOENICS Input Language (PIL) which facilitates the input of problem-defining data. Specifically, it allows users to express their requirements through algebraic formulae, whether for:

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:
Unlike the earlier PLANT feature of PHOENICS, In-Form creates no new Fortran coding and therefore needs no 're-compilable' version of the software.

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

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
    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

Back to main contents

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

Prior to the introduction of In-Form, there were three methods for defining flow-simulation tasks for PHOENICS, namely:
  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:

  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, whereafter 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:

1.2 The new capabilities supplied by In-Form

1.3 How In-Form works

The points which all users of In-Form should understand are as follows:
  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:


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

Consider the setting of the PIL variable RHO1, the first-phase domain-fluid density.

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

c. Answers to initial questions about In-Form

Questions already may have arisen in the reader's mind, which it is as well to articulate and answer at once. Here are some:


d. What has appeared in Q1EAR and EARDAT

For interested readers who have read the second part of section 1.3 (How In-Form works) the consequences for Q1EAR and EARDAT of the In-form statements of sub-section b above will now be shown.

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

The following comments are appropriate:


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

As has already been stated, the general form of an In-Form statement in a Q1 file consists of four items, enclosed between () brackets:
(keyword what_where_when_indicators formula optional_conditions)

This will now be explained, under the headings:

It should be noted that:

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

The keywords used in In-Form statements are:


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

'var', the 'what' indicator

In the statements for density in section 2.1a, the words between the keyword and the formula were 'RHO1 is'.

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

The applicability of formulae can be limited in space and time, by use of the word 'at' followed by the name of a patch or object, the names of which must appear in the Q1 file.

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) 
Here, the 'where' is specified by the IXF, IXL, IYF etc arguments of the patch commands; and the 'when' by the final '1,1's which, since the case is a steady-state one, signify 'at all times.'

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
wherein it will be noted that the exclamation mark, !, replaces 'at'; and

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

It might be argued that the same effect could have been arrived at without the use of In-Form; this is true; for RHO1 could have been set by means of four INIVAL-type patches.

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)) 
from which it can be deduced that the formulae may involve other 3D-stored variables (u1, v1, p1, h1) and also geometrical quantities (xg, yg) .

[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

Core library case 756 simulates (rather crudely) the motion of a paddle in a chemical reactor. It does so by shifting the PRPS distribution be reference to different patches at different times.

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

The name of an object may be substituted for the name of a patch, with the difference that the formula is then operative only in that part of the bounding box of the object which lies within the facet-described outer surfaces of the 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

The alert reader may have noticed that, for the square-cavity case, the In-Form statement containing 'at SW' was placed below the PATCH(SW,.....) declaration, and that the same order (PATCH first, at later) was adopted for the three further statements.

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
which will be found to give the same results as before.

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


d. The formula


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

There are numerous post-formula options; but many of them apply only to particular keywords, as is shown in Appendix 2.

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

EARDAT manifestations; the use of '!'

Inspection of the corresponding entries written into EARDAT, when the SATELLITE has finished reading the Q1 of case 756, reveals that the counterparts of the In-Form statements just inspected, namely:

(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)
are ( with $ and blanks removed for ease of reading ):

 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:

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:

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

INFOB_N

In-Form objects, created by the INFOB keyword, will not be discussed systematically until section 6. Here it suffices to say that their existence and location may (but need not) be indicated by the value of a 'marker variable' (usually MARK) in the cells which they occupy.

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

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

a. General description

The formulae employed by In-Form, whether for setting properties, initial values, sources or anything else, are arrangements of operators, functions and operands which conform to rules which are similar to those of algebra and/or Fortran.

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

b. Operators

The operators which may be used are:

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:

formula-name functions:

neighbour-location functions:

special functions:

These functions have one argument. Namely name of solved variable. They are used in the (STORED statements. section 9.3 in more detail.

Examples of the use may be found

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
The foregoing operators and functions can be associated with the following operands:
  1. Names of stored and solved variables

    The NAME of any SOLVEd or STOREd variable, eg 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

    (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

The best way to find out what examples of the use of In-Form are to be found in the PHOENICS Input-File Libraries is to activate the PHOENICS Commander and then to click on the Input-File Library icon at the top of the opening page.

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

In-Form allows time discretization to be dictated by formulae by means of the TGRID keyword, the syntax of which is most easily learned by inspection of library case 778.


3.2 Geometric grids for parabolic flows

In-Form permits the specification of expanding and contracting grids for parabolic calculations.

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

Since the introduction many years ago of the 'Virtual-Reality' user interface, PHOENICS has made extensive use of 'objects'. [Click here for the relevant Encyclopaedia entry]

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

All that has been explained above about attachment of In-Form operations (INITIAL, SOURCE, etc) to the whole domain, to patches in space and time, and to VR-objects, applies also to In-Form objects, as will be illustrated below. However the syntax is a little different.

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

In-Form objects are created by means of statements of the following format:

(INFOB at PATCHNAME is Formula with INFOB_N)

Here:

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'?

VR objects have 'bounding boxes'. These are the smallest volumes which can be defined by grid-aligned surfaces into which the object will fit.

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

Two special functions, namely 'BOX' and 'SPHERE', are used in the formulae which follow the INFOB keyword.

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

The format governing the use of BOX in INFOB statements is indicated by the following example:
   (INFOB at PATCH1 is BOX(arguments) with INFOB_1)

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

The format governing the use of SPHERE in INFOB statements is similar to that of BOX, namely:
   (INFOB at PATCH1 is SPHERE(arguments) with INFOB_1)

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

Core Library 769 shows how a pyramid can be created by a succession of In-Form statements employing the BOX function, in which the x-, y- and z-sizes vary with the value of zg.

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

If a similar pyramid is required with its base on the X=0 surface rather than the z=0 one, at it is necessary to replace zg by xg in the In-Form statements and to interchange the first, fourth and seventh arguments (which relate to x) with the third, sixth and ninth (which relate to z). Then the result is as shown here.

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

It is permissible, and sometimes convenient, to associate an individual In-Form object with more than one patch, for example when different time periods are in question.

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

Library case 754 provides several examples of simple shapes made by the use of the BOX function.

e. Simple shapes made with SPHERE

Library case 749 provides several examples of simple shapes made by the use of the SPHERE function.


f. Some more-complex examples

Sphere connecting two tubes

Next 771 library case illustrates the creation of a Pump Chamber.

(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.