Preprocessing Overview

The preprocessing step creates partitioned data for parallel execution of the flow solver. pre_nsu3d is the general pre-processor for the flow solver nsu3d. There are three main ways that the preprocesser can be run

Prerequisite files for preprocessing the grids are: It is strongly recommended to run visual checks on the bcs and comp files prior to preprocessing the mesh and running the flow solver. This can be done using tecform as shown in the tutorial

prensu3d Input File

Below is a description of the pre_nsu3d input file:
TITLE: Name of the case, if unchanged pre_nsu3d will autogenerate based on other file names.

MESH FILE NAME: See here for more information on compatible model grids.
  • If this file ends with *.mcell or *.mcell.unf an mcell file is assumed containing mixtures of element types. (see mcell file format for a more detailed description)
  • If the mesh file ends with *.b8.ugrid, a b8.ugrid file format is assumed.
  • If the mesh file ends with *.cogsg, a VGRID file is assumed, containing only tetrahedra. In this case, the corresponding *.bc file is also read in.
POIN1 FILE: This entry controls merging of tets into prisms (for vgrid files) and line construction (for all grid files) MCELL MESHES:
  • If file name is "none" or 0, no lines will be created.
  • If file name is 1, lines will be created based on the prisms in the existing grid and the NS boundary condition set in the bcs file.
  • If file name is a valid *.poin1 file, lines will be created based on the information in this file.
(In all cases, for mcell files, no further prism merging can occur) VGRID MESHES:
  • If file name is "none" or 0, no lines will be created and no prizm merging will occur.
  • If file name is 1, the standard poin1 file named *.poin1 (where * is the prefix for the cogsg file) will be used.
  • If file does not exist, an error will occur.
  • If file name is a valid *.poin1 file, lines and prizms will be created based on the information in this file.
  • If file does not exist, an error will occur.
DIST FILE: Distance function file. There are 4 methods for computing distance function.
  1. Brute force search
  2. Octree search (disabled/not supported)
  3. Eikonal equation solver
  4. Marching spheres algorithm
If the specified distance function file is not found, pre_nsu3d will automatically choose the brute force method for dist function calculation and write out a distance function file with the specified name. The next time pre_nsu3d is run with the same inputs, the distance function file is read in, and the recomputation of the distance function data is avoided.

This behavior can be modified by specifying a numerical value in the place of the dist file name:

0: Do not compute the distance function (suitable for cases with no turbulence model)
1: use brute force method (recommended if using many processors)
2: use octree method (currently disabled/not supported)
3: use eikonal equation
4: use marching sphere algorithm (requires pre_nsu3d to be linked to the drums library)

The brute force method may take a significant amount of time but scales well on large numbers of cores. This is the default method as it gives the exact distance function result and is the most robust overall. The marching spheres method yields the same exact result as the brute force method but runs considerably faster by making use of an efficient search technique. This is enabled through the drums library. For large grids, this method is preferable to the brute force search method.

The main issue with this approach is that it occasionally results in failure. In this instance, the brute force search method should be used. The Eikonal equation solver relies on the solution of a PDE to obtain the distance function and scales well, although it requires cpu time equivalent to several hundred flow solver iterations. The Eikonal equation solver method yields an approximate distance function which will not be exactly the same as the other methods. Convergence tolerances on the Eikonal equation solver can be set as optional parameters in the input file; examples of such input files are shown here: When the distance function is computed using a numerical option in the place of a file name, the results are written to the file *.new.dist This file can be renamed (for example *.dist) and specified in the pre_nsu3d input list and will then be used in subsequent pre_nsu3d runs for the same mesh.

The bcs file is typically the same file used for NSU3D runs. The bcs file sets the bc's in the mesh. Note that new bc's can be specified at NSU3D run time, but the number of bc's and their assignment to patches cannot be changed at NSU3D run time. Thus, the patches that share a particular instance of a bc are determined at preprocessing time by pre_nsu3d. It is also used here to specify NS surfaces for merging prisms and growing lines.

Name of the component file. The component groupings are preset at preprocessing time by pre_nsu3d. Forces can be reported based on components that are defined as groupings of patches, and bodies that are defined as groupings of components.

