5. The GENTRA FORTRAN

1. Introduction

GENTRA, like PHOENICS EARTH, has a user accessible area where users can attach their own coding sequences to supplement the built-in-features. This chapter introduces this area.

2. The structure of GENTRA-EARTH

The EARTH part of GENTRA is attached to PHOENICS-EARTH as a GROUND subroutine. While most of the GENTRA-EARTH routines are supplied in binary (and are not, therefore, accessible to users) some routines are provided in open source (see figure 5.1). These are:



Figure 5.1: The GENTRA-EARTH structure

• GENTRA, the Ground Station that attaches GENTRA to EARTH. The GENTRA subroutine initialises the GENTRA variables, calls the particle-tracking modules and then transfers the interphase sources computed by GENTRA to the finite-volume equations solved by PHOENICS. Users seldom need to introduce changes in this module, which for this reason, is not discussed in this Guide.
• GENIUS (GENTRA Interface for User Sequences) is the GENTRA open-source subroutine where users can insert FORTRAN coding to supplement or replace the built-in features. GENIUS is called by GENTRA at well-defined stages during the solution of the particulate phase. GENIUS can therefore be regarded as the counterpart for GENTRA of the EARTH GROUND.
• GPROPS is the particle property function routine, in which properties of the particulate phase may be set.

Regarding the filing arrangements, all of the open-source routines are provided within the file "gentra.htm". This can be edited from the VR-Environment by clicking on File, Open file for Editing, and selecting gentra.



Figure 5.2: Opening GENTRA.HTM for Editing

A reference copy of this file is kept in the \phoenics\d_earth\d_opt\gentra directory. Users can copy this to their private directory for modification.

