PRELUDE Tutorial BEGIN1: The basic essentials
In this tutorial you will be taught:
- how to activate PRELUDE,
- what you can expect to see when you do, and
- how to examine and change the attributes of the
objects in this (rather empty) first scenario.
It is presumed that you already know what PRELUDE is, and why it is important to users of PHOENICS. If not, please click
The most convenient way of running this and all other tutorials is
to view it in a narrow window on the left of the screen and to
perform the operations in a larger PRELUDE window on the right.
The tutorial is rather long; and, because it describes the mechanics of PRELUDE in rather abstract terms, you may find it too boring to study each section form start to finish.
If so, skip the remainder and jump to the next section, or even to tutorial 2. This one can always be returned to when you feel the need.
- How to start
- The Menu bar
- The Tool bar
- Loading a Gateway
- The complete object tree
- The domain object
- The clipper object
- The cellgrid object
- The axes object
- The camera object
- The 'variables' object
- Concluding remarks
1. How to start
PRELUDE can be activated in several ways. The simplest is to click the
icon on the desktop.
You should then see an image of which the top part is :
and the lower part is empty.
We shall now examine the functions of the buttons, one by one.
2. The Menu bar
Below the Title bar which contains the words 'Prelude Controller' lies the Menu bar: File, Edit, etc., clicking on any one of which lead to further
menus, as follows:
- 'File' leads to a menu concerning opening and saving 'cases' and related files (a 'case' being a flow-simulation scenario with which PRELUDE is concerned).
- 'Edit' leads to: Undo, Redo, Set working directory, font size and 'Interface Theme'.
- 'Options' leads to various commands concerned with changing appearance and with running PHOENICS modules.
- 'Create' leads to commands which will be used in adding objects to the scenario.
- 'Cases' leads to a list of the cases which have been loaded during the current PRELUDE-using session.
- 'Tools' enables the standard toolbar to be displayed or hidden.
- 'Help' leads to the explanatory documents.
3. The Tool bar
Below the Menu bar lies the Tool bar, on which the buttons have the functions
explained by the following notes:
- Prepares PRELUDE for loading an unnamed new case. It has the same effect as 'File, New Case'.
- Prepares PRELUDE for loading a named new case. It has the same effect as 'File, Open'.
saves the input-data files
Q3) for this case.
toggles the object-tree, which shows and permits selection (by clicking on the name) of any
object in the scene
displays variables which may be used in relationships, and their current values. It is an
alternative to the 'functions' box (see below), and is preferable in that it does not obscure the graphics screen.
enables the attributes of the currently-selected object to be inspected and, if
hides the currently-selected object.
hides the currently-selected object and all its 'child' objects
presents images of shapes which may be inserted
copies the currently-selected object
pastes the currently-copied object
deletes the currently-selected object
presents view of the scene on the XY plane
presents view of the scene on the YZ plane
presents view of the scene on the ZX plane
presents a three-dimensional view of the scene
undoes last action
redoes an undone action
shows the contents of a file in which all actions undertaken by PRELUDE
in the present session are recorded.
4. Loading a Gateway
Below the tool bar lie boxes which will appear whenever you first
activate PRELUDE, or when, in the middle of a session, you click on the
new-case icon .
The first contains a white space into which you can type the name
which you wish to assign to the
new case which you are about to create.
The second line gives you a choice of several boxes. If you choose the
one called 'Load Gateway', you will be led to a menu presenting the
'gateways' provided by CHAM. Clicking on one of these
causes PRELUDE to load a scenario typical of the selected class of flow
situations, together (often) with a 'store cupboard' containing objects which
you are likely to find useful.
In the present tutorial, you will shortly be invited to choose the gateway called 'Beginner'.
Clicking on the other enables you to browse through the appropriate set
of the directories on your machine, so as to select a
Q1, Q3 or
'PRELUDE-script' file (with .psc extension) from which to start your
The nature of these files will be explained in later tutorials
You will now be shown how to load a gateway; thereafter the tutorial
will enable you to explore the contents of a very simple one,
learning to use, as you do so, some of the tools which you will need when you
later employ PRELUDE for more complex tasks.
- Replace 'case0' by typing in the white space, say, 'tut_1', or
any other character string (but WITHOUT BLANK SPACES).
- Now click on 'Load Gateway' and then select 'Beginner', which is the
elementary Gateway designed for beginners. You should see,
in the graphics window:
namely a red-outlined box which represents the domain into which, in due
course, will be placed the objects which are to be studied.
Also visible are three coloured planes touching the sides of the domain,
and red, green and blue arrows emanating from a green sphere.
These represent respectively the 'clipper planes' and the coordinate axes.
- If the background colour is not white or grey, click on 'options' in
the menu bar, then 'Set Background Colour'; then choose white or grey,
in order that all features become clearly visible.
If the font size is too large or too small for you, now is a
suitable time to change it by use of the 'Edit' button of the menu bar.
PRELUDE is an 'object-oriented' program. You can now examine what
objects constitute the case under consideration. by
clicking on the 'object tree' icon
toolbar. You should then see:
in the top-left-hand corner of the window.
5.1 The domain object
The "+" sign close to the word 'domain' signifies
that the domain object is a 'parent', having some 'child objects' dependent on it.
The whole 'family' of objects is displayed by clicking on the "+"
sign next to domain, and then on all further ones which appear. You will then see:
From the point of view of a person who is interested in simulating physical processes by means of PRELUDE and PHOENICS, the objects are, it may be felt, diasappointingly abstract.
If that is your feeling, simply note that objects are arranged in families, and that the details can be found here if you need them.
Then proceed to the next topic by clicking here,
We shall discuss the children later; first however we shall
explore the attributes of 'domain' itself.
To do this you must 'select' it, by clicking on the box containing the
word DOMAIN, an action which results in the words 'Selected DOMAIN
Attached to Domain' appearing in the top right-hand corner of the window.
[DOMAIN is attached to itself because it has no 'parent']
Click on in the
tool-bar. You will see this in the top part of the window:
'Size' is the only tab of interest for our present purpose.
From this picture we deduce that the dimensions of the box in the three
coordinate directions, X, Y and Z, are each 1.1 units of length (which we
may think of as metres; but that is not of significance to PRELUDE).
You will now be shown the six methods which PRELUDE provides for
modifying these dimensions.
The subject is important because the same
methods are used for all other numerical quantities which PRELUDE
If however you feel that six methods are too many to learn about all at once, click here
whenever you are eager to proceed to the next topic of the tutorial.
You can always return later to learn about the methods which you have skipped.
Method 1: typing numbers
- Replace the 1.1 in the xsize box by typing in 1.2. Then click on
any other white space.
You will see that:
- The 1.2 is printed immediately to the right of the white space;
- The image of the box in the graphics window is appropriately
Now type in a series of other numbers, large and small, positive and
negative, observing the corresponding changes.
Method 2: Recovering earlier values
- Now right-click in the white space. You will see the following
list of all the numbers which you have entered.
Click on any number in the list. Then that is the number to which
'xsize' will return.
Method 3: Pressing mouse buttons
- At the right-hand end of the white spaces, up-and-down arrows are to be
seen. Move the cursor to one of these and press the left-hand mouse
button. The numbers within and to the right of the white space will
change continuously (stopping at zero if you are pressing the down
arrow); and the image of the box in the window will change
It should be noted that the upper and lower limits of the numbers, and their intervals, have been preset in the 'script' which set up the beginner's Gateway. They are not, unless special measures are taken, under the PRELUDE user's control. This will be explained in later tutorials.
Method 4: Typing expressions
- PRELUDE also accepts input by way of Fortran-like expressions.
To show this, restore 1.1 to the xsize space; then replace the 1.1 in
the 'ysize' space by 'xsize(domain)'. Then click on some other box.
The only visible change will be that the up-and-down arrows on the right
of the ysize space become greyed-out, signifying that they can no
longer be used. (Check this by trying to use them).
Now type into the zsize space (perhaps by first placing 'xsize(domain)' into the paste buffer) 'xsize(domain)*0.5' and then click on some other box (which is a general requirement after an entry, and so will not be further reiterated below). Then the zsize
up-and-down arrows will be greyed-out; 0.55 will appear to the right of
the space; and the z-dimension of the drawn image will change
Now change xsize to 1.2. The three size dimensions of the domain box
(to the right of the white spaces) are now 1.2, 1.2 and 0.6 . They have
all changed together; and you have seen your first
demonstration of the relational capabilities of PRELUDE.
Method 5: Introducing functions
- You may have noticed that, when you placed the cursor in one of the
white boxes for the first time, three boxes labelled 'Function', 'Object Name' and 'Insert Function' appeared beneath the toolbar.
Use of these, which is by no means essential for the beginner, enables settings to be made by way of click-cut-and-paste operations instead of typing.
Clicking on the first of these and pointing to 'X...' with the mouse cursor reveals this:
This is a list of x-related functions which may be used in expressions, once an object name has been selected as their argument.
- Suppose that it is desired to place in the zsize box the expression 'ysize(DOMAIN)' without having to type the characters. This involves using ysize as the 'function' and 'DOMAIN' as the object name.
To do so, first
place the cursor in the 'zsize' white space, and high-light its
contents, by double clicking, as though you were about to type over it.
Then click on 'y...' in the 'functions' drop-down menu and then 'ysize'
You have now indicated which function you wish to use.
Next, click on 'DOMAIN' in the 'Object Name' menu, thus selecting this as argument
click on the 'Insert Function' button.
Then the desired 'Ysize(DOMAIN)' will appear in the Zsize white space.
Click on any other space; then observe that the
right-hand number and the y-dimension of the domain box in the drawn image change appropriately.
- It should be noted that the 'right-click trick' (i.e. recovering earlier values, see Method 2) works in the same way for expressions as it does for numbers. To check this, right-click in the zsize space. You will see:
Method 6: Introducing new variables and/or expressions.
- To learn about this method, click on the box marked 'Functions' in the menu bar
at the top of the graphics window. You will then see the following:
Replace 'newname' by, say, 'dimension'; press 'OK'; then click on the down arrow beside the left-hand box and select the variable-type: 'real'.
In the same way introduce the real variables 'length', 'width' and 'height'. Your screen should now look like this:
By default the newly-introduced functions are set to zero.
- It is now time to fill
these boxes with some meaningful data, for example as follows:
Your screen should now look like this:
- Type 1.1 instead of 0
in the 'dimension' space.
- Double-click on the white space opposite 'length' and then on the word 'dimension' in the 'functions' list.
- Do the same for the 'width' and 'height' boxes.
- Now highlight the '1.1' in the 'xsize' box of the 'DOMAIN' attributes.
- Click on 'LENGTH' in the functions list; and see it appear in the white space.
- Make the corresponding actions so as to ensure that 'WIDTH' and 'HEIGHT' appear in the other two spaces.
Finally click on the 'Graphics' tab and the familiar graphics window will appear with the 'Size' tab open. You should there see that the domain sizes in the boxes are specified parametrically by 'LENGTH', 'WIDTH' and 'HEIGHT', respectively, and their true values are given to the right of each size box.
Being now at the end of this long section of the tutorial, you should bear
in mind two things:
- You have learned, by concentrating exhaustively on a single
aspect of data input, things about PRELUDE input generally. It will not
therefore be necessary to go into such detail in later tutorials.
- Although the tutorial has shown you things which you could
do, that does not mean that PRELUDE forces you to do any of them. Do not
therefore suppose that the practical use of PRELUDE will be laborious.
It is not.
Let us now examine other objects in the scenario provided by the
First, so as to make an entirely clean start, close PRELUDE by clicking
on the top-right-hand white cross in its red box.
Now re-start PRELUDE, set the casename to be tut_1a, say, and re-load
the beginner gateway.
Click on the 'tree' icon; and, this time click also on the + next to
DOMAIN, and then on the + close to AXES. You should then see:
Evidently the DOMAIN has several children dependent on it; and one of
them, called AXES, has three children of its own.
5.2 The clipper object
- First select 'CLIPPER' by clicking on it, or on its name in the tree.
Its three perpendicular planes will then be outlined in white (which is
not easy to see unless the back-ground colour is different from white).
Such outlining is carried out for every object that is selected, except
in the case of the domain, which is special in several ways.
Changing the size
Now click the 'red-tick' icon in the toolbar. You should then be presented with a greater number of buttons than for 'DOMAIN,
as shown here.
- First click on 'Size'; then, by clicking on the up-and-down arrows or by typing entries into the white boxes, confirm that the x, y and z dimensions can be changed in the same manner as before to get a picture like this:
- However, 'CLIPPER', and all other objects which you will later introduce, also allow rotation and changes of position, relative to the domain, as you are now invited to investigate.
Rotating an object
Click now on 'Rots'; then click and hold one of the
up-and-down arrows to the right of 'Xrot', 'Yrot' and 'Zrot'.
The object will be seen to rotate about one of the coordinate axes to result in pictures like this:
This behaviour is general; i.e. it will occur for any selected object
(except the DOMAIN, which lacks both the 'Pos' and 'Rots' tabs because it cannot move relative to itself).
Typing numbers (or valid expressions) into the white spaces will be found to have effects analogous to those pertaining to 'Size'.
Leave the 'Irotation' box untouched at present. Its use will be explained later, in connexion with physical objects.
Changing the position of 'CLIPPER'
Another tab which was not possessed by 'DOMAIN' is 'Pos', standing for 'position'.
In order to study this, first return 'X rot', 'Y rot' and 'Z rot' to zero;
then click-and-hold on the up-and-down arrows, meanwhile observing the motions. You should generate pictures like this:
Typing numbers, or valid expressions, in the white boxes should also have corresponding effects on the clipper-plane positions.
5.3 The CELLGRID object
Flow-simulation calculations proceed by regarding the domain under consideration as consisting of a set of contiguous 'cells' arrayed in 'grid format.
PRELUDE treats this array as an object which it calls 'cellgrid'.
- Although the geometrical aspects of the CLIPPER object have been
discussed, what it is used for has not. Its use can however be
illustrated by first restoring the xpos, ypos, ypos, xrot, yrot and zrot of 'CLIPPER' to zero, the xsize, ysize and zsize to 1; and then selecting another object, namely 'CELLGRID', by clicking
on its name in the object tree.
What is then shown is the following image:
which reveals that the domain now contains three sets of planes,
perpendicular to the
x-, y- and z-directions, the intersections of which define a set of rectangular
non-intersecting boxes which can serve as the 'cells' of a
Now select again the clipper object; then click-and-hold on the up-arrow
of xpos. Holding for long enough causes the grid wholly to disappear, as though the movement of the low-x clipper plane has 'swept' it away
If xpos, ypos and zpos are each set at 0.5, the picture is as
The lower-dimension parts of the grid have been 'clipped off', and only
the upper parts are visible.
This makes plain the purpose of the clipper object: it is to enable the user to render invisible those parts of the scenario which obscure his view.
Lastly, restore the clipper object to its original position; then click on
the 'Rots' tab and on the up-arrow of 'Y rot' until its value is 45.
Then the following picture will appear:
It will be useful to experiment with various combinations of positions
and rotations in order that the power of the clipper object can be
It may further be mentioned that more than one clipper object can be
introduced (via 'Create' in the top menu bar); but that is for
expert users of PRELUDE, not beginners.
In order that you can see the grid more easily, set the x-size, y-size and z-size of the clipper object to 0.1, say, but still with the 45-degree y-rotation.
What you will see is:
It can now be seen that the CELLGRID object does not in fact display all
the edges of the cells, but only those which lie on the domain
5.4 The axes object
The camera object (of which there can be more than one) provides a means of controlling how the objects in the graphics window are displayed.
Let us now turn attention to the AXES family of objects, having first
hidden the CELLGRID object by way of the
hide-object icon, and with the CLIPPER object remaining small.
Clicking on AXES in the object tree, and on the 'attributes' icon will
Then click on the Attributes tab.
You will see:
Here an important word to notice is 'GROUP'; this implies, despite the
somewhat inappropriate buttons on its 'attributes' panel, that its sole
function is to act as parent to its children.
It does have the attributes of rotations, position and size. Increasing the last of these, by way of the 'up' arrows, shows that the object 'AXES' is visually represented by the x-, y- and z-direction arrows emanating from a sphere centered on their point of intersection. The sphere is white when 'AXES' has been selected; otherwise it is green.
- You can set a new position for this object (i.e. a new position of their reference point) if in the open 'Pos' tab you change Xpos and/or Ypos and/or Zpos from zero set by default to any other value. When doing so, you will observe that all three attached objects, AXISX, AXISY and AXISZ will move as 'obedient children' should do. They have been truly 'grouped'.
You can also rotate this object around any axis you prefer, if you open the 'Rots' tab so as to generate pictures like this:
Note that in this picture, the 'Pos' tab and the 'Rots' tab panels are shown in the same picture only to give the idea of the changes made.
There is more that could be said about these objects and how they were created; but it would be of interest only to advanced users. Therefore, instead, we continue our inspection of other objects on the tree.
However, it is not essential for new users who have experience of other graphics programs to understand it completely at the beginnning; for many, the way to move and rotate mouse images by means of the mouse appears to be obvious and satisfactory.
If you are one of those, practice for a few minutes your mouse-manipulations skills; then, in order to proceed at once to the next section, click here.
The following section is provided for the others.
- Click now on the object-name 'CAMERA0'. What you should see is:
Now click on the attributes icon. The panel will come into view with the 'Pos' tab open.
Here the x,y,z position coordinates refer to where the camera (i.e. the imaginary optical device which creates the screen image) is situated in the space defined by the x,y and z axes of the domain.
- In order to understand the significance of these numbers, watch how the image changes as you change these values successively to, say:
2, 4, 6;
4, 8, 12.
These make the domain more distant; but it is still being viewed from the same angle.
2, 2, 2;
4, 4, 4; and
8, 8, 8.
With these, the cubical box is being viewed along its diagonal through the origin.
- Now click on 'Attributes' so as to see the following image which enables the 'field of view' to be changed by way of a slider bar:
Click on the slider and move it to the left, so as to reduce the field-of-view index above it; then the object will appear to move nearer. Moving the slider to the right has the opposite effect.
- Further attributes are:
- the coordinates of the point of attention (Xatt, Yatt, Zatt) at which the
camera is 'looking', i.e. the coordinates in 'domain space' of the centre
of the screen; and
- the 'up' boxes, wherein:
- a '1' in one of the boxes and '0' in the others indicates which
axis is vertical on the screen;
- a '1' in each of the 'x' and 'y' boxes, with '0' in the 'z' box makes
the bisector of the angle between the 'x' and 'y' axes vertical;
- the other possible pairs of 1's act similarly;
- in general, finite values in all boxes act as 'weighting factors' to
determine which line through the origin will appear as vertical;
- placing the same number in all three boxes causes the picture to disappear.
Temporary changes of camera position and field of view.
The position coordinates of the camera which you have just set are now in PRELUDE's memory.
However, you may also make changes to the viewed image by clicking and holding the mouse buttons and then moving the mouse cursor.
These do not affect the memorised quantities.
The effects are more easily learned by experience than by reading instructions; but the following words may assist:
- clicking and holding the right button causes mouse-cursor movements to produce a 'zoom' effect;
- clicking and holding both left and right buttons simultaneously causes the object to perform vertical, horizontal or diagonal translations which follow those of the mouse cursor; and
- clicking and holding only the left button, enables mouse-cursor movements to cause the object to rotate.
Experiment with such mouse actions for as long as you like. Then click on camera0 in the object tree. You will find that the view returns to that which existed before you began those actions.
Those actions have had only a temporary effect.
This is however not true of field-of-view changes made by means of the slider. In order to restore the field of view, you will have to move the slider back to its original value, i.e. 45.
Adding a camera
It may be that, among the views which you created by zooming, translating and rotating, there is one to which you would like to return. This is easily contrived, as follows:
Before terminating discussion of the object tree it is proper to remark that there is one object which has not yet been discussed, namely 'variables'.
This object will indeed not be discussed in the present tutorial because it concerns the CFD calculations which PHOENICS will be asked to perform.
This is a matter for later tutorials.
You are of course at liberty now to click on any buttons which interest you, so as to
see what they do.
However, your time may be better spent by proceeding to the further tutorials which will take you systematically
through all the functions of PRELUDE and its role as the New User Interface