Analytical Services & Materials, Inc.


The Patcher

Section I: Introduction *

Section II: The Patcher Control File *

Part I: Run Modes *

Part II: New Features *

Section III: The Patcher Database Structure *


The Patcher

Section I: Introduction

    Flow conservation is essential aspect in computational simulation of complex three-dimensional configuration. In the area of aerospace design, accuracy is very important aspect of CFD simulation. For example, the GEAE company will reject any simulation which produces error higher than .05%. With this factor in place, CFD simulation uses non-cocervative patcher is consider incomplete and may be inaccurate. Dr. Paul Pao developed and continues the advancment of the Pre utilities. Pre is one of the major utilities needed to setup the general multiblock option for the PAB3D code. Pre creates the patching connectivity table "Patcher" and sets up the memory information for the PAB3D code. The Aerospace CFD community recognizes the patcher procedure as one of the accurate representations of conservative patching package. PAB3D, TLNS3D and a version of CFL3D use the patcher procedure for the multiblock setup. This chapter describes the patcher setup and the connectivity table.


If the user have the source code (Fortran and C) of Pre, the user will need to compile Pre once by:


        make Pre


    It depends on a small set of Fortran and c source programs:


        am.f Pcauto.f pchpdycw.f premem.f prewrap.c

Section II: The Patcher Control File

        There are two main input files for Pre:


        patch.cont and/or ep.change


    Other files are needed either by default or requested by one of the control files:


        grid.file user.cont


    Once all the files are assembled within a working directory, Pre can be invoked by either


        Pre <patch.cont


    or just type:


    In the latter case, Pre will ask for the name of a 'ep.change' file.
Now it is time to introduce the ep.change file: an example is:


    Generic form:

* label: 'run-mode', nstart, nstop, 'control-file-name'

'run-mode', nbstrt, nbfini, ''

* label: global change to epsrf: ep-num, ep-value

nn1 <enter 0 if no change is given

ep-num, ep-value

... <Repeat nn1 times

* label: local changes w/specified face-pair:

nn2 <enter 0 if no change is given

ffoa, ffob, ep-num, ep-value

... <repeat nn2 times

* label: local change: identify one side of the face-pair;

nn3 <enter 0 if no change is given

'receiver/donor' ffoa/ffob, ep-num, ep-value

... <repeat nn3 times


    An Example

* 'default'. 'debug' or 'normal'; nblock-start, nblock-finish

'debug', 1, -1, 'dynamic.cont'

* global change to epsrf: ep-num, ep-value

1 (or 0 if no change is given)
28 8.

* local change: specify face-pair: ffoa,ffob,ep-num,ep-value

1 (or 0 if no change is given)
21.6 12.5 28 8.0

* local change: 'receiver' or 'source',face-num,ep-num,ep-value

4 (or 0 if no change is given)
'receiver' 30.1 28 8.00
'ffoa' 33.4 28 8.00
'donor' 46.3 28 8.00
'ffob' 29.5 28 8.00


** this example is to show the appearance of input lines.

 Part I: Run Modes

'default' batch mode patching using default ep-values. The code makes the entire run without stopping for user interaction.

'debug' interactive mode for patching. The patcher will stop if 'empty cell' is found for a block face with connection to other blocks. A list of action options is available for the user to choose from. Each option can be activated by simple keystrokes. At the end of each block, the user will be asked if he/she would like to continue. More detailed description will be given later in this documentation.

'normal' after all block faces are patched with no error, the preprocessor will automatically designate this mode in the ep.change file. It will run through the entire patching will all the local and global ep-value changes given in the remainder of the ep.change file. The Pre execution will patch the entire grid from first to last block.

'restart' this run-mode will patch grid from first block on the 'normal' non-interactive mode, then switches over to 'debug' mode at block=nbstrt. The advantage of this mode is to have a complete patching record at the end of the run. If the patching is entirely successful, there is no need to redo the entire grid once more under 'normal'.

'skip' this is tricky one: sometime the user wants to skip over some blocks during patching. The input will be to use the next line (normally a label for global changes) for additional input:

'run-mode', nbtot, nb1, nb2, ...

This secondary run-mode designation can be 'debug', 'normal', or 'restart'. nbtot is the number of blocks to skip, and nb1, nb2, ... are the block numbers of the blocks to be skipped over in the patching process. One of the reason to use 'skip' is for a grid where some bad blocks are included in the grid file; a core dump has occurred at some blocks where the user may want to deal with them later on, etc.

Start/Stop locations for 'debug' session:

Nbstrt Begin from this block for debug mode;
nbfini Stop at the end of this block in 'debug'  mode. Note: '-1' can be used to designate 'last block' in the grid file.


    For 'normal' run mode, the block range n1 and n2 are automatically set to first through last block. For 'restart' run-mode, patching always starts from block 1. The value of nbstrt is used to signal switching from 'normal' mode to 'debug' mode.


    'control-file-name' PAB3D control file name

