Encyclopaedia Index

Contents list

VR Editor Main-Menu

The Main Menu is where all the domain-related settings, such as domain size, variables solved, physical properties, numerical and output controls are set. Any source which operates over the whole domain is also set from here.

The main menu is reached by:

All these methods bring up the Main Menu top panel.

Main Menu - Top Panel

This is the top panel of the main menu, and can be reached from any other panel by clicking on Top menu. It is the panel displayed whenever the Main menu is activated from the hand-set, and it is the only panel from which it is possible to return to the main VR-Editor environment.


From the Top menu panel, a Title can be set for the current case. This is a text string up to 40 characters long, which then appears in all the input and output files.

The buttons along the top of the panel allow the setting and modification of the case. In general, it is best to start at the top left, and work from left to right, top row then bottom row, as this minimises the chances of missing out settings.

The buttons perform the following functions:

The 'PIL command' line on each panel allows the entry of commands in the PHOENICS Input Language, PIL. This powerful facility should be used with care, as it may 'by-pass' menu settings.

The Help button on each panel gives a more detailed overview of the functions available from that panel - the text is broadly similar to that contained in this section of this document.

Help on individual data-entry boxes and buttons can be obtained by clicking on the '?' in the top-right of the window, and then clicking on the required item.

Some panels contain more lines than can be shown. In such at case, a Page Dn and Line Dn button will appear at the bottom of the panel. These scroll the panel down by a page or a single line to reveal the remaining options. The font and screen resolution influence this, so the menu panels may not appear exactly as depicted here.

Main Menu - INFORM

The In-Form editor allows commands in the In-Form language to be added to the model. In-Form allows the specification of:

by way of formulae placed in the data-input file. The In-Form editor provides a simple interactive means of creating and modifying the formulae.

Image: The In-Form Editor

Full details can be found in INFORM: TR 003.

Main menu - Domain Faces

Clicking on this button brings up a dialog from which boundary conditions can be applied to entire domain faces.

Xmin, Xmax, Ymin, Ymax, Zmin, Zmax denote the opposite faces of the domain in the X, Y and Z directions. The available options are:

These objects will appear on the screen, and will be listed in the Object Management Panel.The default names for these objects can be changed from the Object Specification dialogs as for any other object.

At a face, these options are mutually exclusive - selecting one will deselect any other selection. The objects are created with default attributes. The user must ensure that any non-default values, such as an inlet velocity or wall surface temperature, are set by opening the attribute dialogs for these objects and setting any required values.

Any PLATE, OUTLET or INLET objects which cover the entire face of the domain will be recognised as domain-face, and will cause the appropriate flags to be set to Yes on the above dialog.

For external wind-driven flows it will often be much easier to activate the WIND object.

The function of the WIND object is to provide boundary conditions representing the atmospheric boundary layer due to the wind at all faces of the domain in a self-consistent manner. The following conditions are applied:

Main Menu - Geometry


For Cartesian and Polar co-ordinates, this is the same dialog that is displayed by clicking on the Grid mesh button on the hand-set, then clicking on the mesh region to be changed. Region 1 in each direction is initially selected. Descriptions of how to modify the mesh are given in VR-Editor Hand-set, Mesh Toggle, and in Space and Time grids.

The settings are:

For Body-Fitted Co-ordinates, changes to the grid are made in the BFC menu.

Main Menu - Models

This panel controls the variables to be solved, and the models used.


Note that some of the options described below are reached by clicking on Page Dn.

