PRELUDE Tutorial BEGIN1: The basic essentials


In this tutorial you will be taught:

Preliminary advice

It is presumed that you already know what PRELUDE is, and why it is important to users of PHOENICS. If not, please click here.

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.


  1. How to start
  2. The Menu bar
  3. The Tool bar
  4. Loading a Gateway
  5. The complete object tree
    1. The domain object
    2. The clipper object
    3. The cellgrid object
    4. The axes object
    5. The camera object
    6. The 'variables' object
  6. Concluding remarks

1. How to start

PRELUDE can be activated in several ways. The simplest is to click the [chopin.gif] 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:

3. The Tool bar

Below the Menu bar lies the Tool bar, on which the buttons have the functions explained by the following notes:

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 [newdoc.gif].

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 interactive session.
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.

  1. Replace 'case0' by typing in the white space, say, 'tut_1', or any other character string (but WITHOUT BLANK SPACES).

  2. 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.

  3. 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.

  4. 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.

  5. PRELUDE is an 'object-oriented' program. You can now examine what objects constitute the case under consideration. by clicking on the 'object tree' icon [treen.gif] in the toolbar. You should then see:


    in the top-left-hand corner of the window.

5. The complete object tree

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']

  1. Click on [immov.gif] 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 handles.

    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
  2. Replace the 1.1 in the xsize box by typing in 1.2. Then click on any other white space.
    You will see that:

  3. Now type in a series of other numbers, large and small, positive and negative, observing the corresponding changes.

    Method 2: Recovering earlier values
  4. Now right-click in the white space. You will see the following list of all the numbers which you have entered.


  5. Click on any number in the list. Then that is the number to which 'xsize' will return.

    Method 3: Pressing mouse buttons
  6. 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 correspondingly.

    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
  7. 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).

  8. 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 correspondingly.

  9. 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
  10. 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.

  11. 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

    Finally 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.

  12. 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.
  13. 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:


  14. 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.

  15. It is now time to fill these boxes with some meaningful data, for example as follows: Your screen should now look like this:


  16. 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.


  17. Being now at the end of this long section of the tutorial, you should bear in mind two things:

Let us now examine other objects in the scenario provided by the 'beginner' gateway.

  1. First, so as to make an entirely clean start, close PRELUDE by clicking on the top-right-hand white cross in its red box.


  2. 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

  1. 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.

  2. Changing the size

    Now click the 'red-tick' icon [immov.gif] in the toolbar. You should then be presented with a greater number of buttons than for 'DOMAIN, as shown here.


  3. 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:


  4. 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.

  5. 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.

  6. 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'.

  1. 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 CFD grid.

  2. 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 shown:


    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.

  3. 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:


  4. It will be useful to experiment with various combinations of positions and rotations in order that the power of the clipper object can be appreciated.

    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.

  5. 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 boundaries.

5.4 The axes object

  1. Let us now turn attention to the AXES family of objects, having first hidden the CELLGRID object by way of the [hideseob.gif] hide-object icon, and with the CLIPPER object remaining small.


    Clicking on AXES in the object tree, and on the 'attributes' icon [immov.gif] will show:


    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.

  2. 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.

  3. 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.

5.5 The camera 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.

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.

  1. Click now on the object-name 'CAMERA0'. What you should see is:


    Now click on the [immov.gif] 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.

  2. 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.

  3. 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.

  4. Further attributes are:
  5. 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:

    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.

  6. 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:

5.6 The 'variables' object

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.

6. Concluding remarks

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 of PHOENICS.