The purpose of this document is to explain how to use the VR-Editor and VR-Viewer of PHOENICS. The place of these executables in the PHOENICS world can be seen from the following image, extracted from
phoeexec.htm. Here they are enclosed in red.
It may be concluded therefrom that the Editor is one of several means at the user's disposal for writing the input-data file,
Q1, which instructs PHOENICS about what it should do; and the Viewer is just one of the means for displaying the results as graphical images.
Their two functions are entirely distinct; but they happen both to be carried out with the aid of the satexe.exe executable; which is why, perhaps unwisely, they are documented together.
Both Editor and Viewer can be operated either interactively or in response to instructions provided by files, as indicated here. However it is mainly the interactive mode which is of concern here. That is why an earlier statement of purpose was phrased, somewhat narrowly, as:
The purpose of this document is to describe in detail all the control buttons and
switches available in the VR-Editor and VR-Viewer.
As the 'VR' in their names indicates, both modules originated at time (1995) when 'Virtual Reality' was a popular (albeit variously defined) concept. The history of their creation can be read here.
It will be found below that the executable comprising the VR-Editor and VR-Viewer is also referred to as the VR-Environment. This refers to nothing more than the fact that, in either Editor or Viewer mode, the user has some top-menu-bar options which permit switching from one module to the other; or indeed to activate other PHOENICS modules. This capability is not unique; the same is true to some extent of PHOENICS-Direct; and still more of the PHOENICS Commander.
The major part of the present document was written long before either the Commander or Direct existed; which explains and may excuse the, as it now seems, somewhat self-centred style of its language. That having been said, it is still important that present-day users of TR326 should understand its limitations as well as its capabilities, as expressed In the next few paragraphs.
Why the VR-Editor was created
The PHOENICS Input Language , PIL, came into being in 1981, when data input via Fortran statements was abandoned; and the first users thought the labour of learning PIL to be a trivial price to pay for the benefits which CFD conferred. They edited their Q1 files by hand.
Their successors however demurred; and to assist them a menu-type interface was devised which enabled data-items to be set, one-by-one, with less strain on the memory. The Q1 file was still written; but behind the scenes, invisibly to the users.
The use of this interface too was, after some time, felt to be burdensome; and so a so-called "2D menu" was created, which enabled its user to proceed more freely. At this time the "virtual-reality" notion was becoming popular; and the amalgamation of all those ideas resulted in the Satellite executable's being able to present to its users a graphical interface very similar to today's VR-Editor.
The manner in which the VR-Editor was created
The creators of the VRE GUI, as it was called (GUI standing for Graphical Use Interface), acted as though:
- Each user would enter all the input data which PHOENICS needed for a specific flow simulation by way of its dialogue boxes.
- The entries would be recorded in a Q1 file, before the simulation was performed; and their equivalents in solver-understandable terms would be written, as before, into the EARDAT file.
- The manner of recording would allow re-reading of the Q1, followed by further interactive modification of input data, and launching of a subsequent flow-simulation run.
- Q1 files which were not records of dialogue-box interactions could also be read by the VR Editor; but their contents would be re-written in record-of-dialogue form.
- Information regarding the newly acceptable 'VR-objects' of which the shapes were described by the corner co-ordinates of surface-fitting 'facets', were conveyed to the solver by a new file called FACETDAT.
Enthusiasm was high, and progress rapid. But hindsight-assisted consideration enables some negatives to be discerned, namely:
The so-called protected mode was later invented precisely so as to limit such misfortunes.
- The Editor was designed to write Q1s in which only the simpler PIL constructs were used. It spoke what might be called "Basic PIL".
- Consequently, when it re-wrote any 'advanced-PIL' statements in Q1 supplied to it, for example those involving declarations of new variables or if-then-else logic which are so valuable for multi-instance series of runs, it replaced them by their single-instance equivalents.
- It did not even keep a copy of what it had read; therefore unwary writers of well-wrought multi-instance Q1s often lost their work
Some consequences to be aware of
Users should therefore understand that the VR-Editor sometimes seems to 'have a mind to its own'; by which is meant that the instructions which it transmits to the solver do not always conform entirely to those which the user prescribed. Some examples will now be given:
- A user, wishing to place the monitoring point near the middle of the domain might insert in his Q1 file the statements:
ixmon=nx/2; iymon=ny/2: izmon=nz/2
The VR-Editor knows arithmetic but not algebra. Therefore the ixmon, etc. values will be right on the first occasion; but if the user subsequently changes nx, ny or nz, they will be wrong.
- Nor, of course does the Editor allow users to insert expressions (for example nx/2) in its dialog boxes. Only numbers can be accepted.
This limitation of the VR-Editor does not apply to the more modern menu-offering modules: PQ1-editor PRELUDE and PHOENICS-Direct; which is why they are recommended to new users of PHOENICS.
- Further, the Editor by default modifies whatever grid the user has himself defined so as to accord with its creators' views of what variation-of-fineness distribution will give optimal numerical accuracy. Since those views were formed in days in which solid objects were more likely than not to be grid-aligned, many users nowadays prefer to deactivate the Editor's efforts by inserting by hand-editing the statement:
nogrid=t into their Q1 files. Then they can choose the grid-distributions which they prefer.
- Finally it should be mentioned that the user who wishes to inhibit all un-called-for interventions by the Editor can do so by inserting the still-more powerful statement:
Remarks about some of the further sections of this document
What is an object?
In the early VR days it was something one could imagine holding in one's hands: it was three-dimensional; and probably solid.
Then two-dimensional inlets and outlets began to be called 'objects'; and in the course of time the only sure definition became, implicitly: an object is whatever collection of data items one may associate with one of the entries in this highly miscellaneous
It appears to be desirable to classify these objects in a meaningful way; but this has not yet been done
Most of the further sections have been left without updating for many years; but, even though the first paragraphs of section 11 have been slightly modernised, the hand-editing of Q1 files is so important nowadays that more should be written here, as follows:
Nevertheless it should be acknowledged that PQ1 writers have been able to deduce from the contents of section 11 how to write files to which the PHOENICS satellite reacts correctly (See for example the "labyrinth" SimScene).
- This section does not make the purpose of its provision perfectly clear. Its tone is factual, with the tacit preamble: "This is what is done." But about why it is done, or why it is done in this way, there is complete silence.
- The doubt is compounded by the fact that only half of the story is told. It is true that the statements described are to be found in the Q1 files; but they are not those which convey the information to EARTH. These are the SPEDAT lines which are printed in the Q1EAR and EARDAT files, and which are ultimately echoed in EARTH.
- If section 11 were intended therefore to assist the human editor of parameterized Q1 files, therefore, it would be better to skip entirely description of the > OBJ lines and to explain what SPEDAT-format lines would more-economically convey his or her wishes.
- To provide the corresponding document, linking each of:
would be truly to assist the PQ1 writer. The present document leads in another direction, without apparent advantage.
- verbal description
- dialog-box representation
- SPEDAT representation