makepoin1 is a pre-processor that is required when using grids generated with ICEM-CFD meshing tools. makepoin1 takes as input the ICEM generated cell file (usually named with a .bin extension) as input and calculates the first point distance from solid bodies required by the turbulence models in NSU3D.
A sample input file for makepoin1 is shown below:
meshcut
The meshcut utility cuts the mesh based on distance function and/or layer.
Run this code before runing extract.
dist_cut > 0: cut node's dist > dist_cut
layer_cut > 0: cut node's layer > layer_cut
setwallbc
The setwallbc utility provides a means to 'hard-wire' surface boundary conditions into a NSU3D grid file. A typical use for this would be to specify surface temperature on a patch by patch basis. This utility is for advanced users since it requires modifying parameters in the source code and compiling. It is mainly intended to provide a means to set custom values on boundaries that are not available through the existing boundary condition types.
Comments in the source code indicate where the custom definitions should be placed, but it is up to the user to ensure that the resulting boundary conditions are valid.
ugcombine
The ugcombine utility combines various input grids into a single unstructured grid data set.
To get an example input file, run the utility, type 'input' and press enter.
ugcombine takes the following files for each component grid:
*.mcell.unf --> Mixed cell grid file
*.poin1 --> Boundary Layer Lines from VGRID or makepoin1 code
*.bcs --> Boundary condition file
Note that these are NSU3D grid file formats.
If a grid has been generated in VGRID, then it must
be passed through merge1/merge2 to get a mixed element mcell file
before proceeding to ugcombine.
If a grid comes from ICEM or other mesh generator which generates
mixed element grids, it must be passed through makepoin1 to get a poin1 file.
The bcs file for each component must be built manually as if each
individual grid file were to be run with NSU3D.
The poin1 is optional and may be omitted for inviscid grids.
The bcs file can be omitted but one will need to be created manually
for the combined grid in this case.
Because VGRID and other parts of the NSU3D preprocessor make
assumptions about node ordering, the grid nodes must be re-ordered
upon combination.
The ordering is such that all boundary vertices appear first and then all
prizm layer nodes (ie. the poin1 vertices) appear next, with the remainder
of the vertices appearing afterwards.
The number of bodies in the mcell file :nbod
is used to tag the number of component grids, and each
grid point has a tag to identify the component grid
to which it belongs. This tag list is written to the
bottom of the new mcell file, which is then
read in by extract and re-written at the end of the
edge file created by extract. This info is then partitioned
later by pre_nsu3d.
*****NOTE: For this, versions of extract.2.9d and higher are required.
Older versions will not read the tag id.
*****NOTE: Requires version pre_nsu3d.3.b.3d
The number of patches and components are concatenated from
each individual component grid.
ugform
ugform is a facility to reformat a VGRID grid file into a *.cell file for NSU3D. ugform can also be used to define components and rescale a VGRID grid file, or an existing *.cell grid file. ugform will convert VGRID files directly to consistent *.cell files, even in the case of viscous grids generated from VGRIDns. In this case, the surface triangulation connectivity specified in the VGRID file *.bc is incorrect, although the surface patch information contained in this file is correct. ugform accounts for this and recomputes the correct surface triangulation connectivity.
A sample input file for ugform is given below:
Line 1 contains a descriptive title. Various input file formats are supported. The most common is the cogsg VGRID file format. In this case, the file FORMAT on Line 3 is set = 3.0 and the file name refers to a VGRID cogsg unformatted file. The entry on line 5 is then not read. Older VGRID *.int and *.grd files can be read in by setting FORMAT=1 (formatted *.int *.grd) or FORMAT = 2 (unformatted *.intu, *.grdu) on line 3 and 5, while specifying the appropriate file names on these lines. Finally, existing *.cell files can be read in, in order to rescale them or redefine the components. This is achieved using FORMAT = -2 on line 3, with the entries on line 5 being ignored.
For grids generated from VGRID, the bound (*.bc) file must be specified on line 7. This file is always formatted, IFORM = 1.0
The patch to BC file is obsolete and should be set to "none" on line 9.
The component file, described in the next section, is specified on line 11. This is always a formatted file, IFORM = 1.0.
The output *.cell file name is specified on line 13. This should be an unformatted file, using IFORM = 2.0
A scaling factor is specified on line 15, which can be used to rescale the grid by multiplying all coordinates by this factor. In general, grids with dimensions near unity are preferred, since this may prove more robust in subsequent pre-processing operations. To avoid rescaling the grid, use a scaling factor of 1.0
Component File
The name of a component file can optionally be specified as input to ugform, 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 in Figure 6. 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.
prensu3d.sh
When the NSU3D tool suite is installed as detailed above, there is a shell script called PRENSU3D.sh that can be used in lieu of running the individual post-processing tools in order to prepare a supported mesh type for running in NSU3D, as well as performing other tasks, such as re-partitioning or defining a new set of multi-grid levels for the model.
Executing the script with no arguments produces a brief summary of usage options:
In most cases, the default options will produce a valid set of case files for running the flow solver as long as the values of NMESH and NPART are appropriate where:
NPART = Number of mesh partitions for parallel execution. The parallel solver will run as long as the number of partitions is evenly divisible by the number of mpi processes launched.. i.e. 8 partitions will run on 8, 4, 2, or 1 processes, but not on 3, 5, 6, 7 or more than 8 processes.
NMESH = Number of grid levels to construct for the multigrid convergence acceleration scheme employed by the flow solver. Typical values are 4 or 5, but this may be reduced if there are problem areas in the mesh.
amg3d
amg3d is the pre-processor which builds the coarse multigrid levels for the agglomeration multigrid algorithm employed by NSU3D
amg3d employs a graph algorithm to construct the coarse grid levels. Therefore, amg3d takes as input a *.edge grid file. The implicit lines are constructed either with a weighted graph algorithm, or by using information in the *.poin1 file which defines the normal structure of the prismatic layers. The output of amg3d consists of a *.amg file which contains all the necessary information for running the multigrid algorithm with NSU3D.
A sample input file for amg3d is given below:
The input (*.edge) file and output (*.amg) file and their formats are listed on lines 3 and 5respectively on the amg3d input list. While various options for these file formats are available, FORMAT = 2.0 should be used exclusively in all cases for both files.
The number of coarse levels to be generated is specified on Line 7. If too many levels are specified, such that too few points exist for adequate coarse level construction, amg3d may fail on these levels. If a failure occurs, simply reduce the number of levels until the code completes satisfactorily. Note that the total number of grid levels available to the multigrid algorithm in the solver is NLEVELS + 1, since the fine grid is not included in NLEVELS. Thus the parameter NMESH in the NSU3D input list may be set less than or equal to NLEVELS + 1. If NMESH exceeds this value, NSU3D will terminate before the multigrid solution process begins.
The parameters on lines 9, 11, and 13 determine the specifics of the agglomeration algorithm for constructing the implicit lines and the coarse levels.
ILINE (Line 9): Determines line construction algorithm.
ILINE = 0 omits any construction of implicit lines. Solver will run point implicitly only.
ILINE = 1 creates lines using weighted graph algorithm on each level.
ILINE = 2 creates lines using weighted graph algorithm on fine level. On coarse levels,
only edges which contain fine grid line edges can become lines.
ILINE = 3 creates lines using *.poin1 file information. Edges listed in this file are given
large weight to ensure they get chosen as a line edge by the weighted graph algorithm.
ILINE = 4 creates lines using *.poin1 file information exclusively.
IWEIGHT (Line 11): Controls weighting of graph algorithm.
IWEIGHT = 1: Use regular weighted graph.
IWEIGHT = 0: Do not use any edge weights. Line weights are still used.
IWEIGHT =-1: Do not use any edge or line weights.
IFRONT TYPE (Line 13): Governs the agglomeration front.
IFRONT TYPE = 1: Use aspect ratio priority queue. High aspect ratio points are
considered first.
IFRONT TYPE = 2: Use number of fine grid points as priority queue. Agglomerated
cells containing the fewest number of fine grid points are considered first.
IFRONT TYPE = 3: Regular front. Based on neighbors of previously agglomerated
points.
While there are various options for controlling the agglomeration specifics, in practice, only two settings are used:
For highly stretched viscous grids: ILINE=3.0, IWEIGHT=-1, IFRONT TYPE=3
For isotropic inviscid grids: ILINE=0.0, IWEIGHT=-1, IFRONT TYPE=3
These two individual settings should be used exclusively for most users.
distf3d
distf3d is the pre-processor which computes the distance function required by certain turbulent models in the flow solver, such as the Spalart-Allmaras one equation model. distf3d reads in a grid *.edge file and a boundary condition *.bcs file, and outputs a distance function *.dist file. The *.dist output file contains the distance for each grid point to the nearest boundary face on a Navier-Stokes no-slip boundary, as defined in the boundary condition file. Additional information, such as the identity of the nearest boundary face for each grid point is included in the *.dist file, but is not required by the turbulence model. The *.dist file is subsequently used as input for the flow solver or its pre-processor pre_nsu3d.
The computation of the distance function for large grids can become unacceptably expensive if a brute force search technique is employed. For this reason, a sophisticated octree searching technique is implemented. For smaller grids, or cases where the octree method may fail, the brute force technique can be used as a backup method.
There are three phases to the computation of the distance function. The first phase finds the closest boundary point for each field point. The second phase finds the closest location on a boundary face for each field point, using the neighboring faces of the closest point. The third phase checks and updates these distances if they are not the true minimum distances (for example if a closer face which is not a neighbor of the closest point can be found). Because this last phase can be very expensive, and only results in minor corrections, it can be restricted to points close to the boundaries.
A sample input file for distf3d is given below:
Line 3: Choose the formulation for computing the distance function. Formulation 1.0 selects the inexpensive, but inexact method based on finding the closest point. Formulation 2.0 selects the exact method (usual setting), which is more expensive.
Line 5: When the exact (=2.0) formulation is chosen, it is usually applied only in regions close to the boundary, to spare the expense of recomputing the distance function over the whole grid with the exact formulation. FDISTMAX determines the distance away from the boundary within which the exact formulation is employed.
Line 7: CLOSEST PT SEARCH METHOD: 1.0 selects the sophisticated and more efficient octree method, while 2.0 selects the simple but more expensive brute force method. Usual setting = 1.0. Brute force method can be used as backup method in case octree method fails.
Line 9: The input (*.edge) file and its format are listed on Line 9. FORMAT = 2.0 should be used exclusively here.
Line 11: The boundary condition (*.bcs) file and its format are listed on Line 11. FORMAT = 1.0 should be used exclusively here.
Line 13: The output (*.dist) file and its format are listed on Line 13. FORMAT = 2.0 should be used exclusively here.
dmin3d
A sample input file for dmin3d is shown below:
extract
extract is a facility for converting a *.cell file into a *.edge file. A *.cell file can be considered as the neutral file format for NSU3D. Any incoming grid must first be converted to the cell file format. This format contains a description of all the cells (mixed elements including tetrahedra, prisms, pyramids, hexahedra) and boundary faces (triangles and quadrilaterals). While this is the most compact and highest level representation of an unstructured grid, it is not suitable for an edge based flow solver such as NSU3D, which requires a list of (unrepeated) edges and edge coefficients. extract extracts the graph (list of edges) from the grid specified in the cell file, and builds the necessary coefficients required by the flow solver. The resulting edge files are several times larger than their generating cell files, and do not contain the cell connectivity information, the regeneration of which is a non-trivial operation when only edge data is available.
A sample parameter input file for extract is given below:
An input *.cell file name is specified on Line 3 and its format type on Line 5.
An output *.edge file name is specified on Line 7 and its format type on Line 9.
NSTERM (Line 11) : Parameter for selecting the type of edge coeficients to be included in the output file. Although various file format options are available, the use of FORMAT = 2.0 is recommended exclusively for all cases for both input and output files. For inviscid flow computations, NSTERM can be set to 0.0, and only inviscid flow edge coefficients will be computed. For NSTERM = 1.0, the edge coefficients required for the full Navier-Stokes terms are computed. However, this is only possible for a fully tetrahedral mesh, and for a mixed element mesh (containing prismatic elements for example) the edge coefficients for the thin layer viscous terms must be employed by setting NSTERM = 2.0. In general, NSTERM can be set = 2.0 for all cases.
merge1
merge1 is a program to reduce the complexity of three-dimensional tetrahedral grids by merging tets into prism elements. The .poin1 file generated by VGrid or by invoking the makepoin1 program is required.
A sample input file for merge1 is shown below:
The default values shown here should be used for most cases, as merge1 is an intermediate step in generating grids for NSU3D and the defaults usually produce good results.
merge2
merge2 is a program to create consistent faces in a mixed element grid for NSU3D. The program takes the ouput from the merge1 program which consists of non-contiguous merged prisms and tets and creates a valid mesh.
A sample input file for merge2 is shown below:
prensu3d
pre_nsu3d is the general pre-processor for the flow solver nsu3d. The principal function of pre_nsu3d is to create 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, build-ing coarse grid data structures, assigning boundary conditions, checking mesh and multigrid level consistencies .etc..).
There are three (3) different modes of operation for pre_nsu3d. In the automatic mode, pre_nsu3d reads in the grid and other associated file, partitions the data using an internally supplied partitioning strategy, and then writes out the partitioned data for the flow solver. This mode of operation is achieved by setting the parameter NOPTIM = 0.0
The internally supplied partitioning strategy produces sub-optimal partitions, and should only be used for small numbers of partitions (of the order of 4). In general, much better parallel per-formance will be achieved by making use of a better partitioning strategy. Therefore, an interface is provided to two externally available grid partitioners, the CHACO partitioner, described at http://www.cs.sandia.gov/bahendr/partitioning.html, and the MeTiS partitioner, downloadable from http://www-users.cs.umn.edu/karypis/metis/main.shtml.
In order to use an external partitioning code, pre_nsu3d must be invoked twice. The first run of pre_nsu3d is used to generate output files for the partitioner. In this mode, the NOPTIM parameter is set to a negative value (-1 or -2, depending on the partitioner to be used), and a separate file is generated for each grid level in the multigrid data set (including the finest grid). These files are then used as input to the grid partitioner. Each file must be partitioned into the same number of subdomains, and this must correspond to the parameter NPART in the pre_nsu3d input file. In the second phase, pre_nsu3d is run again with the same inputs, except that the parameter NOPTIM is now set to 1.0, and the partition files (generated as output from the partitioner) must be listed in the pre_nsu3d input file, under the heading PARTITION FILES, listing the fine grid partition file first, followed consecutively by the partition file for each coarser grid level. The fully partitioned output for the flow solver is generated as output from this run.
pre_nsu3d requires as input a grid (*.edge) file, a distance function (*.dist) file, a multigrid (*.amg) file, a boundary condition (*.bcs) file, and optionally, a list of partition files for each multigrid level. 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.
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.
A sample pre nsu3d input file is given below:
Line 3: The input grid (*.edge) file and its format are listed on Line 3. Format should always be = 2.0
Line 5: The input distance function (*.dist) file and its format are listed on Line 5. Format should always be = 2.0
Line 7: The input multigrid (*.amg) file and its format are listed on Line 7. Format should always be = 2.0
Line 9: The input boundary condition (*.bcs) file and its format are listed on Line 9. Format should always be = 2.0
Line 11: NOPTIM controls the mode of operation of pre_nsu3d.
NOPTIM = 0.0: Auto-partitioning mode. pre_nsu3d will use the internally supplied partitioner to partition data into NPART subdomains, and produce the output required by the flow solver. In this mode pre_nsu3d needs only be run once, but partition quality is generally poor.
NOPTIM < 0: Create output for external stand-alone partitioners. Output for either CHACO (-2.0) or MeTis (-1.0) can be generated. One file for each grid level of the multigrid algorithm is generated. These files are to used as input to the appropriate grid partitioning program.
NOPTIM = 1.0: Read partition files created by external partitioners, and generate final partitioned output required by flow solver. The partition files to be read in must be listed in the input file on Line 19 and below, starting with the partition fole for the finest grid, followed by each successively coarser grid.
Line 13: VECTORIZATION = 0.0 should be used for cases to be run on cache-based microprocessors. For vector machines, such as the Cray J90 or SV1, VECTORIZATION = 1.0 should be used, or false results may be produced. Using VECTORIZATION = 1.0 on a non-vector machine will result in sub-optimal performance. VEC_LENGTH defines the length of vector line vector groups for vector runs. (This is only relevant for the line solver, not for the regular grid edges). Large vector lengths will run faster on vector machines, but may incur more overall work because short lines need to be extended to fit the length of the longest line in the same vector group. VEC_LENGTH = 64.0 is a good compromise for most cases.
Line 15: NMESH defines the number of multigrid levels (including the fine grid).
Line 17: NPART defines the number of partitions. This must be consistent with the number of subdomains in the partition files to be read in, otherwise pre_nsu3d will abort.
Line 19: The names of the partition files, generated by an external partitioner, are listed starting on Line 19, and adding extra lines for each additional file name. There is one file name for each grid level, starting with the finest grid and ending with the coarsest grid. These file names are only required when NOPTIM > 0.