Equation formulation, Simulation is, Lagrangian Particle Tracker (GENTRA), Solution for velocity and pressure, Free-surface models, Energy equation, Turbulence models, Radiation models, Combustion Models, Mean Age of Air, Solution control / Extra variables, Advanced user Options Edit InForm 7, Edit InForm 8

  1. Models - Equation Formulation

    This allows the formulation of the equations to be chosen. The options are:

    The main choice is between elliptic, parabolic and fully-developed. Elliptic is the most usual form, as it allows for recirculation.

    There is a further choice of staggered or collocated velocity formulation. In the staggered formulation, velocities are stored at cell face centres, in the collocated form they are stored at cell centres, just like pressure and temperature.

    The staggered form is usually best for Cartesian and polar grids, the GCV collocated for BFC. See also the CCM entry in the PHOENICS Encyclopaedia.

    Parabolic performs a marching integration suitable for flows with no recirculation, e.g. developing pipe flows or jet spreading.

    Fully-developed calculations will give the flow rate for a given pressure-drop, or the pressure-drop for a given flow, without any information on how the flow developed.

  2. Models - Single / Multi-Phase

    This option switches between single and multi-phase operation. If the domain is occupied by a single fluid, which does not change phase, or by several fluids which ARE ALWAYS SEPARATED by solid, the flow can be treated as single phase. If the fluid changes phase, or there are several MIXED fluids, then the flow must be treated as multi-phase.

    The available options are:

    The Encyclopaedia entry on Multi-phase flow gives more details.

  3. Models - Lagrangian Particle Tracker (GENTRA)

    This activates the GENTRA Lagrangian particle tracker, which is described in The Gentra User Guide TR/211. The particle tracker is an alternative way of treating multi-phase flows. It is suitable for dilute suspensions, where volume-fraction effects are small. Packets of particles are tracked through the domain. Each packet represents a large number of particles following this path. The particles can exchange heat, mass and momentum with the carrier fluid.

  4. Models - Pressure And Velocity

    This option switches ON or OFF the solution for the pressure variable P1, and the velocities U1, V1 and W1 (depending on the dimensionality of the problem). If the simulation is two-phase, then the second phase velocities U2, V2 and W2 will also be activated. If the grid dimensionality is changed later, the required velocity component( s) will be added or removed as needed.

    Pressure and velocity must be ON before it becomes possible to select Multi-Phase or Free-Surface models.

  5. Models - Solution For Swirl

    If the geometry is axi-symmetrical (two dimensional in the Y-Z plane), this option switches on the solution for the swirl component of velocity. (This button is only present for cylindrical-polar geometries.)

  6. Models - Free Surface Models

    The available free surface models are:

    The Scalar Equation Method (SEM) is good for overturning or breaking interfaces, but is restricted to very small time steps.

    Height of Liquid (HOL) can run steady-state, or with larger time steps but cannot deal with overturning interfaces.

    See also the Lectures on Scalar Equation Method and Height of Liquid.

  7. Models - Energy Equation

    The energy equation can be solved in one of two forms:

    The enthalpy form is often more suited to combustion applications, the temperature form to conjugate heat transfer. Internally, the equation is always cast in enthalpy form, so the units of the sources are always Watts.

  8. Models - Energy Equation, Total/Static

    By default, the Temperature form is set to 'Total', the enthalpy form to 'Static'. The static form includes the substantial derivative of the pressure and the kinetic heating terms in the energy conservation equation as additional source terms, the Total form does not.

    If the flow is highly compressible (high Mach number) the Temperature form should be switched to 'Static' otherwise incorrect solutions will be obtained. This is because all the property formulae require the static temperature.

    The Enthalpy form can be used in 'Total' form as long as a suitable temperature derivation is selected in the properties panel.

  9. Models - Turbulence Models

    The available turbulence models are divided into the following groups:

    All models are described in the POLIS Encyclopaedia under ' Turbulence', where each has its own descriptive article.

    Brief advice: use the simplest model which produces realistic results. In many cases, the CHEN-KIM model provides a reasonable compromise between accuracy and economy. If there are many walls (obstacles) present, the LVEL model will be even more economical, and also more accurate for coarse grids.

  10. Models - Radiation Models

    The following radiation models are available:

    They are described in full in the PHOENICS Encyclopaedia under ' Radiative Heat Transfer in PHOENICS'.

    WARNING: The 6-Flux and Radiosity models are not yet fully implemented in the Menu, especially with regard to the boundary conditions. Please use the ' User-defined' object attribute to set the boundary conditions described in POLIS. The IMMERSOL model is fully implemented.

  11. Models - Combustion Models

    The following combustion models are available:

    They are described in the PHOENICS Encyclopaedia under: ' Combustion', ' Reaction', ' SCRS', ' Extended Simple Chemically-reacting System',' CHEMKIN Interface'. There are examples in the 'Chemical-reaction library'.

    WARNING: Only the 3_GASES model is fully implemented in the Menu. The remaining models are not yet implemented in the Menu. Solution of the required variables can be activated through the Solution control - Extra variables button below.

    Please use the 'user-defined' object attribute to set the boundary conditions described in POLIS.

  12. Models - Mean Age of Air

    The AGE variable represents an estimate of the 'time since entry'. It is obtained by solving for a tracer, named AGE, which has a uniform source of 1/m3/s, and is zero at all inflow boundaries. If the flow were one-dimensional and steady, AGE would be equal to the time spent by local air particles in traveling from the entrance to the point in question.

  13. Models - Solution Control / Extra Variables


    This panel gives options to:

    See the POLIS Encyclopaedia entries on SOLUTN and TERMS for more information.

  14. Models - Advanced User Options

    This panel gives access to PIL settings from Groups 7 and 8 which are not covered by the other sub-menus of this panel.

  15. Models - Edit InForm 7

    This starts the In-Form editor with Group 7 selected as the current Group. Full details can be found in INFORM: TR 003.

  16. Models - Edit InForm 8

    This starts the In-Form editor with Group 8 selected as the current Group. Full details can be found in INFORM: TR 003.