3. The FORTRAN subroutine GENIUS

   GENIUS is similar, in concept and format, to the EARTH subroutine GROUND. GENIUS is divided into groups, some of which are further divided into sections, that are visited at specific stages during the computation. Users can insert their own coding in these groups in order to obtain additional results, to compute auxiliary data, and to influence the GENTRA computation. (Users are however advised that the modification of GENTRA variables, particularly of those which affect the particle history, should always be effected with great caution).

   After a call to GENIUS, the execution is directed to the appropriate group and section by the FORTRAN variables IGENGR (GENIUS group) and IGENSC (GENIUS section) and a network of computed GOTOs. Both IGENGR and IGENSC are set within GENTRA and the user should not modify their values.

   The groups and sections of GENIUS are discussed now in this guide; a list of the user-accessible FORTRAN variables can be found in Appendix C; and Appendix G contains the full listing of GENIUS.

   1. GENIUS Group 1: Preliminaries

   Group 1 is visited at the beginning of the first call to GENTRA in each EARTH run, ie when

   (ISTEP.EQ.FSTEP).AND.(ISWEEP.EQ.GSWEP1)

   Group 1 is therefore a convenient place for the initialisation of local variables that are subsequently going to be used in GENIUS; and, since the group is visited after GENTRA has initialised its variables, it is also the place to override the Q1 and default settings for the GENTRA variables. Users can, for instance, change the logical units for the output files (see variables LUPRO, LUWAR, LUERR, LUTRA, LUHIS in Appendix C)

   2. GENIUS Group 2: Start of new track

   This group is visited at the beginning of the tracking of each particle, once:

   • the particle data has been read from the inlet-data table and stored in the F-array;
   • all the variables for the track (such as the particle number IPARTI, the absolute time TIME, the cell residence time CTIME) have been initialised; and
   • the trajectory and history files have been opened (if the user has requested such output and the current sweep is the last one).

   GENTRA calls this group before it locates, using the particle-inlet co-ordinates, the indices of the cell where the particle is initially located. Users can therefore override, in this group, the settings in the inlet-data table for the particle inlet position and properties. This is particularly useful when the particles obey a size, velocity or density distribution. In this case, "dummy" properties can be used in the inlet data, and these can be subsequently overwritten in GENIUS. To do this, the particle variables to be set in GENIUS are the ones ending in N in the list provided in Section C.2. The values will be subsequently transferred to the corresponding 0 variables by GENTRA. You do not need to supply the cell indexes I*PAR*, since these will be found by GENTRA using the particle co-ordinates supplied.

   3. GENIUS Group 3: start of new Lagrangian time-step for the current track

   Group 3 of GENIUS is visited at the beginning of the time-step, after

   • the time-step counter JCOUNT has been updated;
   • the particle properties at the beginning of the current time-step are assigned the values prevailing at the end of the previous one;
   • the continuous-phase properties at the particle position have been found (see Section C.1 for a list of these variables, and Section 6.8.3 for further information); and
   • the stagnation check has been passed (see Section 6.8.1);

   and before

   • the time-step is calculated (see Section 6.7.1); and
   • the particle is moved (see Section 6.8).

   Users can, in this group, specify the maximum time-step by resetting the variable GDTMAX (initially set in the Q1 file/menu); or inspect (and, with caution, change) the continuous-phase properties "experienced" by the particle (see Section 6.8.3).

   4. GENIUS Group 4: Particle reaches cell boundary

   GENIUS Group 4 is visited when a particle reaches a cell boundary. The value of IGENSC is used to distinguish between several events, as follows:-

   IGENSC=1 means that the particle has reached an exit (i.e., the appropriate face of a patch whose name starts with GX);

   IGENSC=2 means that the particle has reached a wall or obstacle. (Note that the visit to GENIUS takes place after the velocity components have been changed after bouncing, if the particle is to be bounced);

   IGENSC=3 means that the particle has been reflected at an axis/surface of symmetry;

   IGENSC=4 means that the particle is in a new cell (note that the particle might, in this case, be inside the new cell, and not just on the boundary).

   5. GENIUS Group 5: End of current Lagrangian time-step

   Group 5 of GENIUS is called at the end of the current Lagrangian time-step, after:

   • the cell residence time CTIME and the absolute time TIME have been increased by GDT, the current time-step size;
   • the several end-of-tracking criteria (such as timeouts) have been checked;
   • the cell residence-time CTIME has been reset if the particle is in a new cell, and transferred to the full-field store in EARTH if the current particle IPARTI is GRESTI.

   Users can, in group 5 of GENIUS, "kill" the tracking of the particle by setting the logical variable KILPAR to .TRUE.. The tracking of the particle will be then abandoned, and GENTRA will start tracking the next one.

   6. GENIUS Group 6: End of current track

   Group 6 of GENIUS is visited before finishing the track for the current particle, and moving on to the next one. It is visited after the plot trajectory and history files have been written, if appropriate, and closed.

   7. GENIUS Group 7: GENTRA returns control to EARTH

   GENIUS Group 7 is visited immediately before RETURNing the control to EARTH, after the CALL to GENTRA for the current sweep.

   8. GENIUS Group 8: Special calls

   Group 8 of GENIUS is designed to allow the user to modify the built-in Lagrangian equations. There are 5 sections in this group.

   • Section 1: Particle momentum equation

   The method of discretization of the particle momentum equation is described in Section 6.5.3. The discretized form of the equations is:

   

   At the time this section is called, all of the coefficients and sources (GVCSAA, GVCSBB, GVCSCX, GVCSCY, GVCSCZ) have been calculated in GENTRA. For the particle momentum equation given by equation (6.32) in Section 6.5.3, the prevailing values are:

   

   Users are free to reset them or add to them. For example, if an extra magnetic field needs to be taken into account and the effect of the magnetic force on the particle can be written as:

   dUp/dx= GMX

   (if only x-component of the force exists) then the user should add the following coding in this section:

   GVCSCX = GVCSCX + GMX

   As another example, the following coding replicates the built-in particle momentum equation:

   REYNOL=RENLF(DIPARO,RELVEC,GSENUL)
   CDRG=GPROPS(1, REYNOL, GDRAG)
   GVCSAA=(3.0*GSENUL*DENGAS*CDRG*REYNOL)/4.0*ROPARN*DIPARO**2
   GVCSBB=GVCSAA

   where GPROPS and RENLF are GENTRA function subroutines, and all the FORTRAN variables appearing on the right hand side are in local common blocks ( see the common-block file TRACMN ). The values of GVCSCX, GVCSCY and GVCSCZ will already have been set in GENTRA.

   • Section 2: Particle energy equation.

   This section is called before the energy equation is solved but after the coefficients and sources (GHCSAA, GHCSBB, GHCSCC) have been calculated. The user can change the terms in the energy equation in the same way as for the momentum equation.

   • Section 3: Particle mass equation.

   This section is called before the mass equation is solved but after the coefficient and sources (GMCSAA, GMCSCC) have been calculated. Beware that instead of solving particle mass or particle diameter, the square of the particle diameter is chosen as the dependent variable.

   • Section 4: Particle solidification.

   In this section, the user can change the built-in model for particle solidification which is a function of particle temperature.

   • Section 5: User's own Lagrangian equations.

   The user can write his own particle momentum, energy, mass and solidification equations in this section. The particle velocity, temperature, size, etc., calculated here will overwrite the corresponding particle property.

   9. GENIUS Group 9: Particle inlet conditions.

   Whenever a data element in the particle inlet-data table described in Section 2.7.1 is replaced by the name of the data item, GENTRA will look up the relevant section in this group for the inlet data. The inlet data is passed from this section through the variable "PRVLIN". For example, if the inlet-data table reads:

   <GENTRA-INLET-DATA>
   *_ XP _ YP _ UP _ VP _ DIAM _ FRATE
   0.1 0.2 UP 1.0 1.2E-05 1.2E-03
   <END-GENTRA-INLET>

   GENIUS Group 9, Section A will be visited for the setting of UP. If the user inserts the following coding in Section 4 of this group.

   PRVLIN=3.0

   then the x-component of the particle velocity will be set to 3.0 m/s.

