PHOENICS-Direct SimScenes:
The Apps for PHOENICS


Brian Spalding, November 2013

  1. Introduction
    1. What is a SimScene
    2. A prelminary list of Simscenes
    3. How to run a SimScene
  2. The rationale
  3. How SimScenes relate to PHOENICS
  4. What is PHOENICS-Direct
  5. A typical SimScene
  6. How to acquire a SimScene
  7. How to create a SimScene
    1. General features
    2. Using a standard format
    3. The typical directory structure
    4. The parameterised Q1 file
    5. Assisted writing of Q1 files.
    6. The scene.xml file
    7. The PQ1 editor
    8. Other aspects of SimScene creation

1 Introduction

1.1 What is a SimScene?

A SimScene simulates fluid- and heat-flow in a pre-selected set of situations, the particular parameters of which are further selected by its user. It does so by transmitting the user's requirements to a powerful but hidden 'simulation engine' and by presenting the latter's responses in a user-understandable form.

The 'engine' is CHAM's PHOENICS software package; and this is an embodiment of the science of Computational Fluid Dynamics. SimScene users however need no knowledge of these.

A SimScene can be thought of, by analogy with the 'apps' which abound for smart-phones and tablet computers, as an 'App for PHOENICS'. The following slide from a recent lecture illustrates the concept:

A SimScene consists a package of unique-to-it text and graphics files, together with the needed-by-it members of the general PHOENICS family. There is no need for the ordinary SimScene user to know anything about these; but the more-inquisitive few will find a brief description here.

1.2 A preliminary list of Simscenes Currently-available SimScenes include those which may be seen by clcking on the following hyperlnks:

1.3 How to run a SimScene

Activating the file start.bat in the main folder of the SimScene launches a SimScene run, which brings to the screen an image such as (for the Labyrinth SimScene) the following:

The content of the central part of this 'top page' of Labyrinth, is the start of a descriptive document which is specific to it. The buttons and tabs along the top of the page, however are present in all SimScenes; and is their functions which will be explained in this 'how-to-run' document.

The three tabs

The first tab simply brings back the top page when something else occupies the screen. The third does nothing when clicked on; but it displays the name of the file inspected after the 'view'  button has been pressed.

A mouse-click on the second tab, 'Inspect or modify input data', evokes the following image:

This is the first of several menus, by means of which the user enters, in the white boxes, the parameters which he selects.The entries may be numbers, character strings or algebraic expressions; and in some cases, indicated by the presence of the downward-pointing arrow, they may chosen from a displayed pull-down list.

The menu shown is that named 'geometry'; and others may be activated by clicking on the other names in the list on the left. The contents of the white boxes are the defaults of the Labyrinth SimScene.

The buttons

  1.  operates only when an htm file with hyperlinks to other files is being viewed; it then performs the 'back-to-previous' function'.
  2.  activates the 'display or modify scenario' function, which allows the scenario in question to be viewed graphically and its geometrical attributes (only) to be altered.
  3.  activates the data-input (Satellite) and solver (EARTH) modules of PHOENICS, abd deposits the results of the simulation in the working directory.
  4.  opens a menu which enables a series of runs with successively altered input parameters to be launched.
  5.  causes the selected graphical-display module to be activated and to be ready to show whatever is dictated by a prepared-in-advance macro file.
  6.  activates the 'find' function, when, after the user has pressed the next button, he has selected the file which he wishes to view.
  7.  opens a window through which the user may browse for the file which he needs.
  8.  saves the file after it has been edited.
  9.  shows the list of saved parameter sets
  10.  provides access to .csv files
  11.  provides zoom feature ??????

2. The rationale

The reasons for bringing SimScenes into existence are set out in conference publications CHT12 and HEFAT9 and in the associated power-point presentations CHT12 and HEFAT9. A summary now follows.

The problem

PHOENICS possesses so many already-built-in features, and capabilities of adding new ones, that it is able to simulate an extremely wide range of processes; and it is also equipped with sophisticated data-input and results-display facilities.

However, so extensive have become its powers that 'learning-to-use-PHOENICS' has become a dauntingly complex and time-consuming task. In respect of PHOENICS as it was until recent years, the task can be begun by clicking here.; but there is much more now.

The solution

However it is only CHAM staff members who need, collectively, to know how to use the whole of PHOENICS. Users of PHOENICS, having at any time one particular simulation in mind, need to invoke only a sub-set of its capabilities; and for them PHOENICS has been made especially easy to use. This has been done by the creation of special packages for which the name ‘Gateway’ was first used, then ‘Simulation Scenario’, and now SimScene for short.