Main Menu - Properties

From this panel, the main domain material can be chosen from the CHAM-supplied property libraries.

The domain material is the material that initially fills the entire solution domain. Regions of the domain can then be filled with other fluids or solids by creating BLOCKAGE objects, and selecting the required material for them.

The individual properties loaded from the library for the domain fluid can then be edited - changed. This is not possible for the properties used for blockages. If a blockage is assigned the ' domain material', it will automatically pick up the properties specified here.

The reference pressure and temperature values are always added to the calculated pressure and temperature before use in property calculations. The reference temperature is set by choosing Centigrade (reference temperature is 273) or Kelvin (reference temperature is 0) for 'Temperature units'.

Image: PROPERTIES using Property Tables

The 'Ambient pressure' and 'Ambient temperature' entries set the pressure and temperature prevailing outside the domain. These values can be used, if desired,  to set the pressure and temperature at all INLET, WIND, WIND_PROFILE, OUTLET, FAN and PRESSURE_RELIEF objects. 

When 'Initialise from ambient' is set ON (the default), the initial values of pressure (P1) and temperature (TEM1) are always made consistent with the ambient values set here.

When 'Set buoyancy from ambient' is ON (the default), the reference temperature for Boussinesq buoyancy is set to the ambient temperature, or for density_difference buoyancy, the reference density is calculated from the ambient pressure and temperature.  

The 'Property storage' button allows the field values of the properties to be placed in the EARTH output file PHI, so that they can be plotted in the viewer.

Turning the property tables OFF allows the individual properties to be set directly.

Image: PROPERTIES not using Property Tables

This panel is also accessed from the Edit properties of current material button on the previous figure. For each property, a pull-down list of all available options is provided. The available options are listed in Encyclopaedia.

Main Menu - Initialisation


This panel provides options to:

Unless explicitly set in this panel (or set to ambient), initial values for Temperature, Enthalpy, turbulence model quantities and solved-for passive scalars will be taken from the inlet values supplied at the first inlet defined.

NB. When solving for passive scalars where there is one inlet with a finite inlet value and one or more inlets or outlets with a value of 0.0 it can be important to set the initial value explicitly to 0.0, in case the domain is initialised to the finite inlet value.

If the inlet value of a scalar is 1.0, but the majority of the domain is filled with scalar=0.0, it is very important to explicitly initialise the relevant scalar(s) to zero.

If there are more than five stored/solved variables, the > (and <) buttons can be used to scroll through all available variables.

Although the names of the restart and cut-cell files may be displayed as upper-case, the Earth solver will convert them to lower-case.

If 'Restart cut-cell values' is set to NO, the values in the cut cells will retain their initial values as set here on restart, and the named file will not be read. This is useful when restarting a PARSOL=T run from a PARSOL=F run when the pbcl.dat file will be empty. It can also help avoid problems restarting parallel runs when the processors cannot agree on how many cut cells there are.

Main Menu - Sources

Image: SOURCES Panel

This panel allows the creation of whole-domain sources, which are not attached to an object. All sources or boundary conditions which do not apply to the whole domain must be attached to an object, and set through the appropriate object attribute dialog box.

The 'Cyclic boundary conditions' button gives the options:

Cyclic boundaries are then imposed between the first and last rows of cells in the IX direction, for the slabs indicated.

