Encyclopaedia Index


is a PIL Command; groups 11, 12, 13 & 23

A 2009 prefatory remark

Indicial or geometric location of patches

All that is written below is correct; but, because it dates from the early years of PHOENICS, it fails to draw attention to one important fact, namely that the locations of the patches which it describes are defined in terms of their starting and finishing grid indices, IXF, IXL, IYF, IYL, etc rather than their geometric coordinates in x~y~z space.

This has the disadvantage that grid refinement cannot be effected by simply (say) doubling NX, NY and NZ; one must additionally modify the IXF, IXL, IYF, etc for patches which define their locations in the grid.

Fortunately there exists a solution to this difficulty; or, rather, two: one old and the other new, namely:

  1. the complete set of arguments 'ixf, ixl ,iyf ,iyl ,izf ,izl' can be replaced by
    when the geometric limits of the so-named object have been defined in an RSET command appearing higher in the Q1 file; or
  2. the name of the patch can be changed so as to make its first character a dot; then the indicial arguments can be replaced by their normalised real-number equivalents.
The details will be explained and exemplified below, in the recently-modified section 1; but attention is drawn to it now lest the importance of the indicial-or-geometric question should be overlooked.

Connections with VR-objects

The following sections have another deficiency: they make no mention of patches which are not created explicitly by user-editing the Q1 file; yet many patches do come into existence as indirect results of user actions, namely those which are associated with the assignment of initial values and sources for Virtual-Reality objects.

A small amount of information on this topic is to be found in TR 326; but more is needed.


  1. The PATCH command and its arguments
    1. Indicial locators
    2. Geometric locators; via RSET
    3. Geometric locators; via dot-patch
    4. Which kind of locator should one use?
  2. The uses of PATCH
    1. in group 11 for initial values
    2. in group 12 for source, diffusion and convection modifications
    3. in group 13 for sources and boundary conditions
    4. in group 23 for line-printer-type output
  3. De-activating PATCHes
  4. Region numbers as arguments
  5. PATCHes introduced via Fortran
  6. Power-law patches
  7. Referencing PATCH names in GROUND coding

1. The PATCH command and its arguments

PATCH is a PIL command used in a Q1 file to define sections of the domain over which:

  1. in Group 11, the initial values of stored or solved variables are to be set;
  2. in Group 12, the source, convection or diffusion terms of solved variables are to be modified;
  3. in Group 13, special sources or boundary conditions of solved variables are to be activated;
  4. in Group 23, profile, contour or tabular plots of stored or solved variables are to be printed.

1 (a) Indicial locators

PATCH can have 10 arguments, whereby:


1 (b) Geometric locators; via RSET


PATCH might have only 6 arguments, namely:

PATCH(patch_name, TYPE, OBJECT, object_name, ITF, ITL)

Here the argument(s):

Examples of the geometrically-located PATCH are to be found in Input-File-Library case 274 . Click here for RSET and here for PATCH.

Two further points should be noted, namely:

  1. objects introduced by RSET commands always affect the grid: and
  2. indicial markers are still used within the solver. Thus the RESULT file of case274 contains the lines:
     Group 11.Initial field variables (PHIs)
      PATCH(BODY1   ,INIVAL,    1,    3,    2,    3,    6,   10,     1,     1)
     INIT(BODY1   ,PRPS, 0.000000E+00, 1.980000E+02)
      PATCH(BODY2   ,INIVAL,    1,    3,    4,    6,    7,   10,     1,     1)
     INIT(BODY2   ,PRPS, 0.000000E+00, 1.980000E+02)
    This however is a manifestation of EARTH's internal accounting; and it has no bearing on the question of which kind of locator should be used.

1 (c) Geometric locators; via dot-patch

A different means of introducing geometrically-located patches is the recently-introduced dot-patch device.

Description and exemplification can be accessed via the hyperlink. Here it suffices to say that:

1 (d) Which kind of locator should one use?

Indicial or geometric ?

Although patches with indicial locators predominate in the current PHOENICS Input-File Libraries, that is only because they were invented first; for most purposes, geometrically-located patches are to be preferred.

The reason is that grids are artificial entities, necessary for the purpose of perfoming numerical calculations, but forming no part of the physical phenomenon which is to be simulated.

Indeed it is often desirable to perform the simulation with more than one grid, using perhaps a coarse grid at first so as to establish the major features of a flow and a succession of finer ones later, in order to procure greater accuracy. The use of the SPINTO module makes it easy to do so.