4. The property function - GPROPS

   GPROPS is a function routine for particle properties, a full listing of which can be found in Appendix G. The arguments of GPROPS are FUNAME, PARAMT and DEFVAL. FUNAME is the index number of the function (eg 4 for the thermal conductivity of the vapour), PARAMT is the main parameter of which GPROPS is a function, and DEFVAL is the default value for the function. If DEFVAL is not a GROUND number, GPROPS is set to DEFVAL before returning. However, if DEFVAL is equal to a GROUND number, control will be directed within GPROPS to the appropriate section where it will be set as a function of PARAMT. It is possible to set GPROPS to be a function of any of the variables within GENTRA (described in Appendix C), as these are available within GPROPS due to the inclusion of the common file "TRACMN". If a GROUND number is set for DEFVAL, but appropriate coding is not supplied within GPROPS, an error condition will occur and execution of GENTRA-EARTH will be stopped.

5. Building private versions of GENTRA

After modifying a user-accessible module of GENTRA (i.e., subroutines GENTRA, GENIUS or GPROPS), the user must build a private version of EARTH. The build script will automatically compile GENTRA.HTM, so there is no real need to compile it separately.

In the VR-Environment, click on Build, then Earth.



Figure 5.3: Building a ‘Private’ EAREXE

Once the new EARTH executable has been built, the environment must be told to run the ‘private’ EARTH, not the ‘public’ (CHAM-supplied) EARTH. Click on Options, Run version, then select ‘Private’ or ‘Prompt’ for Earth.



Figure 5.4: Selecting to run a ‘Private’ EAREXE

To run EARTH, click on Run, Solver, Local Solver (Earth). If ‘private’ had been selected above, the newly-built EARTH executable will be run. If ‘Prompt’ had been selected, the option of running ‘Private’ or ‘Public’ EARTH will be offered.

---

Top Previous Next