NLEVELS: Number of multigrid levels.
NLEVEL=1 implies no multigrid, only the fine grid is processed. In this case, the amg file is ignored.
NLEVEL > 1 invokes the construction of coarse multigrid levels through agglomeration.

Example input file: input.prensu3d.VGRID.pzmlayer

This is an optional input that corresponds to the number of prism layers at the edge of the boundary layer that are left as tetrahedra in the prism merging operation (vgrid mesh files only). Because these cells at the edge of the boundary layer can be ill conditioned, it is beneficial to leave them as tetrahedra (i.e. not to merge them into prisms.) If a valid prism mesh cannot be obtained, increase this number gradually until a valid mesh is obtained.

The default value is 2. Usually, a value of 4 will be sufficient to remedy any problems. If a value other than 2 is required add the header line (at the end of the input file) and the number below the line as: OPTIONAL NLAYER OF PRISMS TO REMOVE 4.

Here are some reference sample input files for prensu3d:

Running prensu3d

pre_nsu3d requires as input a grid (*.edge) file, a distance function (*.dist) file, a boundary condition (*.bcs) file, optionally a component (*.comp) file. The output of pre_nsu3d is not a file, but rather a directory containing a series of files. The user need not be concerned with the contents of the individual directory files. The directory can be copied, moved, or tarred up and ftp'ed to remote machines without individually listing the contained files. The flow solver nsu3d need only be given the directory name as input.

pre_nsu3d can be invoked in several ways:
  1. Running pre_nsu3d and amg3d by hand
  2. Using the script
  3. Invoking the script
1. Running pre_nsu3d and amg3d by hand On the first pass, pre_nsu3d is run to get an amg file, then amg3d is run, and then pre_nsu3d is run again. See the tutorial for this specific preprocessing method.

2. Python script intended to replace the script used with the old serial pre-processor routines, see

The Python script is provided for user convenience and as a replacement for the shell script that shipped with the previous releases of the NSU3D utilty codes.

If installed correctly, typing with no arguments produces a brief summary of the command line options, while typing -h produces more detailed usage instructions.

The script can be used in two modes. The first emulates the behavior of the original script where the arguments are in a specific order: {case-name} {grid directory} {NMESH} {NPART} {Optional Parameters}

The second is more flexible and allows the arguments in any order using flags: -m {NMESH} -p {NPART} -c {case-name} {Optional Parameters}

By default the second mode will attempt to identify a usable grid using the case name in the current directory or in the directory specified with the -g flag.

3. Script to run pre_nsu3d and amg3d in sequence when required pre_nsu3d: NSU3D preprocessor amg3d: sequential agglomeration drums: Library for fast distance search (links to pre_nsu3d)

After the script runs, the terminal output will be saved to output.prensu3d and the input files for pre_nsu3d and amg3d will be left in the working directory. This can be useful, allowing the codes to be easily run manually if there are problems with the automated script.

Additional prensu3d Information

In addition to creating partitioned data for parallel execution of the flow solver, pre_nsu3d also in-corporates various other pre-processing operations previously contained within the flow solver itself in older versions of nsu3d. (These include reordering data for cache or vector efficiency, building coarse grid data structures, assigning boundary conditions, checking mesh and multigrid level consistencies .etc..).

The output directory produced by pre_nsu3d contains three files for each processor of a parallel nsu3d run:
  • header.n : A formatted test file containing information on the number of points and other entities for the partition of the grid belonging to processor n, where the range of n is 0 to number of processors-1.
  • order.n : An unformatted file with the original vertex ordering information (with respect to the unpartitioned data) for each partition n.
  • part.n : An unformatted file containing all grid and other information required by the flow solver for partition n.
Therefore, when running on 128 processors, for example, the pre_nsu3d output directory will contain 384 files. When running sequentially on a single processor, this directory will contain only 3 files.

The number of partitions/processors is specified as input to pre_nsu3d, which in turn determines the configuration of the output directory. Note that the flow solver nsu3d can be run efficiently on a number of processors which is any sub-multiple of the number of grid partitions. Therefore, it is advisable to partition the grid at the outset into a number corresponding to the maximum number of available processors, even if it is expected to be run most of the time on a smaller number of processors. For example, if 32 processors are available and the grid is partitioned into 32 parts, the solver can be run efficiently on 1, 2, 4, 8, 16 or 32 cpus, which can be specified at run time.