The MOFOR ON/OFF button (which only appears for Transient cases) activates the Moving Frames Of Reference model, which allows objects to move through the domain. When turned ON, two extra buttons are displayed. One allows the user to browse for the MOF file, and the other to edit it using the currently-selected file editor. The MOF file controls the motion of the objects. For more details, click here.

The panel also allows built-in whole-field sources to be set, such as:

The following buoyancy options are available

  1. Constant
  2. Density_difference
  3. Boussinesq Approximation
  4. Linear_in_2_scalars

All are described in the Encyclopaedia under 'Gravitational body forces'. In brief:

Option 1 applies the full gravitational force

Option 2 uses a reference density, and should be used if the density is not constant;

Option 3 uses a reference temperature, and should be used if the density is constant but the temperature is variable

Option 4 allows the buoyancy force to be a function of any two solved scalars.

If 'Set buoyancy from ambient' on the Properties panel is set to ON, the values needed for Options 2 and 3 will be taken from the ambient temperature and pressure set there.

To create a new whole-field source click on 'Advanced settings PIL'. If this is not visible ,click on 'Page down' to show the next page of options.


Enter the name of the PATCH in the 'New' box and click 'Apply'. A new PATCH will be created; the TypeCoefficient and Value can now be set as required. Clicking on PATCH number will cycle through the available Patches. The > (and <) symbol next to Variable scrolls through the list of available variables, if there are more than five.

To start the In-Form editor with Group 13 selected as the current Group, click on Edit InForm 13 on the main sources panel. Full details can be found in INFORM: TR 003.

Main Menu - Numerics


The main entries on this panel allow the total number of iterations ( sweeps) over the whole domain, and the global convergence criterion to be set.

In transient cases, the 'Vary with time' button leads to a dialog from which the number of sweeps per time step can be changed with time or time step. Up to 15 bands of sweep settings can be made. If more are required, or the conditions for variation are more complex InForm can be used.

The submenus give options to:

Numerics - Relaxation Settings


Relaxation is a technique for slowing down possibly excessive rates of change. It does not affect the final solution. In many cases, convergence will be very hard to obtain without suitable relaxation settings. The relaxation methods available are described in the Encyclopaedia article on RELAX.

The default relaxation settings turn the Automatic Convergence Control (CONWIZ=T in the Q1) ON.

MAXINC sets the maximum increment (change) from iteration to iteration for each variable.

Reference velocity sets a typical velocity in the domain (usually based on a typical inlet velocity)

Reference length is a typical length scale for the case, usually based on the domain size.

The two reference quantities are used to estimate an initial timescale. In many cases, the default values work quite well. For large-scale external aerodynamics, for example flow over a city, where the domain may be kilometers in size it can be very important to set the reference length to an average domain size otherwise convergence may be unacceptably slow. The WIND object will do this automatically, otherwise the user should do so manually.

In this mode, any false time step settings for velocities are ignored - the solver will set linear relaxation of 0.5 for all velocities that have false time step relaxation. If the relaxation for velocities is switched to LINEAR, the user-set values will be used.

If no settings are made for the other variables, the solver will set linear relaxation of 0.5, except Temperature (TEM1) which is set to 0.25.

For fire simulations, the maximum increment for temperature (TEM1) should be reduced from the default value of 1000 deg/sweep to, say, 10 deg/sweep, otherwise convergence may still be difficult. If the expected velocities are very small, the maximum increments for the velocity components should also be reduced. If a FIRE object (only available in FLAIR) is detected, and the relaxation for TEM1 is the default (no user setting has been made), the maximum increment for Temperature is automatically reduced to 10 deg/sweep.

'Reset solution defaults' resets all the solver control variables to their default values, so that the Automatic Convergence Control can operate in full.

If the Automatic Convergence Control is turned off, the relaxation settings can be set individually.


Typical values for false time step relaxation may be estimated from the governing time-scale of the process under consideration. Very often, values based on residence time work well. These can be calculated from:

Domain residence time ~ Domain length / Inlet velocity

Cell residence time ~ Domain length / Inlet velocity / Number of cells

False time step values within an order of magnitude of these will usually be effective.

For the velocity variables, it can be advantageous to use the Self-Adjusting Relaxation AlgoritHm (SARAH). This is activated by setting SARAH to a value > 0. Values around 1.0 have been found to work well.