* label for global changes of ep-values
nn1 number of changes

<nep, ep-value ep reference number, new value.Repeat nn1 times.

* label for local changes where both receiver and donor face numbers are given


    nn2 number of face-pair changes

<ffoa,ffob,ep-num,ep-val receiver face number, donor face number, ep-reference number, new value.Repeat nn2 times.

* label for local changes where receiver or donor face is given:
nn3 number of local changes


<word,ffox,ep-num,ep-val 'key-word',ffoa/ffob,ep-num,ep-value. Repeat nn3 times.



ep-num: = the epsrf identification number
ep-value: = the corresponding epsrf value
ffoa (value of) = decimal form of block.face
ffob (value of) = decimal form of block.face

'key-word' = see list as follows:

'receiver' = block face receiving flow information
'ffoa' = block face receiving flow information
'source' = block face supplying flow information
'donor' = block face supplying flow information
'ffob' = block face supplying flow information


    Changes made during debug mode are automatically recorded in the third group of changes. The value of nn3 is change and written back to the file automatically. In most cases, the user would start with nn3=0 for a new grid, and then specify changes if needed through Pre in 'debug' mode.


    In 'default' and 'normal' mode, the code runs in a way similar to the old 'Patcher'. The grid will be patched from beginning to end without stopping. Errors will be reported to the user. In 'default' mode, the code will not change any of the pre-defined ep-values.

Part II: New Features

  In 'normal' mode, changes to ep-values are made according to user input in the 'ep.change' file. Two important improvements have been made with respect to the old-patcher:


  • Pre will automatically query the connectivity information in the Pab3D control file to determine the 'source' or 'donor' grid range on the 'source' or 'donor' face. As a result, multiple-cut patching range is automatically processed in the code. The code will not patch a cut into itself, for obvious reasons. As a result, the user no long needs to use the 'ordinary' patch option for C-grid. All patching can be given in the general patching form. If no correspondence is found, the code will issue a warning message. This condition is a user error: connectivity occurs for pairs of block faces. An error occurs if one or the other side is not specified.
  • There is one situation where the grid face is patched to itself: i.e. in case of 'extrapolation' to get rid of a small number of remaining 'empty cells'. In the new patcher code, the user simply specifies '10000' as the last cut for the block face in question. No block or face designation in the code is required (or permitted). The Pre code will extrapolate any cell within the given grid range which has been filled less than one percent of its own cell face area.

Caution: do not use the '10000' extrapolation option over a ranged where a "partial" solid wall is involved. The '10000' code will put a huge 'hole' in the solid wall.

    In all run mode, the user can invoke Pre without redirection of the pab3d-control-file to the executable as the input file:



'enter ep.change file name'


    In the given 'ep.change' file, the run-mode word can be any of the permissible options. The PAB3D.cont file name is given in the same line in this file. The Pre processor will then start running according to the given run-mode. It will stop to query the user if it is in 'debug' mode for optional instructions.


    When 'empty cells' are found in 'debug' mode, the code will ask:


    = End patching [1.6]<-[2.5]; Move on to next patch?
    y/n/c/e/h/v/w/auto ?
    - y=yes,n=no,c=change,e=erase,h=help,w=where,v=value=ep,auto=auto


    The response code can be reviewed by typing 'h' or 'help':

Help Manual: input keys <<'
yes (y): go to next block face'
no (n): stay and change ep'
change (c): stay and change ep'
erase (e): erase previous changes'
help (h): show help manual'
where (w): where are the bad cells?'
value (v,ep): show default ep-values'
auto (auto): search for ten best ep-values.'


    In all the query responses, 'y' or 'yes' can be substituted by a carriage return <cr for lazy people, such as the author. The main purpose is to change certain ep-values and try again. In this interactive mode, the user need not do what was required in the old patcher: end the session, edit and change the ep.f file, recompile, and do it again!


    Before making changes, the user can type 'h' or 'help' for listing of the response-key manual, type 'ep' or 'v' for a list of the ep-reference number and values, or 'w' or 'where' for a list of 'empty cells' indicial addresses.


    The bad-cells are lists by their (i,j,k) address. Imin, imax, jmin, jmax, kmin, and kmax indicate the block faces. The user can choose not to deal with the empty cell on a particular face for now, and move on to the next patch, by typing 'y' or <cr. The bad-cell addresses are saved with the patching face-pair id-numbers in a file called 'badcell.list'.


    One of the major conveniences to the user, in addition to being able to debug on-line, is the 'auto' mode. Once the user types 'auto' the code will echo a list of ep-value that it would automatically try one-by-one to see if a better patch can be achieved. The values are in ten groups. In each group, one of the ep-reference number will be altered for 2 to 4 times. If an improvement is made in a test sequence, the best value will be selected and automatically recorded in the ep.change file as a local change item. If all cells are patched, the changes are automatically recorded and the patcher code moves on to another face-pair. The 'empty-cell' record of ep-value change is print on screen and written in the '' file. If the user wants to change a certain ep-value beyond the pre-determined values in auto, the changes can be made manually by typing 'c' or 'n'.


    For manual changes of ep-values, the code will prompt:

Enter change by giving ep-number and ep-value: terminate by 0, 0.


    The user can enter multiple changes. The requirement of two zeros to terminate the input sequence is a Fortran handicap. The manual changes are also recorded in the 'ep.change' file.


    At the end of the block, the code will query whether the user would like to continue. 'y' or <cr will keep it going. 'n' will stop the code and let the user go and do something else, such as going to lunch. The code will print on screen the beginning and the ending block for this session, and the total number of blocks in the grid. It is a reminder that the session may not be a complete patch of the entire grid.


    If the debug session is successful, the code will change the 'debug' word to 'normal' in the ep.change file. Next time the code is run, it will run from start to finish without stopping at the end of each block.


    One example is included with this package:


    The corresponding ep.change file is:


        ep.jones2 (Grid=stripped3.d , control file: jones2.cont)


** ep.jones2 file contains one ep-value change to make the patching difficult. 'auto' mode will correct that ep-value to default and finish the patch.



Section III: The Patcher Database Structure


The communication data base structure is written in unstructured form. First, we transform the local information to global one. For the multiblock structure PAB3D code, each block contains six faces as:

Jmin, ===== Face 1 Jmax, ===== Face 2

Kmin, ===== Face 3 Kmax, ===== Face 4

Imin, ===== Face 5 Imax, ===== Face 6

One or more sub-faces may present each of these faces. Each of these faces is a collection of cells, which may contain one or more elements as shown in Figure 1.


Also, the local ID of each sub-face as Block 5, Face 1 and sub-face 3 has a global patch # 25. Each of these local sub-faces is assigned a global sub-face ID (Patch #). This is only done for Block communication sub-faces. Figure 2. shows the example of transforming from local to global and back to local.


The database allows the communications across cells, faces and blocks with a universal set of information. The information is written as an unstructured list of cell correspondences over the block interface. There are two sets of information that complement each other to complete the database. Another set of information is needed for the MPI implementation.

First set deals with the upper level of communications that deals directly with patched element. Figure 3., shows the sections of the database file contains this set. For which, each of the source blocks is assigned a number of patches (NPCH) with their global Ids (IPCH). Each global patch, IPCH, contains selected number of patched elements (NPE_G), destination face (FACD), and the source block, face and sub-face (BLKS, FACS and SFACS). Each entry of the NESC contains five items; the address of D-Cell (Destination, NB1) and S-Cells (Sources, NB2_1 and NB2_2), the value of the contact area as a fraction of the total cell face area of D-Cell (FRC), and the total area of D-Cell (AREA). This information is collected at the fine grid level. This database provides cell area information sufficient for any level of grid density reduction. The NB1, NB2_1, NB2_2 and FRC have a fixed number of items (NPE_G) for the corresponding patch.

With the above set of information, the PAB3D code needs guidance to control the flow of information. Figure 4., shows this input section of the database file. The lower level of communication contains all the information needed to complete this task. Each block may contain a number of patching cells (NPCS) with a starting global sub-face (IPCHS) and a pointer (PNB1) locating the beginning of the five items (NB1, NB2_1, NB2_2, FRC and AREA). For each face (1-6), the number of patched cells (NPCS(l), l=1-6) are defined with the pointer of patched cells (PPCS(l), l=1-6). The last global sub-face (IPCHL) is identified within the specific block. Finally, the three-dimension location of each patched cell in that block is tabulated. For the MPI implementation, each patched block will send and receive data through the database. A set of unique global sub-faces is assigned either the sending (SPB) or receiving (RPB) group for each block. For example block 1 could have Patches 1,2,3 and 4 as sending group and Patches 10,18,21,15 and 9 as the receiving group. The sending group may not have the same number of Patches as the receiving group.

NB1, NB2_1, NB2_2 and NB3 are mulidimensional locator. For example for M-dimension of Lm axis:

N (NB1, NB2 and NB4) =

NB1, and NB2_1 are two-dimensional locator:

Face 1 or 2 => L1 = K and L2 = I

Face 3 or 4 => L1 = I and L2 = J

Face 5 or 6 => L1 = J and L2 = K

NB2_2 and NB3 are three-dimensional locator:

L1 = J, L2 = K, and L3 = I




Figure 4. Set 2 of the Database







If you have any questions, please contact;

S. Paul Pao at 757-864-3044 (LaRC, This email address is being protected from spambots. You need JavaScript enabled to view it.) or
Dr. Hamid at 805-258-2987 (AS&M, DFRC)