Compatible Model Grids

VGRIDns Meshes

VRGIDns is a NASA Langley developed grid generator which produces high quality stretched meshes suitable for Navier-Stokes calculations. VRGIDns produces fully tetrahedral meshes exclusively. However, VRGIDns also produces a *.poin1 file which can be used to identify the structure of the tetrahedra in the viscous regions.

The relevant output files from VGRIDns for the NSU3D package are:
  • .cosgs file : contains mesh connectivity and coordinates
  • .bc file : describes surface point to geometry patch information (not to be confused with the .bcs boundary condition file)
  • .poin1 file : describes surface point to semi-structured tetrahedra vertex information in viscous regions
Using these three files, a mixed prismatic tetrahedral mesh can be constructed.

ugform is used to reformat the *.cosgs and *.bc VGRIDns grid files into a *.cell file. This *.cell file describes a fully tetrahedral mesh. The mesh merging operation is then performed in two phases, first by running this *.cell file and the VGRIDns *.poin1 file through the merge1 program, and then running the result produced by this procedure through the merge2 program, which produces a new *.cell file, which now corresponds to a mixed prismatic/tetrahedral mesh, which usually also contains a small number of pyramids. This new *.cell file is now used as the basis for all subsequent pre- and post-processing operations in the NSU3D package. The *.poin1 file is also required as input to the amg3d agglomeration multigrid pre-processing program, and therefore should not be discarded.


ICEM Tetra grids can be output directly in the *.cell format for nsu3d, by selecting the NSU3D output option. However, these are labeled as *.bin upon output from ICEM Tetra. These are probably best relabeled with a *.cell suffix. Since ICEM Tetra can produce mixed prismatic- tetrahedral grids directly, there is no need for a merging process. However, ICEM Tetra does not produce a *.poin1 file. A separate facility called makepoin1 is available for reconstructing this file, since it is required by the amg3d agglomeration multigrid pre-processor.

Boundary Condition File

The suite of grid preprocessing codes called by prensu3d requires a boundary condition (*.bcs) file as input in order to determine the boundary conditions for the input grid. Therefore, the boundary condition (*bcs) file should be constructed prior to the grid preprocessing operation. The boundary conditions are based on the patches of the geometry. Each surface patch is assigned a boundary condition type and the surface grid faces that lie on each patch inherit the boundary condition type of their underlying patch.

The preprocessed grid thus contains all the boundary condition information and this is used by the solver at run time by default. For reference, a copy of the bcs file used by pre_nsu3d is written to the partitioned grid directory as GRID.bcs. Optionally, a different bcs file may be used by the solver at run time However, although the boundary condition types and parameters may be changed, the instances of the boundary conditions and their association to patch numbers may not be changed at run time and the optional bcs file used by NSU3D must contain the same instances and patch associations as the original boundary condition file used in preprocessing the grid (athough different bcs types may be assigned to these boundary condition instances). To avoid user confusion, when NSU3D reads in the optional bcs file, since the patch assignements are to be ignored, these should be proceeded by a # sign. NSU3D will stop execution if the optional bcs file does not contain these # characters. An example of an optional bcs file with # signs inserted in front of the patch lists can be found hereExample Optional BCS File.

The relevant boundary condition types are:
  • INSBC: Viscous wall (no slip) boundary condition.INSBC: Viscous wall (no slip) boundary condition.
  • ITBC: Inviscid wall (tangential flow) boundary conditionITBC: Inviscid wall (tangential flow) boundary condition
  • IOBC1: Outer Boundary Condition (implemented as Rieman invariants)IOBC1: Outer Boundary Condition (implemented as Rieman invariants)
  • IOBC2: Outer Boundary Condition (Rieman invariants with specified pressure at subsonic outflow)IOBC2: Outer Boundary Condition (Rieman invariants with specified pressure at subsonic outflow)
  • IOBC3: Outer Boundary Condition (implemented as fixed freestream values) Recommended far field bc.IOBC3: Outer Boundary Condition (implemented as fixed freestream values) Recommended far field bc
  • IFIN: Fan inlet boundary condition for engine power simulations.IFIN: Fan inlet boundary condition for engine power simulations.
  • IFOUT: Exhaust outlet boundary condition for engine power simulations.