These have simple menu-type interfaces, which address the user in terms which he or she can reasonably be expected to understand. Pre-chosen default answers are diplayed; so the user has only to make changes where he or she wishes, as in the following example:

3. How SimScenes relate to PHOENICS

SimScenes thus relate to PHOENICS as does a TV-controller to the TV set and the world of programs which it can display; or as 'apps' do to 'smartphones'. Their users make the choices about what is to be simulated, by way of the menus. Then PHOENICS, behind the scenes, carries out their orders.

The menus are placed on the screen by the so-called 'PHOENICS-Direct' package, which translates the user's menu entries into instructions to PHOENICS in language which the latter understands. They define the calculations to be performed and how their output is to be presented to the user.

4. What is PHOENICS-Direct?

PHOENICS-Direct is thus a user interface for PHOENICS; but it differs greatly in motive and style from its predecessors, the Virtual-Reality Editor, and PRELUDE

The VR-Editor provides, for users who have learned its rules, access to a wide (but still partial) range of PHOENICS capabilities; by contrast PHOENICS-Direct, with its associated SimScenes, leads directly to just the capabilites that its current users require.

Moreover, PHOENICS-Direct menus can accept, as the VR-Editor can not, data entries in 'relational' form, as illustrated below.

Evidently, in this 'boundary-condition' menu, the inlet velocity is to be deduced from the Reynolds Number, and from property and geometry data which have been set elsewhere; and the inlet temperature is also specified indirectly by reference to the separately-set external temperature.

This relational-data-input (RDI) feature of PHOENICS-Direct is a very useful time-saver indeed..

PRELUDE also possesses RDI capabiliies; and it too can be provided with Gateways which focus on limited scenarios, The construction of these however has required a new input language to be learned, whereas PHOENICS-Direct accepts its instructions in the long-established PHOENICS Input Language, i.e. PIL, with which many of its users are already conversant.

At this point it is appropriate to argue that SimScenes will interest CFD practitioners of two distinct kinds.

Simscene users distinguished: (1) 'Nose-to-the-grindstone' users

Most engineers and environmentalists, although needing to benefit from the flow-simulating powers of PHOENICS, have too little time to learn PIL. They are the ones who until now have had to rely upon the VR Editor as their problem-set-up interface. The first part of this document (sections 1 to 6) is written with them in mind; for SimScenes greatly increase both the range of PHOENICS features which they can exploit and the ease of so doing.

(2) Their further-looking colleagues

Those of the second kind, having already recognised that the VR-Editor can write for them only an elementary dialect of PIL, have learned to make use of at least some of PIL's advanced features; and especially its RDI capabilities. Possibly they have even been creating therewith parameterised Q1 files, for their less-experienced colleagues to use.

Such persons will be pleased to learn that PHOENICS-Direct enables them to achieve their ends with much greater ease, and so may wish themselves to become SimScene creators. Among them will be:

Such would-be SimScene creators need neither profound knowledge of CFD nor the skills of the VR-Editor connoisseur. They do require some acquaintance with the PHOENICS Input Language; and they also need to know something about the behind-the-scenes workings of PHOENICS-Direct.

The latter is what section 7 is about.

5. A typical SimScene


One of the first SimScenes was TubeFlow, created in 2012; this was designed for persons interested in the steady flow of single-phase fluids through tubes of circular cross-section. Its descriptive document, which also contains much about SimScenes in general, can be accessed by clicking here .

6. How to acquire a SimScene

SimScenes are not integral parts of PHOENICS, to be supplied to its licensees whenever a new version is issued, They are best thought of as being akin to 'apps', to be obtained via whatever means, and on whatever terms, are offered by their creators.

At the time of writing, all SimScenes have been created by CHAM UK, to which a request should be addressed by anyone who wishes to acquire one. Those who already possess PHOENICS licences may obtain them, at the present time, free of charge. However they may be supplied to others, as stand-alone limited-capability PHOENICS versions, at finite charges which are nevertheless much lower than those of the standard full-capability PHOENICS.

The PHOENICS-Direct executable which is needed for all SimScenes, and the PQ1 Editor which is needed by all SimScene creators, are themselves such apps. They are obtainable from CHAM, but not necessarily free of charge.

7. How to create a SimScene

7.1 General features

The scenario and the purpose of the simulation

The creator of every SimScene starts by defining the item of equipment, or the physical process, which is to be simulated. An example might be the flow through a bank of finned tubes, illustrated below, such as are used in many heat exchangers,:

The ultimate reason for creating such a SimScene would be to assist heat-exchanger designers to choose tube-bank configurations and dimensions which would provide the required heat-transfer performance, without demanding excessive fluid-pumping power.

Selection of the parameters to be varied

In this is example, as in most, the dimensions can be described by way of numerical parameters, including, according to the configuration in question: Then the materials must be specified which constitute the tube and fin metals and the within-tube and between-tube fluids. Further scenario-defining parameters are the flow rates and theinlet temperatures and pressures of the two fluid streams.

Defining the quantities to be predicted.

Also to be enumerated are the desired outputs. Heat flux per unit volume and presure drop per unit length will certainly be among them; and it may well be decided that users would like to know not only their values for particular input condiitons, but also their coefficients of sensitivity to those conditions.

In addition to numerical output, graphical displays by way of graphs, contour diagrams and streamline displays, possibly animated, convey valuable information about the simulated equipment or process. For example, pictures of the following kind provide an insight into the internal workings of a heat exchanger that tables of numbers cannot convey.

Solution-control parameters

Although users of SimScenes need no knowledge of CFD, some of them surely will possess some knowledge; and they may wish to exercise it. Therefore menus will usually be supplied with a SimScene which allows users to vary at least a few of the numerical inputs which influence the equation-solving process . Numbers of grid intervals, and of solver-cycle iterations are likely to be among these; and the SimScene creator may see fit to provide access to many more, with of course suitable default settings which the unadventurous user may simply prefer to leave unchanged.

7.2 Using a standard format

PHOENICS will accept instructions about input, solution control and output that have been formulated in many different ways. However the tasks both of creating and of using SimScenes are faciitated by adopting a standard format for all, with only such omissions and additions as the special cases demand.

The TubeFlow SimScene can serve as a model. Its descriptive document explains that the items to be included in menus can be conveniently presented in ten groups, as listed here:

  1. General
  2. Geometry
  3. Variables solved
  4. Material properties
  5. Models
  6. Initial conditions
  7. Boundary conditions
  8. Output
  9. Computational grid
  10. Numerical

TubeFlow itself however has only nine groups, 'initial conditions' being absent because only steady-flow situations are considered.

Whereas uniformity of format facilitates human understanding, variations for the alleviation of boredom are permissible. Greater strictness is desirable however when it is the understanding of computers which is in question, as is true of one important aspect of PHOENICS-Direct. This concerns the way in which new PIL vriables are declared and set in the underlying parameterised Q1 file which has to be identical in content to the scene.xml file (to be described below) which embodies the menus.

This compatibility can be ensured if the human editor of both files exerts extreme care. But, if the PQ1 is written in accordance with certain precisely-defined rules, its compatible scene.xml can be produced automatically by the computer. Boredom is a small price to pay for such relief.

7.3 The typical directory structure

Although deviations are allowable, the directory structure employed by TubeFlow can also usefully be adopted as the standard; for this allows path-names to be copied from one SimScene for use by another with minimal changes. The structure is:






In the TubeFlow folder resides the batch file, start.bat, which activates this particular SimScene; and if Russian , Japanese, Chinese, etc are suported, of which PHOENICS-Direct is capable, the corresponding batch files start_ru.bat, start_ja.bat, start_ch.bat etc. are also present.

The file descr.htm resides in \tubeflow\docs, together with the images which it displays. This is the file of which the contents were made accessible in sub-section 2.1 above. This file is written by the SimScene creator in order to explain to its users what are the features of the current SimScene which distinguish it from others.

The sub-directories \working\ and \multirun\ are where the results of single and multiruns,respectively are to be found; and the user may find it useful to create to copy their contents to additional folders with similar names for the storage of results obtained at different times.

Favorite is of course the place where favoured settings are to be stored.

Finally the folder \input\ is the home of two important scenario-defining files. These will now be discussed

7.4 The parameterised Q1 file

The changing nature of the Q1 file

Since the soon after the launching of the first PHOENICS, in 1981, its equation-solver, EARTH, has been told what to do by way of instructions placed by its user in the file called Q1. This is an ASCII file, which can be created by any text editor; but the entries in it must conform to the rules of the PHOENICS Input Language, PIL.

At first this comprised a list of assignments of values to pre-defined variables, for example:

but later it was enabled to declare new variables and assign values to them too, for example:

Soon followed logical structures (IF_THEN_ELSE_ENDIF ; DO_ENDDO ; etc), graphics-display features and further utilities enabling complex fluid-flow-simulating calculations to be initiated.Year-by-year new features have been added, making present-day PIL an invaluable aid to the CFD specilist