In such a successive refinement operation, it would be extremely tiresome to have to change all the IXF, IXL, etc. of the PATCHes each time the grid was changed.

If geometric locators are used, there is no need for this.

RSET or dot-patch ?

Although too little experience has been gained of either of the two methods, for a firm recommendation to be made, it seems probable that the greater simplicity of the dot-patch method will cause it to be preferred.

2. The uses of PATCH

The uses of PATCH in the four above-mentioned Groups will now be described separately.

2. (a) Initial-value patches in Group 11

In group 11, the last two arguments are always 1, for the initial values can be set only at time step 1.

The PATCH types operative in group 11 are:

PATCH in Group 11 is always followed by one or more INIT commands, each having four arguments, namely: patch name, variable index or name, coefficient, and value.

The INIVAL type.

An example is:

This, because the type is INIVAL, will set the initial value of U1 to equal 12.5 if the PIL variable INIADD equals F; but if INIADD=T, the value 12.5 is added to whatever has already been set by FIINIT(U1) and by earlier-appearing INIT commands.

If the variable is being stored but not solved, as would be the case with porosities for example, the value will be retained throughout.

When porosities ( eg. NPOR ) fields are being set, it is important to remember to put FIINIT(NPOR)=1.0, so that no blockage is present in sections of the domain not identified by PATCH.


If it is desired to give the variable initial values which vary linearly with ix, iy or iz, the following steps should be taken:


When INIADD is true, judicious use of the various types of patches permits complicated initial-value variations to be contrived.

Setting initial values via GROUND

For more complicated variations of the initial fields than those provided by the above options, the fourth argument of INIT should be set to GRND. This causes EARTH to visit group 11 of GROUND for an array of GROUND-set VALues for each cell in the PATCH. For example:


requires the user to provide in group 11 of GROUND a sequence which fills the EARTH array referred to by the index VAL for INDVAR=H1 at each IZ slab of the domain.


To check that the initial fields are correctly set, the user should set INIFLD=T to cause EARTH to print out the initial fields at the beginning of the calculation.

Uniform velocity fields for BFC grids

Uni-directional flows can be initialized by means of the special PATCH names starting IBFC that causes group 11 of GREX3 to call subroutine GXBFC.

The following commands result in a uniform initial flow at 99.0 m/s, parallel to ZC in a body-fitted grid,

2. (b) Term-modifying patches in Group 12

PATCH....can be used in Group 12 to make local adjustments to the terms in the differential equations.

The following patch- names, in which ? is a 'wildcard' and GP12 can be replaced by an ampersand, cause the terms indicated, for the variable appearing as the second argument of a corresponding COVAL statement, to be multiplied by the third (CO) argument of that COVAL, in the cells occupied by the PATCH.
Patch-name terms affected
GP12CON? all convection terms
GP12SOR? all built-in source terms
GP12CNE? east-face convection terms
GP12CNN? north-face convection terms
GP12CNH? high-face convection terms
GP12DFE? east-face diffusion terms
GP12DFN? north-face diffusion terms
GP12DFH? high-face diffusion terms

For example:
would cut out the east-face convection terms for the first- and second-phase z-direction velocity components, in the cells and for the duration indicated by arguments 3 to 10 of the PATCH command.


'Contact resistances' can be introduced into heat-transfer simulations using GP12DF patches. The ability to multiply the total diffusive conductance, for a particular variable and a particular patch, by the constant appearing as the CO argument of the corresponding COVAL is used. In addition, the VAL argument is given significance.

Specifically, the resistance to diffusion now becomes equal to: (resnom + VAL)/CO, where resnom is the nominal resistance, ie that computed by PHOENICS EARTH.

The diffusive coefficient becomes the reciprocal of the above resistance, multiplied by the cell-surface area.

The feature is useful when it is desired to introduce a "contact resistance" to heat conduction. Then VAL should take the value of this resistance and CO should be set as 1.0.

If it is desired to replace the EARTH-calculated resistance by another, say "resnew", then VAL should be set as resnew*1.e10 and CO should be set as 1.e10 .


This feature works only for variables for which the harmonic-mean diffusion option has been selected.

2. (c) Source and boundary-condition patches in Group 13

PATCH is used in Group 13 to define the areas or volumes over which boundary conditions or special sources are to be set by means of COVAL.

The PATCH types operative in group 13 are:

Much information about what boundary-condition or source functions are to be exercised by a patch is conveyed by the name of the patch.
An account of the significance of patch names is to be found in the PHENC entry: RESERVED NAMES.

2. (d) Print-out-controlling patches in Group 23

