Encyclopaedia Index
Back to main contents

9. Print-out-related capabilities

Contents of Section 9

  1. The LONGNAME keyword
  2. The PRINT keyword
  3. Coefficients, residuals, corrections and exchange coefficients (gammas)
  4. Eliciting debug
  5. Tabular Output

9.1 The LONGNAME keyword

Variables which are introduced by way of In-Form statements beginning: (STORED ... are computed at each sweep through the solution domain. However, it sometimes occurs that values are required only for print-out purposes.

For such cases, In-Form provides the LONGNAME feature, which is activated only for print-out sweeps.

Syntax

The syntax of LONGNAME statements is exemplified by the following line from Input-library case 763:

   (LONGNAME of L3RH print as 3-Piece-Wise_Linear_Density)
wherein: The usefulness of the LONGNAME feature is shown by the following lines which appear in the RESULT file for case 763:

Field Values of L3RH: 3-Piece-Wise_Linear_Density
 IY=  10   1.083E+03   1.038E+03   1.023E+03   1.022E+03   1.023E+03
 
 Field Values of RHO1: The_Density_Actually_Used
 IY=  10   1.083E+03   1.037E+03   1.023E+03   1.022E+03   1.023E+03
They show that the density actually used, which was computed from a cubic polynomial, differed very little from the piece-wise-linear alternative.

An earlier 'longname' feature

To avoid confusion, it should be mentioned that In-Form's LONGNAME keyword serves the same purpose as the earlier, still-available, but somewhat less easy to use, practice described here.

9.2 The PRINT keyword

Syntax

The '(PRINT' .... In-Form statement will print fields of standard dependent variables, or of user-defined single real variables, calculated by formulae, into a file called INFOROUT, which it places in the working directory.

The format is:

(PRINT String_15 is Formula)

  where

String_15 is a character variable with a length of no more than 15 characters, this limit being imposed by the format of SPEDAT.

It is printed in INFOROUT followed by the value of whatever appears in FORMULA.

First example

Library case w979 concerns transient flow of a turbulent combusting gas. The 'two-fluid model' of turbulence is employed, which implies that the hotter fragments of gas move faster than the colder ones.

Inclusion in the Q1 of the following three lines causes the difference of velocity at IX=75 to be computed and plotted:

(make of ud75 is 0)
(store1 of ud75 is 1u[75]-2u[75])
(print of veldiff ix=75 is ud75)

The corresponding INFOROUT file appears thus:


************************************************************
 IRUN    =         1  LIBREF =       979
 ISTEP   =        20  ISWEEP =         4
 VELDIFFIX=75    =  4.692078E-04
 ************************************************************
 ISTEP   =        40  ISWEEP =         4
 VELDIFFIX=75    =  2.592363E-01
 ************************************************************
 ISTEP   =        60  ISWEEP =         4
 VELDIFFIX=75    =  1.895071E+01
 ************************************************************
 ISTEP   =        80  ISWEEP =         4
 VELDIFFIX=75    =  2.894094E+01
 ************************************************************
 ISTEP   =       100  ISWEEP =         4
 VELDIFFIX=75    =  2.895671E+01
 ************************************************************
whereby it will be noted that spaces between DIFF and IX have disappeared (so legibility would have been better had under-scores been used, thus:
veldiff__ix

It is possible to print more than one variable into the same file. Thus the pressure difference driving the velocities at IX=75 can be printed by inserting three more lines in the Q1 file as follows:

(make of pd75 is 0)
(store1 of pd75 is p1[75]-p1[76])
(print of p1_diff ix=75 is pd75)

The INFOROUT file becomes, correspondingly:


************************************************************
 IRUN    =         1  LIBREF =       979
 ISTEP   =        20  ISWEEP =         4
 VELDIFFIX=75    =  4.692078E-04
 P1_DIFFIX=75    = -4.105164E-02
 ************************************************************
 ISTEP   =        40  ISWEEP =         4
 VELDIFFIX=75    =  2.592363E-01
 P1_DIFFIX=75    = -2.074691E+01
 ************************************************************
 ISTEP   =        60  ISWEEP =         4
 VELDIFFIX=75    =  1.895071E+01
 P1_DIFFIX=75    = -3.733529E+02
 ************************************************************
 ISTEP   =        80  ISWEEP =         4
 VELDIFFIX=75    =  2.894094E+01
 P1_DIFFIX=75    = -2.890381E+00
 ************************************************************
 ISTEP   =       100  ISWEEP =         4
 VELDIFFIX=75    =  2.895671E+01
 P1_DIFFIX=75    =  1.977539E-02
 ************************************************************

Line-printer plots in RESULT

Sometimes the INFOROUT file has so many items in it that trends are difficult to discern; it is then convenient to make use of the line-printer-plotting facility of PHOENICS.

In case w979, a patch called TIMEPLOT is already in use for plotting some standard variables. It therefore suffices to add the following lines to the Q1:

(print of veldif at timeplot is ud75)
(print of p1_dif at timeplot is pd75)

There then appears in the RESULT file the following plot:


PATCH(TIMEPLOT,PROFIL, 100, 100,   1,   1,   1,   1,   1, 100)
 PLOT(TIMEPLOT,P1_D,-3.964E+02, 5.151E-02)
   Variable    1 = VELD   2 = P1_D
     Minval=  0.000E+00 -3.964E+02
     Maxval=  2.896E+01  5.151E-02
     Cellav=  1.255E+01 -7.122E+01
 1.00 22222222222222222222+....+....+...11112222222222222
 0.90 +                   22          111 22            +
 0.80 +                     2        11  2              +
 0.70 +                      2      1   2               +
 0.60 +                       2    1   2                +
 0.50 +                       2   11   2                +
 0.40 +                        2 11   2                 +
 0.30 +                        221   22                 +
 0.20 +                        12    2                  +
 0.10 +                      11  2  2                   +
 0.00 11111111111111111111111..+..22+....+....+....+....+
      0   .1   .2   .3   .4   .5   .6   .7   .8   .9  1.0
 the abscissa is      ISTP.  min= 1.00E+00 max= 1.00E+02
from which the trends are easily perceived.

It should be mentioned that what lies between the 'of' and the 'is' of the (PRINT statements has had to be shortened in order to keep 'veldif at timeplot' and 'p1_dif at timeplot' within the 15-character limit; for even one excessive letter cases EARTH to terminate with the message:


PATCH command with TIMEPLO  name not found
 Invalid In-Form formula; run aborted.
An alternative (partial) solution would have been to reduce the length of the name of the TIMEPLOT patch.

It should also be mentioned that the arguments of the printed PATCH command which represent IXF,IXL,ITF,IYL,IXF,IZL are without significance for the In-Form-elicited plot.

Where the PRINT statements are located in file w979.htm can be seen by clicking here.

Printing arrays

Also the user-defined array can be dumped in inforout file at the end of account by means of (print statements. In 789 library case SINF and SOUT user-defined arrays are dumped in inforout file by means next statements 


 (print of phead_1 at SINF is phd1)
 (print of phead_2 at SOUT is phd2)

9.3 Coefficients, residuals, corrections and exchange coefficients (gammas)

Contents:
  1. Coefficients
  2. residuals
  3. corrections
  4. exchange coefficients (gammas)
  5. manipulating coefficients

  1. Coefficients

    Users who are interested in the finite-volume equations solved by PHOENICS may print, and manipulate, terms which enter those equations.

    The typical form these equations is seen by clicking here.

    The terms which may be accessed are:

    The In-Form statements which enable them to be accessed have the form:

    (STORED of name is AXCO(varname))

    where:

    A complete set of examples can be found in input-library case 788

  2. Residuals

    The equation imbalances, i.e. the residuals, may be obtained in a similar manner; but for them the In-Form Statement is:

    (STORED of name is RESI(varname))

    Such statements are also to be seen in case 277.

  3. Corrections

    Solving the finite-volume equations produces "corrections", i.e. quantities which should be added, cell-by-cell, to the values of the solved-for variables in order to reduce the imbalances in the equations.

    To gain access to them, the appropriate statement is:

    (STORED of name is CORR(varname))

    Examples of accessing residuals and corrections are to be found in library cases: 249, concerned with 2D flow in a square cavity, and 768, concerned with 3D flow in a water heater.

    If on-line, click here for the temperature field, the residual field, and the correction field for case 249.

    Because the solution is well-converged, the values of both the residuals and the corrections are very small. This accounts for the irregularity of the residual field, of which the values have been reduced to the round-off error of the computer.

    This method of displaying residuals and corrections is more convenient than the older-established method, which involved giving the variable of which residuals and corrections were required a special name, ending with the % sign. That method however is still available.

    Warning

    It will sometimes occur that the corrections are printed as zero. The explanation is that the iterative computation will have stopped before the prescribed value of LSWEEP because the residuals had fallen below the reference value; therefore the solver, which is where the corrections are computed, may not have been entered.

    The cure is to set NPRINT to some value well below that of the number of sweeps at which solution terminated.

  4. Exchange coefficients (gammas)

    Also of interest to those who study the workings of the numerical-solution process are the exchange coefficients, i.e. diffusivities times densities, which enter (together with convection contributions) into the calculation of aN, aS, aE, aW etc. These too may be accessed by way of an In-Form statement, which is in this case:

    (STORED of name is GAMM(varname))

    This feature is illustrated in case 788.

  5. Manipulating the coefficients, etc

    Like other 3D-stored variables, the coefficients and other quantities mentioned in the present section may be:

    These possibilities give the user great power to intervene, if he or she wishes, in the solution process.

9.4 Eliciting debug

In-Form is supplied with extensive debug facilities, for the investigation of suspected errors.

These facilities are activated by use of the "read Q1" facility. Specifically, the Q1 file is supplied with, starting in column 3 or greater:

The full list of features is:

FULL
for all the following
FORMULA
for displaying the formula being parsed
INITIAL
for initial-value settings
STORED
for stored-value settings
MAKE
for the MAKE facility
PROPERTY
for property settings
SOURCE
for sources
LINE
for linearization aspects
XGRID
for grid-related settings
YGRID
ZGRID
TGRID
INFOB
for In-Form objects
MOFOR
for moving objects

As is obvious, debug of a particular kind is activated when t follows the feature name, and deactivated by f.

An f following debug deactivates all debug features.

All debug features are f by default.

In-Form debug print-out is governed by the same indices as is the older-established debug from EARTH, i.e. that elicited by the PIL variable debug, namely izdb1,izdb2, etc.

Library case case 768 provides an example.

9.5 Tabular Output

In-Form can produce tabular output in comma-separated-variable format to named files. A new line can be written at the end of each sweep, or at the end of each time step. The values written to the files can be the outcome of any In-Form formula. There is no limit to the number of files

Syntax

The command to produce a sweep-wise table file is:

(TABLE in file_name is GET(form1,form2,...,formn) with HEAD(head1,head2,...,headn)!SWEEP)

The command to produce a time-wise table file is:

(TABLE in file_name is GET(form1,form2,...,formn) with HEAD(head1,head2,...,headn)!TIME)

  where

file_name is the name of the file to be created. If the filename is given the extension .csv, it will be directly recognised by Excel.

The GET function retrieves the values of form1 - formn and writes them to the table file. There is no limit on the number of variables that can be written. form1 -formn represent any valid In-Form construct. They can be single real values, elements of an array, the evaluation of a formula, whatever is required.

The HEAD function supplies the column headers to be written to the first line of the table.

For example, adding the line

(TABLE in monplt1.csv is GET(P1[1,3,3],P1[NX,3,3],P1[1,3,NZ-5]) with HEAD(P1_1,P1_2,P1_3)!SWEEP)

to library case 274 produces the file monplt1.csv, which contains:

ISWEEP, P1_1, P1_2, P1_3
     1,  0.000000E+00,  0.000000E+00,  0.000000E+00 
     2,  7.819997E+01,  6.381281E+01, -1.904133E+01 
     3,  9.748657E+01,  7.934592E+01,  3.729689E+00 
     4,  9.297382E+01,  7.512841E+01,  2.528054E+01 
     5,  8.867683E+01,  7.146969E+01,  3.346389E+01 
     6,  8.672485E+01,  6.953475E+01,  4.156276E+01 
     7,  1.030840E+02,  8.589959E+01,  8.495282E+01 
     8,  1.524511E+02,  1.357139E+02,  1.641428E+02 
     .
     .
   195,  4.161576E+02,  3.990614E+02,  3.937202E+02 
   196,  4.161576E+02,  3.990614E+02,  3.937201E+02 
   197,  4.161576E+02,  3.990614E+02,  3.937201E+02 
   198,  4.161576E+02,  3.990614E+02,  3.937201E+02 
   199,  4.161576E+02,  3.990614E+02,  3.937202E+02 
   200,  4.161576E+02,  3.990614E+02,  3.937202E+02

This can then be easily imported to Excel (Click on 'Insert', then 'Charts'.) The data can be plotted as a 'Scatter' chart to produce a convergence plot like this:

The files themselves are written at the end of each sweep or each timestep, so that should the run crash for any reason, the data up to that point will be available. It is also possible to look at the files during the run, to 'see how it is getting on'. If something looks out of order, the run can be stopped and investigated.

Back to main contents

10. Replacing READQ1

(a) REALREAD, INTREAD and LOGREAD

The READQ1 features of PHOENICS allow variables which do not form part of the PIL set to be transmitted to EARTH. However, each variable requires one extra line to be inserted in the Q1 file.

In-Form allows up to 20 variables to be transmitted in a single line (possibly with 'continuation' effected by the $ sign), by means of the REALREAD, INTREAD, and LOGREAD statements.

Their use is illustrated by the facility (introduced with PHOENICS-3.5) for changing turbulence-model constants, which is described here,

Suppose, for example, it were desired to employ the different constants:
CMU =0.6 CD =0.2 C1E =1.5
C2E =1.92 AK =0.4 EWM =9.0

This could be effected by inserting in the Q1 file the line:

((REALREAD turconst is 0.6 0.2 1.5 1.92 0.4 9.0)

When the satellite reads this line, it places in Q1EAR the line:


 SPEDAT(SET,REALREAD,TURCONST,C,0.6&0.2&1.5&1.92&0.4&9.0)
which is echoed in RESULT; and in EARDAT the line:

 REALREAD  TURCONST       C0.6&0.2&1.5&1.92&0.4&9.0
This is then acted upon by the sequence of coding starting with IF(GETREALS in the subroutine INIVST, which duly interprets what it finds and records its work by printing the following in the RESULT file: 

 CMU     = 6.000000E-01 CD      = 2.000000E-01
 C1E     = 1.500000E+00 C2E     = 1.920000E+00
 AK      = 4.000000E-01 EWAL    = 9.000000E+00
This example has shown how real variables may be transmitted. Integer and logical variables are transmitted by use of INTREAD and LOGREAD statements in the corresponding manner.

(b) Discussion

The following points need to be understood by those wishing to exploit this powerful new means of transmitting simulation-defining data:

Back to main contents

11. In- Form and the VR-Editor

(a) Historical background

(b) Editing In-Form statements via the menu

The question has been answered by providing "In-Form" buttons in all appropriate menu panels of the VR-Editor, which access a newly-created 'In-form editor'.

One such button is shown here, for the top panel.

When that button is pressed, the Inform Editor appears.

Similar buttons appear on lower-level panels of the VR-Editor user-interface.

(c) Example; library case 360

There now follow several screen-capture images which show stages in the editing of the moving-body trajectory.

The existing Group 13 statements are viewed here

They are then changed by way of Notepad-like editing actions to this.

When they are what the user wants, they are saved.

This action places them in the phxx file which the VR Editor uses to store items which must be written to the final Q1, the relevant part of which is seen here:


  Echo InForm settings for Group 13
  inform13begin
char(xce,yce,zce,radius,gravt)
char(vel,times);
   ** Definition of the first moving In-Form Object
   SOME COMMENTS : Radius doubled; Gravity halved; That is all
radius=.5*2; gravt=9.81/2     ! Changes made on this line only
vel=10.;times=tim
xce=0.5+:times:*:vel:

(d) The future of the Inform Editor

Back to main contents

12. Adjustment of terms in differential equations

The GROUP 12 feature of PHOENICS allows the diffusion, convection and source terms in the differential equations solved by PHOENICS to be altered from their standard formulations.

In-Form can effect more extensive modifications of these terms; morever it does so without the use of special patch names.

12.1 How to modify diffusion and convection terms

The (MODDIF ...) or (MODCON ...) keywords of In-Form are placed at the beginning of an In-Form statement, the purpose of which is to introduce new value of diffusion or convection terms into the balance equations of solved-for variables, i.e. those which have featured in a preceding SOLVE(), or SOLUTN(name,y,y,....) statement.

The recalculation will be executed only at internal cell faces of the domain area; for updating at domain boundaries, the MODDIF and MODCON statements can not be used.

The complete format of the In-Form MODDIF and MODCON statements is:

12.2 How to modify built-in source terms

Similarly to the previous section the (MODSOR ...) keyword of In-Form is placed at the beginning of an In-Form statement, the purpose of which is to make adjusment of value of built-in source terms into the finite-volume equations of solved-for variables.

The complete format of the In-Form (MODSOR statements is:

In modsorq1 case In-Form is used to simulate flow near the thin pipe grid which is placed horizontally at north faces of cells for each iy=iysh. The diameter of pipes is very small and equal diam=0.01 m. Thus the pipe grid is a subgrid object. It is supposed that the pressure drop at pipe grid can be calculated by formulas 

  dP = f*2*rho*vel^2, [N/m^2]
  f=0.33*Re^(-1/5)    and
  Re=abs(vel)*diam/enul
The resistance at the pipe grid is simulated by updating the built-in source term of equation for v1 variable at iy=iysh cells by means following two lines 

 PATCH(MSOR1,CELL,1,NX,IYSH,IYSH,1,NZ,1,1)
 (MODSOR of V1 at MSOR1 is ANORTH*.33*REYN^(-0.2)*2*RHO1*VLSQ)

End of main text of In-Form Documentation

Back to main contents