False time step relaxation can be applied to all SOLVEd variables, except Pressure, by setting the RELAX flag to FALSDT. False time step values are trapped to always be greater or equal to zero.

Linear relaxation can be applied to any SOLVEd or STOREd variable by setting the RELAX flag to LINEAR. A value of 0.0 implies no change will be allowed, 1.0 will allow the full change to take place. Linear relaxation values are trapped to lie in the range 0.0 < value < 1.0

In BFC, linear relaxation of Pressure of the order 0.7 or less is often required.

Numerics - Iteration Control


The POLIS Encyclopaedia entries on the individual items explain their function.

The default linear equation solver is based on Stone's Strongly Implicit method. To use the Conjugate - Residuals - Gradient solver for any variable, set ENDIT for that variable to GRND1. Circumstances under which this may be advantageous include:

Numerics - Limits on Variables


This panel allows minimum and maximum values for all SOLVEd and STOREd variables to be set. The POLIS Encyclopaedia entries on the individual items (VARMIN, VARMAX) explain their function.

Numerics - Differencing Schemes

By default, the selected differencing scheme applies to all SOLVEd variables. The default scheme is the HYBRID scheme.


Clicking on 'Set schemes individually' allows the selection of different schemes for different variables.


The complete list of scheme names is:

LUS          FROMM          CUS         QUICK          CDS
SMART        KOREN          VANL1       HQUICK         OSPRE
VANL2        VANALB         MINMOD      SUPBEE         UMIST
HCUS         CHARM

These are described in the POLIS Encyclopaedia entry ' SCHEMES FOR CONVECTION DISCRETIZATION.

Main Menu - GROUND

This panel sets special variables for use in GROUND. The switch for PLANT is also on this panel.

Main Menu - Output


This panel gives options to:

Output - Pause at End of Run

This has three settings:

Output - Monitor Graph Style

The solver can display convergence-monitoring information on the screen as graphs of:

Output - Field Printout


The settings for OUTPUT are:

The POLIS Encyclopaedia entries on the individual items explain their function.

If 'Suppress all field printout' is ticked, the field printouts will be suppressed but the OUTPUT flags will not be changed, so that settings are not lost should the suppression be removed. In the Q1 this appears as SPEDAT(SET,OUTPUT,NOFIELD,L,T) in Group 19. The main reason for suppressing the printout is to reduce the size of the RESULT file for huge cases.

Output - Dump Settings


Once switched ON, this controls the sweep (for steady-state) or time-step (for transient) frequency with which flow fields are written to disk file.


The setting for OUTPUT for each variable determines whether that variable is written to the saved file or not. This can potentially save a lot of disk space by only writing the variables of real interest, but would also prevent such a 'thinned-out' file from being used as an Earth restart file.

In steady cases, the start letter for the dumped intermediate files is set to S. To also save the initial field, enter CSG1=SWIN in the PIL Command input box at the bottom of the dialog.

In transient cases, intermediate flow fields can be dumped at regular time-step intervals. The names of these files are generated from a user-supplied letter, and the step number - e.g. A100. If the base name ends in 'IN', e.g. AIN, then the initial conditions are written to A0, and the Viewer will start the transient display at time t=0.

Note that if the start letter(s) are set to SW for a transient case, files will be dumped for the requested sweeps of the current step, not the final fields at the end of the time steps. Thus S1, S2, S3 etc will be the solutions of sweep 1, sweep 2, sweep 3 of the current time step, and will be overwritten on the next time step. This is intended as a debugging device to aid the investigation of poor convergence at a particular step.

The letter Q cannot be used as a base for saved intermediate files as there will be a danger of overwriting the Q1 input file!

If the case is one- or two-dimensional in X and Y (i.e. NZ=1), leaving the start-letter blank causes Earth to write out a special file called PARPHI, in which the Z direction is used for time. Each Z plane is the solution for that time step.

If PARSOL is active, a cut-cell data file will be produced at the same time as the intermediate flow field file. The names of these files are generated as PBC<letter><number> - e.g. PBCA100.

Although the names of output and intermediate files may be displayed as upper-case, the Earth solver will convert them to lower-case.