Note that some boundary conditions can be specified multiple ways. The bcs file reader searches for the key words DEFAULT and BCTYPE, so that blank lines or comment lines can be inserted anywhere in the file. However, each boundary condition type requires a specific list of parameters associated with it. A default boundary condition is first applied to all patches, and then may be overwritten by additional specific entries in the *.bcs file. Any boundary condition can have multiple instances. A patch listed multiple times will ultimately end up with the boundary condition applied to the last instance of this patch in the boundary condition file. In order to check for the correct assignment of boundary conditions, the boundary condition file can be used as input to TECFORM along with the *.cell or *.mcell grid file. This produces a TECPLOT file with zones created and named for each boundary condition type, which can then be viewed in TECPLOT.

A sample boundary condition file is given below:
  • Line 1: contains a descriptive title.
  • Line 3: Number of patches on the geometry: This is used to check that the current boundary condition file is consistent with the grid file for the current case. If this is not the case, NSU3D will terminate after reading in the boundary condition file with an error message.
  • Line 5: The default boundary condition type is specified here. This bc type is applied to all patches of the geometry. Individual patch boundary conditions are then overwritten according to the entries which follow in the *.bcs file.
  • Line 8: The tangential boundary condition is set here (ITBC). For viscous flow calculations, this boundary condition is used for symmetry planes. For inviscid runs, this boundary condition can be used for all solid walls. The patches which inherit this boundary condition type are listed on Line 10 separated by commas. Any number of patches can be listed. Multiple instances of the same boundary condition can be used for very long lists of patches.
  • Line 13: The outer boundary condition type is set here (IOBC3). This requires specification of the far field pressure and temperature. For external flows with no power boundary conditions these should be taken as: PINF = 1.0, TINF = 1.0 The patches which inherit this boundary condition type are listed on Line 17 separated by commas. Any number of patches can be listed. Multiple instances of the same boundary condition can be used for very long lists of patches.
  • Line 21: An engine (fan) inlet boundary condition is specified as IFIN. This bc type can be specified in various ways (see IFIN specification page). The current example uses the specification of a static pressure PSTAT on Line 22. This value is relative to the freestream static pressure. The patches which are assigned this boundary condition are listed on Line 24. Any number of patches can be listed. Multiple instances of the same boundary condition can be used for very long lists of patches.
  • Line 28: An engine outlet boundary condition is specified as IFOUT. This bc type requires the specification of a stagnation pressure and temperature, PSTAG_REL and TSTAG_REL on Lines 29 and 30 and MACH number of Line 31. These value are relative to the freestream stagnation values. Note that the stagnation conditions of the freestream depend on the freestream Mach number specified in the NSU3D input file. The patches which are assigned this boundary condition are listed on Line 33. Any number of patches can be listed. Multiple instances of the same boundary condition can be used for very long lists of patches.

Component File

The name of a component file can optionally be specified as input on Line 11 of the parameter input list. If no component file is available, the entry none on Line 11 will cause ugform to automatically create a single component and a single body for the entire grid. To specify various components and bodies on the grid, a component file is created by the user the name of which is specified on Line 11 of the ugform input list. A sample component file is shown below. Components are specified as groups of surface patches, and bodies are specified as groups of components. Each component/body must be assigned a name, and all patches/components must belong to only one component/body.
  • Components are listed first, this is done in lines 1, through 30 in the component file. Line 6 denotes the number of components. The names of these components are listed consecutively beginning on line 8.

  • The patches which constitute each component are then listed beginning on line 15 (in this example), with possible exceptions beginning on line 26 (for this example). Each definition line contains the component number, and a beginning and ending patch number. All patches between these two values are assigned to that component. Patches can be listed multiple times in this assignment. Their component assignment is overwritten with the latest assignment value when they are specified multiple times. The EXCEPTIONS specification also overwrites the component numbers for particular patches. This portion of the file can be deleted (i.e. Lines 23 - 30 inclusively) if no exceptional patches are listed.

  • The specification of bodies begins on Line 35. This specification is similar to that of components except that bodies are composed of sets of components rather than patches. The number and range of the components must of course be consistent with that specified in the first portion of the component file.