1.1 What is Relational Data Input?
To place in the input file:
is direct input.
To place in the input file:
is relational input, because setting of a single parameter (here NX) has the effect of setting others (here NY and NZ) which are related to it.
Direct input allows the setting up of single-instance flow-simulation scenarios, Relational input enables its users to set up classes of scenario, of which instances are selected by way of user-chosen parameters.
This is made possible by the long-existing PHOENICS Input Language (PIL, for short), augmented by the more-recently-established In-Form facility.
A full account of the development of the Relational-Data-Input capability is contained here in the PHOENICS Encyclopaedia article on the so-called Q1 files, of which the kind now in question are called PQ1s, so as to emphasise their Parameterised Relational nature.
Parameterised Q1s are described
here in the just-mentioned
article, the start of which may be accessed by clicking
Perusal of this article would be a valuable, but not essential, preliminary to the present tutorial.
PQ1s are ASCII text files. They can be created in two ways, namely:
The present tutorial, which is the first in a series, is devoted to method 1.
- by direct use of a text editor, by persons conversant with PIL; and/or
- by use of the Phoenics RELational Utility for Data Editing,
PRELUDE, which can be used without knowledge of PIL.
1.2 For whom are these tutorials intended?
As has been explained in the above-mentioned Encyclopaedia article, PHOENICS is designed for two kinds of user, namely:
- those whose prime interest is in the physical phenomenon which they are simulating, and its practical significance for design or process control.
Such users are usually too busy to learn PIL or to create specialist input devices.
They require such devices, e.g. menus and dialog boxes suiting their special needs, to be created for them.
They are referred to as 'menu-users' below.
- those who do wish to create such menus and dialog boxes, perhaps for the
use of their less-knowledgable colleagues.
Such users are willing to learn enough of PIL, and of In-Form, to enable them to achieve their objective.
They are referred to as 'menu-creators' below.
The present series of tutorials is designed for the second of these two classes of user.
It will therefore introduce the elements of PIL and of In-Form in a step-by-step manner, explaining their usefulness and describing the rules which govern them.
It will also, where appropriate, point out where further information can be found in the PHOENICS Encyclopaedia and other documentation.
A typical tutorial will:
- Focus attention on a PQ1 which already exists in the PHOENICS Input file library.
- Explain the PIL and In-Form features which it exemplifies, illustrating the effects they have on the computed results.
- Show how alterations or additions made by editing the text of the PQ1 affect those results.
- Show how the inclusion of further user-interactive devices can extend the power of the menu-users to extend their flow-simulating capabilities.
The present tutorial is constructed in precisely that manner, the PQ1 in question being case 163 of the core library.
The present file, which represents Part 1 of the tutorial, deals with the first two of the above items. Items 3 and 4 will be dealt with in Part 2 of the tutorial, which is provided in a separate file.
2. Q1 for the case 163
The Q1 for this case can be opened if you click
A file very similar to it is also discussed at
in the above-mentioned Encyclopaedia article on q1 files.
We shall analyze its statements to facilitate your understanding and
ability to create Q1 files of your own. It will be good if you arrange to have this tutorial and the Q1 in question both open.
TALK=T;RUN( 1, 1)
This is the first line of the file. It should be also mentioned here that only the lines which start either in the first or second column are regarded by SATELLITE as active statements. The lines starting in columns 3-68 are treated as comments.
TALK=T tells SATELLITE to "converse" with the user,
i.e. to start an interactive session.
RUN(1,1) instructs SATELLITE to stop at the first STOP line: only those PIL statements which follow this line up to the first STOP will be read and processed by SATELLITE.
2.2 In the second part of the Q1, some information is to be found between markers DISPLAY and ENDDIS.
starts in the third column of Q1 and enables its writer to explain to users what kind of the case they are going to deal with, as all of the lines following it are displayed on the screen, until the marker ENDDIS, also starting in the third column, is encountered.
To open Encyclopaedia for more information click here.
The present case concerns the simulation of heat conduction in a steel slab of 0.1 m thickness, internallly heated by 1. kW/m**3 of electric power, with both its faces held to 0.0 deg Celsius. It also comprises 4 sub-case numbers (caseno) which add additional features in succession.
This part also contains some explanation of using markers saveXbegin and saveXend, where X is the number of a group these markers are used in to protect its specific information. It has been already explained here that input data in Q1 files are systematized in accordance with 24 groups.
Here however it should be mentioned that items which have come into existence since the Q1 structure was first formalized many years ago, namely those concerned with debug and VR-object data, are nowadays all regarded as falling into a 25th group. Therefore save25begin and save25end may be encountered.
2.3 GROUP 1 that follows is connected with setting the title and other preliminary data for the Q1 file under consideration. Pay attention that this line is not an active statement as it starts in the third column.
On the other hand, the command TEXT(Steady conduction in electrically-heated slab, which follows, is active and is used to transmit up to 40 characters of text following the open bracket, that will be printed under the GROUP 1 part of the result file after simulation. Click here to find more about it.
2.4 The next part of the file is the one for GROUP 3, and as its title shows it deals with specification of the X-direction grid creating a uniform one for the calculation domain. This part of the Q1 file is also protected by the markers
save3begin and save3end.
- The next part of the file is the one located between markers save1begin and save1end. To consult the Encyclopaedia about 'save', click here.
The general form of presentation is saveXbegin and saveXend,
where X is any integer number between 1 and 25 as has been mentioned earlier.
These markers are placed in Q1 files, starting in the third or higher column, to indicate the beginning and end of entries which must be preserved from being obliterated by the VR Editor. For more information look in the Encyclopaedia article on the 'protected mode' of SATELLITE operation.
It has been stated in the beginning that apart from the basic (default) case this file comprises 4 more sub-cases with additional features differing by their attribute, being the case number (caseno).
- The next line in this section declares caseno to be integer and this is quite obvious as this variable is introduced only to distinguish one sub-case from another.
- The next line is simply a text that explains what is to follow, i.e. what messages are to appear on the screen.
- Next are several mesg commands used to transmit text after an opening round bracket, to the screen during interactive session. Introducion of this information to the Q1 file enables the user easily orient himself among all four sub-cases.
Each sub-case is described here by two successive mesg commands.
For the basic sub-case with caseno=0 these are:
mesg(basic case with minimum settings
These two commands will result in the following on the screen:
basic case with minimum settings
What the possibilities are, is clear from the picture you will see when you run this case.
- Now follows the last mesg command that is
slightly different from the previous ones, viz.
mesgm(caseno equals :caseno: OK? If not, enter required value.
Its only difference from the previous is that it puts blank lines above and below the line which follows as you can see from the above picture.
To read more about mesg commands click here.
- The following four lines are comments which explain how the user's choice of a specific case number is first set by the user and then transmitted to the SATELLITE . The user's task is either to type a specific sub-case number (from 2 to 4) and then press ENTER on the keyboard, or, if he prefers the basic case to deal with (caseno=0), simply press ENTER.
It is the readvdu command which enables reading of keyboard input, i.e. it enables the user to respond via the keyboard to requests from the SATELLITE about specific sub-case that he has selected.
Parameters in round brackets (caseno,int,caseno) denote the following:
caseno - a variable to be introduced,
int - its type, i.e. integer,
caseno - the value of this variable that has been set earlier by the user via keyboard input.
Find more about readvdu command here.
- The following marker save1end shows that the 'protected' part of GROUP 1 ends here.
- The first command within these markers is a conditional command of the type:
if(logical expression) then
The logical expression in round brackets specifies the condition on which the next statement, i.e. statement1, should be fulfilled. For the present case this condition is caseno.ge.0 meaning that if the variable caseno is greater than or equals to zero, i.e. it covers all the cases given, then
the next statements should be fulfilled.
- The statement NX=100, as the comment explains, divides the x
dimension of the slab into 100 elements, i.e. there are 100 grid cells in the X-direction.
- XULAST=0.1 means that the thickness of the slab is set to 0.1 m.
- Then comes the GRDPWR command which creates grids. It contains four arguments in brackets, namely: (X,NX,XULAST,1.0).
- first argument X indicates that the dimension X is in question;
- second argument NX indicates the number of elements or grid cells of this dimension;
- third argument XULAST is the maximum extent of the dimension X, i.e. the thickness of the slab; and
- the fourth argument 1.0 as the comment explains, sets the exponent in the power-law distribution equal to 1.0, i.e. creates a uniform grid.
For more details you may consult Encyclopaedia by clicking here.
- The protected part for GROUP 3 ends here as the save3end marker shows.
2.5 We now deal with GROUP 7, which answers for storing, solving and naming variables. This part is also protected by markers save7begin and save7end.
2.6 Now comes GROUP 11, connected with initialization of variables or porosity fields. It is the part of Q1 where initial values of variables are supplied.
- The next line is SOLVE(TEM1), the command stating which are the solved-for variables in future simulation. The only variable in brackets is TEM1, which means that the aim of our simulation is to calculate temperature distributions for the heated steel slab.
You may find more in Encyclopaedia about this command if you click here.
- Then come two store commands stating which auxiliary variables are required to run this simulation but which are not solved.
- The next part of the Q1 file is valid for the condition if(caseno.gt.0), i.e. for all the cases except one with caseno=0. Its purpose is to enable the accuracy of the numerical calculations to be checked by comparison with the known analytical solution.
Because this part of the file contains explanatory commments, it is included here
verbatim, as follows:
CHAR(FORMULA) ! Declare the character variable FORMULA, and set it
! to the temperature calculated by PHOENICS viz TEM1,
! divided by the theoretical temperature: namely,
! that described by the following:
! 0.5 is a constant in the theoretical expression for
! the parabolic profile,
! 1.E3 is the volumetric heat input,
! xg = x value of any grid point,
! .005*:xulast: = xg of first grid point,
! .995*:xulast: = xg of last grid point,
! KOND is the thermal conductivity of the material
(STORED var #RAT is :FORMULA:) ! Calculates the temperature ratio
The comments explain that FORMULA is being used so as to determine the accuracy of the simulation.
It contains the parabolic temperature distribution which would be derived by solving the differential equation governing one-dimensional heat conduction in a uniform-property solid.
XULAST introduced between colons signifies that the numerical value of this variable, i.e. 0.1 should be used in the earlier expression.
- (STORED var #RAT is :FORMULA:) is the command which assigns the numerical value of the variable FORMULA to another variable called #RAT.
- Next line endif shows that here ends the conditional statement for the sub-case caseno.gt.0, and
- the following marker save7end confirms the end of the protected part for GROUP 7.
You may consult Encylcopaedia here to learn more about it.
This part is also protected by the corresponding markers save11begin and save11end.
2.7 Next part is for GROUP 13 dealing with boundary conditions and special sources. Here boundary and internal conditions as sources and sinks are treated. For more details, click here.
- The first command in this section FIINIT(PRPS)=STEEL specifies the properties of which material should be taken from the whole array of properties in the PRPS file. We need properties of steel for this simulation.
- However, the next conditional command if(caseno.gt.3) warns that for the sub-case 4 it is necessary to replace steel by copper as
- the next command instructs: FIINIT(PRPS)=COPPER.
- That is the end of the conditional statement (endif) and
- of the protected part, too - save11end.
This part is protected by the markers save13begin and save13end.
2.8 The last part of the Q1 file is for GROUP 23 which allows variable field print-out, plotting and tabulation of spot values and residuals. Consult Encyclopaedia for more details.
- The first command within these markers is the PATCH(minXface,WEST,1,1,1,1,1,1,1,1) command that locates the low-x face, its 10 arguments being as follows:
- minXface - patch name up to 8 characters long;
- WEST - specifies that WEST direction coincides with X-axys starting from smaller X-section;
The last eight arguments are normally integers which locate the patch by reference to the computational grid, namely
- 1 - first cell in x-direction;
- nx - last cell in x-direction, that is also 1, as we are setting the low-x face;
- 1 - first cell in y-direction;
- ny - last cell in y-direction, being 1 for the low-x face;
- 1 - first cell in z-direction;
- nz - last cell in z-direction, being 1 for the low-x face;
- 1 - first time step;
- 1 - last time step, being also 1, as only one sweep or one iteration is to be made.
- Next PATCH(maxXface,WEST,NX,NX,1,1,1,1,1,1) command is used to locate the high x-face, its arguments being practically similar to those of the first PATCH command except for the last cell in x-direction. And it was assigned to be NX=100.
For more details about PATCH command, click here.
- Then come two COVAL commands which are used to introduce boundary conditions for our case, i.e. COVAL(minXface,TEM1,FIXVAL,0.0) and
COVAL(maxXface,TEM1,FIXVAL,0.0). The arguments in round brackets indicate the following:
- minXface and maxXface are the names of the patches located on the corresponding faces to which the COVAL commands refer.
- TEM1 is the solved-for variable in question;
- FIXVAL means 'fix the value of this variable', and
- the last argument 0.0 indicates that the ends (first and last faces in x-direction) should be kept at a constant zero temperature, as the explanatory comments which follow the exclamation mark assert.
To learn more about this command, click here.
- There follows the command which introduces the patch called HEATER
The arguments '1,nx' specify that the volumetric heat flux extends from low x
What ensures that it is a volumetric flux is the
word 'volume' which appears as the second argument of the PATCH command; this
specifies the 'type' of the patch.
A description of what other possible types may be invoked is to be found
here. The types 'WEST' and 'EAST', it may have been noticed, were used
for the slab-face patches.
The type name is not case-sensitive.
- It is followed by COVAL(HEATER,TEM1,FIXFLU,1.e3) that is another COVAL command to fix the heat flux at a constant value of 1kW/m**3.
- Next is the conditional statement if(caseno.gt.2) giving new instructions for sub-cases with the variable caseno exceeding 2. These are the following:
- First two real variables are declared - REAL(THICK,HEATINPT) which denote the slab thickness and the heat input.
- Then already familiar numerical values are assigned to these parameters, i.e. THICK=0.1 m and HEATINPT=1.0E3 kW/m**3.
- The command creating the grid is therefore rewritten in the following way: GRDPWR(X,NX,THICK,1.0) in view that the slab thickness is now designated as THICK.
- And the same COVAL command fixing the heat input is now as follows:
- The next line with endif indicates the end of the conditional statement, and
- the very last line in this section, save13end, marks the end of this protected part.
This part is also protected by the markers save23begin and save23end.
- It starts with with the conditional statement if(caseno.gt.1) and is valid for the sub-cases with the variable caseno starting with 2. These are the sub-cases for which the temperature profile will be plotted in the result file as the comment explains.
- Next comes the PATCH command called TEM1PLOT wherein the word PROFIL indicates that a profile is to be plotted along the whole range of the slab thickness, i.e. from the first face to the very last (NX) -
PATCH(TEM1PLOT,PROFIL,1,NX,1,1,1,1,1,1), all other parameters being unchanged, i.e. one cell only in Y- and Z-directions and one time step considered.
'TEM1PLOT' is merely a name which the user has chosen for the patch; any other name can be used, provided that the same one is used in the following PLOT command.
You may find more about plotting profiles by clicking here.
- The second argument of the next command, PLOT(TEM1PLOT,TEM1,0.0,0.0), specifies that the variable to be plotted is TEM1.
The third and fourth arguments of the COVAL command are provided to enable the user to select first the minimum and then the maximum values of the ordinate scale.
When they are both left as zeroes, the user is indicating that he wishes to make no specifications. In effect he is saying to PHOENICS; "You choose."
PHOENICS then chooses such a scaling procedure as causes the lowest point of the curve to lie on the bottom line,
and the highest point to lie on the top line, of the rectangular frame of the picture.
- The last statement in this part is ORSIZ=0.2.This quantity, is described in the
Encyclopaedia entry, as being the height of the frame enclosing the PROFIL plot and having a default value of 0.4, which gives 20 printed lines.
Evidently the writer of the Q1 preferred a smaller diagram, choosing 0.2 for ORSIZ and so printing only 10 lines, as will be seen below.
He was apparently content with its horizontal dimensions; for he did not make a setting for the corresponding variable
ABSIZ which has a default value of 0.5, giving a 50-column-wide plot frame.
- Next line with endif shows the end of the conditional statement when the variable caseno is greater than 1.
- Next is the statement LIBREF=163 that denotes the reference number of the Input Library case, this being, as has been stated above, 163.
- Then comes the marker save23end indicating the end of the protected part for GROUP 23.
- The last statement STOP indicates the end of a particular run. For more details, press here.
3. Some conclusions about the file structure
Having discussed every part of the Q1 file, it is now possible to give summarization as to its structure. It has been already mentioned above that the Q1 under consideration describes the simulation problem with the help of one basic case and four sub-cases differing in the variable caseno. It may be useful to remind the user what these are:
- caseno=0 This is the basic case with minimum settings.
- caseno=1 The basic case that allows a comparison with exact solution.
- caseno=2 Similar to the previous case + the temperature profile along the slab thickness is plotted here.
- caseno=3 Similar to the previous case + two real variables THICK and HEATINPT are declared and set here.
- caseno=4 The metal of the slab is here changed from steel to copper.
4. Making a simulation
In this section we shall make a simulation for the same problem running the basic case andfour sub-cases. You may make these runs in any possible way you prefer. A convenient way of doing so is via the PHOENICS Commander's input file-library feature. We suggest that first of all you create five separate folders for each run where the results of each simulation will be stored. After that do the following.
4.1 Sub-case with caseno=0
4.2 Sub-case with caseno=1
- Open the PHOENICS Commander.
- Click the 'Input-File Library' button in the top row.
- Click the 'set work dir.' button in the top row, then click 'select...' and browse for the working directory you have created for caseno=0.
- Click the 'choose by case number' button on the left, insert the case number 163 in the case number box and click on the 'Load it' button. Your actions will result in the following picture
- From the list of commands choose 'Run the case'.
- You will see the already-familiar screen.
Click ENTER to load the basic case with minimum settings.
- After some short time the simulation will be made. You might have to move the PHOENICS Commander window by the title bar to get the picture like this one.
- Load the result file into the Commander editor clicking the tab 'Result file' in the bottom row.
- Browse the file to the bottom where Field Values are given.
These values are as follows:
- Field values of KOND are represented by a constant of 4.300E+01, i.e. the thermal conductivity of this material (steel) being 43 watts/(m*degC) for each face.
IX here equal to 1, 21, 41, 61 and 81 is a number of a specific face.
- Field Values of PRPS are also represented by a constant of 1.110E+02, this being a number of steel in the database of materials properties collected in the PRPS file.
- And at last, Field Values of TEM1 represent acually the solution of the problem under consideration, as these are temperature values in specific faces, expressed in degrees Celsius. Pay attention to the temperature value at the first face (IX=1) being 2.500E-09, that is very close to the desired zero value.
4.3 Sub-case with caseno=2
- Inside Phoenics Commander click the 'set work dir.' button in the top row, then click 'select...' and browse for the working directory you have created for caseno=1.
- Repeat the steps d-i with one exception: type number 1 when the Satellite screen appears, thus running this very sub-case. The Field Values in the result file will be as follows.
They are identical to the field values of the previous sub-case apart from extra Field Values of the variable #RAT. This is the ratio of TEM1 (temperature obtained in CFD simulation) to the same temperature obtained by the exact solution.
For IX=21, 41, 61, 81 this variable #RAT is unity, meaning that the results of CFD simulation coincide with those of the exact solution. However, #RAT at IX=1, being 2.500E+11, is very far from unity. The explanation is that the 2.5E-9 value of TEM1
computed there, divided by the even lower theoretical value, 0.0, is an uncertain quantity; and to prevent a 'division-by-zero' Fortran error, 1.e-20 has been added to the denominator.
4.4 Sub-case with caseno=3
- Inside Phoenics Commander click the 'set work dir.' button in the top row, then click 'select...' and browse for the working directory you have created for caseno=2.
- Repeat the steps d-i of the section 4.1 but introduce number 2 when the Satellite screen appears. When you open the result file in the PHOENICS Commander editor, the field values of the variables will coincide exactly with those of the previous sub-case. What will be new, is the plotted temperature profile of such kind.
It is a parabola as we anticipated. The words Variable 1 = TEM1 mean that the temperature profile indeed has been plotted. You should pay attention to the fact that both the abscissa and the ordinate vary from zero to unity, i.e. the temperature profile has been represented in relative coordinates.
However, to assist understanding of the real magnitudes, minimum and maximum values of temperature are given above the plot designated by Minval and Maxval.
The variation range for the abscissa in the X-direction, shown beneath the plot, is from min= 5.00E-04 to max= 9.95E-02.
It differs from the introduced slab thickness of 0.1 m, because it is the co-ordinates of the centre-points of the cells which are used as abscissa.
4.5 sub-case with caseno=4
- Inside Phoenics Commander click the 'set work dir.' button in the top row, then click 'select...' and browse for the working directory you have created for caseno=3.
- Repeat the steps d-i of the section 4.1 but introduce number 3 when the Satellite screen appears. When you open the result file in the PHOENICS Commander editor, you will notice no material changes from the previous one.
At the present stage we simply draw attention to this fact; but it should be borne in mind that here we have introduced the slab thicknes and heat input expressed in parametric form, i.e. by means of two real variables THICK and HEATINPT. We shall return to this circumstance in Part 2 of this tutorial when we discuss the advantages of parameterization.
- Inside Phoenics Commander click the 'set work dir.' button in the top row, then click 'select...' and browse for the working directory you have created for caseno=4.
- Repeat the steps d-i of the section 4.1 but introduce number 4 when the Satellite screen appears. To remind you, this is the sub-case where the steel slab has been replaced by the copper one, all other options being identical to the previous sub-case.
- Open the result file in already familiar way and find the field values of variables. You should the following.
- We would like you to pay attention that Field Values of KOND, i.e. thermal conductivity, have been changed from 43 watts/(m*degC) used in all previous sub-cases, to 381 watts/(m*degC) for copper.
- Field Values of PRPS have been also changed from 111 to 103 being the number of copper in the PRPS file.
- Field Values of TEM1, i.e. temperatures along the copper slab thickness, have changed as well; the use a material with a much higher thermal conductivity has resulted in respective reduction of temperatures.
- Let us now examine the temperature profile plotted for that sub-case. It looks as the picture shows.
It is precisely the same, as the plots shown for the previous sub-cases, although the initial conditions, viz. thermal conductivity is about ten times higher than in the previous sub-cases.
This is because all plots for this problem are printed in relative coordinates.
However, although the minimum and maximum X values are the same as in the previous sub-cases (the thickness of the metal slab has been unchanged), you can see that the maximum temperature has been reduced significantly, in full compliance with the increased thermal conductivity of this last sub-case.
5. Concluding remarks
In Part 1 of this tutorial,
In the library case 163, both the thermal conductivity and the volumetric heat input were taken as uniform. Indeed the problem was so simple that it could be solved analytically.
- you studied what is the Q1 file in general;
- what statemements, commands and comments could be used in Q1 files was shown and explained by the example of already existing Q1 for the Library case 163;
- you made several simulations using only one Q1 file, and
- you found out how to present and measure results with the help of the result file and PHOENICS Commander.
In Part 2 of this tutorial, which can be entered by clicking
you will learn how to handle more realistic problems, in which both the conductivity and the heat input vary with temperature.
Moreover, this will be done in a parameterised manner.
This means that the newly-created Q1 will be usable for slabs made of any material for which the said dependences on temperature can be expressed via formulae.
Thus will be illustrated what was written at the start of this tutorial:"the user of PHOENICS can set up classes of scenario, of
are selected by way of user-chosen parameters".