By default, field dumping starts at the first sweep or step, and continues throughout the run. The Limits button leads to a screen on which the first and last sweep or step for dumping can be set. It is very rarely necessary to set such limits, and users are advised not to do so unless specifically required.

Output - Derived Variables


Placing the Skin friction coefficient, Stanton Number, Shear stress (actually friction velocity squared, equivalent to shear stress divided by density), Yplus (non-dimensional distance to the wall) and heat transfer coefficient (in W/m2/K) into 3-D storage allows them to be plotted in the Viewer or PHOTON, as well as appearing in the RESULT file.

Note that the heat-transfer coefficients are only calculated for turbulent flow. To make them appear for laminar cases, the turbulent viscosity should be set to a very small value - say 1.0E-10.

The friction force components SHRX, SHRY and SHRZ are used in the force-integration routines to add the friction force to the pressure force acting on each object. If they are not stored, the integrated force will only contain the pressure component. Storage for the friction forces can also be activated from the Forces and moments ' Settings' panel.

If the Mach Number is stored, the Total or Stagnation Pressure (PTOT) is calculated from:

Ptot = (P1+PRESS0)*(1+((γ-1)/2)*M)γ/(γ-1)

If the Reference Pressure PRESS0 (Main Menu - Properties) is set to zero, the total pressure may go below zero, leading to an error-stop.

If the Mach Number is not stored, the total pressure is calculated from:

Ptot = (P1+PRESS0) +0.5*Vabs2

Output - Forces on Objects

When this is 'On', the Earth solver will integrate the pressure forces over all objects and print the force information to the RESULT file. Control over which objects are included in these calculations is provided on the 'Settings' panel. If the friction force components (SHRX, SHRY and SHRZ) have been placed in 3D store, the force integration will include them.

The moments of the X-, Y- and Z-direction forces about the X, Y and Z axes are calculated, and the point of action of the force is deduced.

The force and moment calculations are only valid for Cartesian and cylindrical-polar grids. The forces and moments are always printed in the Cartesian co-ordinate system. Positive moments are clockwise in a right-handed co-ordinate system.

For each face-cell (cell containing some surface area) of each blockage object, the force is calculated as:

fpi = P1*Ai                       : the pressure force, where Ai is the surface area normal to direction i (X,Y or Z)

ffi = SHRj*Aj +SHRk*Ak     : the friction force, where Aj, Ak are the areas parallel to direction i

fti = fpi + ffi                      : the total force in each cell.

The forces are then summed over all the face-cells of an object to give the total force on the object:

Fti = sum(fti)

The moments about the X,Y and Z axes are then calculated as:

mx =              fty.Z - ftz.Y

my = -ftx.Z            + ftz.X

mz =  ftx.Y - fty.X

where X,Y and Z are the distances of the cell face centre from the X,Y and Z axes. The moments are summed over all face-cells of an object to give the total moment about each axis:

Mi = sum(mi)

The moments of the individual forces about each axis are also summed:

Mzx = sum(ftx.Y); Myx = sum(-ftx.Z)

Mzy = sum(-fty.X); Mxy = sum(fty.Z)

Mxz = sum(-ftz.Y); Myz = sum(ftz.X)

The point of action of the integrated force (the position where the moment is zero) can now be deduced from expressions like:

Xm = Myz/Ftz; Ym = Mzx/Ftx; Zm = Mxy/Fty

Similar summations are performed over all objects to give the total force acting, the total moment, and the point of action of the total force.

Further control over what is printed is provided on the 'Settings' panel.


The settings are:

Image: FORCES SETTINGS panel with Drag Coefficient

The drag coefficients are then printed as:

Cdi = Fi/(0.5*RHOref*Velref*Arearef,i)

Mx' = Fy.(Zm-Zu)-Fz.(Ym-Yu)

My' = -Fx.(Zm-Zu)+Fz.(Xm-Xu)

Mz' = Fx.(Ym-Yu)-Fy.(Xm-Xu)

Main Menu - Help

This displays the section of TR/326 relevant to the current panel. If the POLIS files cannot be found on the local computer, you are offered the opportunity to open the file from the CHAM website. Note that the location of the POLIS files is set in the CHAM.INI file as described here

Main Menu - OK

This returns to the main graphics window, and applies all the changes made in the main menu. This button only exists on the Top menu.

Contents list