Its nature is fully described in the relevant PHOENICS Encyclopaedia article, the main content of which will be supposed known to readers who wish to progress beyond this point.

In particular it will be supposed understood that PIL has a relational character which allows one item of input to be expressed in terms of, and so to depend on, another (as for example WIDTH depended on LENGTH above).

It is to emphasise this capability that the Q1s used by PHOENICS-Direct are called parameterised Q1s (PQ1s from now on). These too are the subject of lengthy Encyclopaedia articles

7.5 Assisted writing of PQ1 files.

Even the earliest version of PIL had too many capablities for ordinary users of PHOENICS to remember how to use them; and passing years made the task harder. Therefore menu-type interfaces have long been provided to relieve users of the burden of writing Q1 files for themselves. Thus in 1995 CHAM introduced its so-called Virtual Reality graphical user interface, the latest version of which, the VR-Editor, is still widely used today.

That GUI however, despite it many merits, is unable to exploit the full richness of the PQ1 possibiliities; which is why PHOENICS-Direct (PD from now on), which can do so, has been introduced.

The introduction of PD has influenced the way in which PQ1s are written; for it has necessitated a stricter adherence to formal modes of expression in order to allow the menu-related scene.xml files to be generated automatically.

A modern PQ1 contains three parts, namely:

  1. Declarations and default values of scenario-influencing settings of parameters;
  2. User-determined changes to (some of) those parameters, effected by reading a new file called frommenu.htm written by PHOENICS-Direct, containing a list of all parameters;
  3. PIL statements which process those settings and transmit their operational significances to the PHOENICS equation-solving and results-display modules.

The reading of the default and menu-set parameters is effected by a single line at the bottom of Part 1 of the PQ1, namely:

It is Part 1 which requires the strictest formalism; for it is this which is read by the PQ1 Editor (see below) in order to generate the second important scenario-defining file: scene.xml, which dictates what the user sees on the menu screen

As has been seen in sub-section 7.2, input parameters are conveniently organised in groups of more-or-less similar items. The entries in Part 1 of PQ1 must therefore be grouped in this way; and the grouping is then reflected in scene.xml.

In order to illustrate this, corresponding parts to the two files will be shown. First an extract from the PQ1 of the TubeFlow SimScene:

 XML-Group Geometry
real(xang) ! circumferential extent, radians
real(diam) ! tube inner diameter, m 
real(thck) ! wall thickness, m 
Next the corresponding part of scene.xml:

        <name>circumferential extent, radians</name>
        <name>tube inner diameter, m</name>
        <name>wall thickness, m</name>
The similarity of their contents is obvious, Their differences of form reflect the differing practices of the PHOENICS Satellite and PQ1 editor, which read the first, and of PD, which reads the second.

7.6 The scene.xml file

PQ1 has long existed; but scene.xml is quite new. Its purpose is two-fold:
  1. to provide the path-names of executables and batch files which PD must activate; and
  2. to tell PD what to present to the user in the form of a menu.
The whole of the scene.xml file belonging to the TubeFlow SimScene can be viewed , by clicking here, whereby it must be remarked that not all browsers display it in the same manner (or even at all). Its full path-name, for those who must therefore inspect it via a text editor, is /phoenics/d_sapps/tubeflow/input/scene.xml .

This file can, like the PQ1, be created by means of any text editor; and indeed the very first such files were created in this manner, However such great care is required to ensure that the necessary relationships between the two files are precisely established that a special editor for both has been created. Describing this is the task of the next section.

7.7 The PQ1 editor

When the PQ1 editor is opened, the top of the otherwise blank screen appears much like that of notepad as:

It is only when the help button is pressed that its much more powerful character starts to manifest itself, thus:

The whole content of the extensive help files can be explored by clicking here. Therefore it suffices to draw attention only to the fact that the macro and code-completion features make use of customisable files.

Specifically, although the relevant files, pq1ed.dci and, flies already contain most of the items needed by conventional SimScenes, they can be added to without limit by any SimScene creator with unusual needs.

A PDF document describing the PQ1 Editor extensively can be viewed by clicking here.

7.8 Other aspects of SimScene creation

The above description of the SimScene creator's tasks is far from exhaustive; but it suffices as a starting point. Those who desire more information can best gather it for themselves by inspecting in detail the TubeFlow example referred to in section 5.

Brief description of the files constituting a SimScene

The files are typically provided as one folder with four sub-folders as follows:
Click here to return to the main text.