PATCH is used in group 23 to define sections of the domain over which plots are to be set by the PLOT command. See PATCH in group 13 for the significance of its 10 arguments.

The PATCH-types that are operative in this group are PROFIL and CONTUR.

If the name of the PATCH starts with the letters TAB, the values of the variable used in the plotting of CONTUR maps will be printed out as a TABle before the map is printed.

If the name starts with the letters TBO (ie. TABle Only), only the table will be printed.

The fourth argument of the COVAL (VAL) has no significance in this case.

3. De-activating PATCHes

Sometimes it is desirable to de-activate PATCHes. In a Q1 file, this can be achieved by simply converting the PATCH statement into a comment by shifting it 2 or more columns to the right by means of the system editor. An alternative which also permits PATCH de-activation in an interactive session is to set the PATCH name to SKIP. See SKIP for further information.

4. Region numbers as arguments

If the grid has been divided into regions (ie if NREGi > 1, for i=X,Y,Z or T), then PATCHes (and CONPOR commands) may be set over whole regions in any direction by setting the last 8 arguments as #ireg, ie: PATCH(name, TYPE, #iregx-first, #iregx-last,... #iregt-first, #iregt-last).

Also, $ireg or %ireg may be used to specify patches applying to the first or last cell in a region respectively, eg: PATCH(name, TYPE, $2, $2, #1, #1, #1, #NREGZ, #1, #NREGT) would specify a PATCH over the first cell in the second region in the x-direction, over region 1 in the y-direction, over all regions in the z-direction and for all time regions.

5. PATCHes introduced via Fortran

If subroutine PATCH is called from SATLIT in FORTRAN, the symbols $, % and # are not recognised. Thus to set PATCHes by region numbers use
100000+<region number> instead of $<region number>
200000+<region number> instead of %<region number>
300000+<region number> instead of #<region number>

For example, the following PIL command:
would become
CALL PATCH('AAA ',VOLUME,100000+1,100000+1,300000+1,300000+2, 1 200000+3,200000+3,1,1)


If a PATCH name begins *name, where name is the four-character name of a solved or stored variable, a corresponding COVAL for variable PHI will introduce a source of PHI equal to:


where CO is the third argument of the COVAL, and NAME stands for the local value of the variable having the name which has been referred to.

An example which provides a source equal to - 4.0*KE*VOSQ**0.5 is:


The feature is illustrated by library cases 413, 414 and 415. See also PHENC entry: star-name

7. Referencing PATCH names in GROUND coding

If the referenced variable has a 2-character name, the patch name must include the blanks, because the internal-to-EARTH test is made on the first 5 characters of the PATCH name.


PATCH(*P1 A,... ) followed by COVAL(*P1 A,H1,1.E3,2.0) will create a source of first-phase enthalpy which is proportional to pressure squared; but: PATCH(*P1A,... ) followed by COVAL(*P1A,H1,1.E3,2.0) will not.


Patch-wise variables are those having a distinct value for each cell forming a patch which is created in the SATELLITE. These are stored in segments of the F-array having length equal to


for each patch, one such segment being supplied for each PWV.

The integer names are those which appear in COMMON block /LBPV/ of GRDLOC, which is as follows:

      1 LBPVSP(7) 

From this it can be deduced that space has been provided for 30 patch-wise variables, that the first 23 names have been allocated (but could be changed) and that the last 7 are spares.

The meanings of the 23 allocated names are:-

    PVGENR, (generation rate-dissipation rate) of turbulence energy;
    PVDISS, generation rate of turbulence energy;
    PVSKIN, the "skin-friction" coefficient;
    PVRLVL, the relative velocity;
    PVSTRS, the wall shear stress divided by density;
    PVRCDS, the reciprocal of the wall distance;
    PVSTAN, the Stanton number;
    PVMASS, the first-phase mass flux;
    PVVMAS, the GROUND-set "value" associated with first-phase mass input;
    PVURES, the x-direction first-phase velocity resolute;
    PVVRES, the y-direction first-phase velocity resolute;
    PVWRES, the z-direction first-phase velocity resolute;
    PVMAS2, as for PVMASS, but for the second phase;
    PVCO,   skin-friction factor;
    PVCP,   pressure coefficient;
    PVVMS2, PVURS2, PVVRS2, PVWRS2, PVSCAX, PVSCAY, PVSCAZ, PVYPLS, the normalised wall distance, yplus.

The remainder are spares, which users can employ for their own purposes.

The arguments of the PATCH and COVAL commands are also stored, as single values, in the F-array, whether they are integers or reals.