Grid Setup
The grid { }, diagnostics { } and periodic { } blocks inside unst { } describe the mesh the solver
runs on: where it comes from and how it is transformed, how degenerate cells are detected and filtered,
and how periodic domains are set up. Meshes are typically generated with the
LAVA Voronoi Mesher; any polyhedral CGNS grid can be used.
Grid File and Transformations
The grid is expected to be in CGNS format, written as arbitrary polyhedrals (even if the grid is made up of only standard element types). Only a single volume zone is supported while each following surface zone is interpreted as a separate boundary condition (BC).
The grid file name is specified as:
Note that the specified grid file (or a symbolic link to it) needs to be present in the same directory as the input file. Otherwise, you can enter the full file path.
Multiple grid files can be specified. The solver will automatically merge the multiple grids and associate each with a domain id.
A grid file may also contain several volume zones; each zone becomes its own domain. Domains are numbered in (file, zone) order, so one multi-zone file is equivalent to the same zones supplied as separate single-zone files.
Some basic grid transformation operations are possible within the grid file. See the examples below:
grid {
file = grid.cgns
# Scale the grid by a factor of 2
transform_1 {function=scale; factor=2}
# Translate the grid 1 unit length in x direction
transform_2 {function=translate; distance=[1,0,0]}
# Rotate the grid 90 degrees around y axis with an origin of (0,0,0); the axis may be any nonzero vector
transform_3 {function=rotate; center=[0,0,0]; axis=[0,1,0]; angle=90}
# Convert 1-cell thick (essentially 2D) grid into axisymmetric (wedge shape)
# Depth is assumed to be in the depth direction, while y-coordinate is the height.
transform_4 {function=axisymmetric; y_center=0, y_tolerance=1.e-6, angle=5}
}
Info
Everything else in the input file and the case setup need to be with respect to the already transformed grid.
The transformations are applied in the given order. You can list as many transformations as needed. If no transformations are needed, the transform inputs can be skipped.
The unstructured solver operates on "tiles" of cells for computational efficiency. Size of these tiles, i.e. approximately how many cells there should be in each tile, can be specified as:
The tile size affects the computational performance of the code, and its optimum value depends on the type of grid and the architecture of the system being used. There are built-in default "best practices" for several NAS systems so you may choose to skip specifying a tile size in favor of the defaults. In general, especially if you are running large scale cases, it is best to experimentally determine the best choice for tile size.Additional partitioning controls are available to customize the METIS partitioning algorithm used for tile creation:
grid {
file = grid.cgns
tile size = 1024
# Enable cell-based weighting during partitioning
# When true, uses number of faces per cell as weight for load balancing
# When false, treats all cells with equal weight (default: false)
do partition weights = false
# Choose partitioning method for tile creation
# true: Use graph-based partitioning (cell-to-cell connectivity)
# false: Use dual mesh partitioning (face-based connectivity) (default: false)
do graph tile partition = false
}
These partitioning options are optional and control how METIS creates computational tiles. The do partition weights option defaults to false, meaning all cells are treated with equal weight during partitioning. When enabled, it uses the number of faces per cell as a weight, which can improve load balancing by accounting for computational cost differences between cell types (e.g., tetrahedra vs hexahedra). The do graph tile partition option also defaults to false, using dual mesh partitioning where faces are treated as nodes. When set to true, it switches to graph-based partitioning using direct cell-to-cell adjacency, which typically produces higher quality partitions but may have different performance characteristics depending on mesh topology.
Note
If the unstructured mesh in question was a Voronoi tessellation of the computational domain created by the LAVA Voronoi Mesher (see the Voronoi Mesh Generator section for details), then the coordinates of the cell generating points, i.e. seeds, are provided in the mesh file. In this case, the user has the choice to read the seed coordinates information from the *.cgns file, the choice to use these coordinates instead of the cell centroids and the choice to use the location where the line segment between two neighboring seeds intersect their respective face instead of the face centroid as the flux exchange location. Additionally, the user can choose to include a correction to green-gauss gradient operator exclusive to Voronoi-type meshes. This correction was explained by Volker Springel in his 2009 paper. These behaviors are controlled by the following parameters, all of which are disabled by default.
By default, grid diagnostics is active (see the Diagnostics section for details).
Diagnostics
At runtime, solver will analyze the grid to determine problem cells. In most cases, these are cell that are deemed degenerate or problematic for solver stability. The cells marked as problem are filtered out, meaning they are not solved for. Instead, they are updated at each step by averaging their neighbor values. A summary of how many cells were filtered is provided at run time.
The diagnostics metrics and default threshold values are specified as listed below. Note that the defaults are designed to catch the most severe problems and have been calibrated to ensure solver robustness. In most cases, keeping the default values are recommended. If you are using defaults, this section or any default entry is not required to be present in the input file.
diagnostics {
# Maximum allowed angle (in degrees) between face normal and
# the vector connecting the two adjacent cell centers
max nonorthogonality angle = 90.
# Maximum order of magnitue change of volume between adjacent cells
max volume change order = 4.
# Checks accuracy of cell gradient stencil/weights vs a linear function
# The error is normalized and specified as percentage.
max gradient error = 1.e3
# Check convexity of cells
do convexity check = true
# Check if a cell is watertight
max green gauss error = 1e-8 # 1e-3 for FLOAT executable
# Check if all faces have a valid neighbor cell
# if the face is not a BC and a neighbor face was not found, abort the run
do face neighbor check = true;
# Check how skewed the angle from cell-centroid-to-neighbor
# versus the cell-centroid-to-face-centroid vector is. Input in degrees,
# between 0 and 180. The default 0 flags no face: give a threshold when
# turning the check on.
do neighbor face angle check = false
min face centroid angle = 0
# Check how close the cell centroid is to its faces. Diagnostic is normalized
# as (min face dist)/(max face dist) for a pair of cells on either side
# of a face, so the threshold is between 0 and 1. The default 0 flags no
# face: give a threshold when turning the check on.
do face dist growth check = false
min face dist growth = 0
# Check isotropy of the cell. Closer to 1 means perfectly isotropic.
do iso factor check = false
min iso factor = 0.25
# If the following is set as nonzero, then cell diagnotics are tracked into
# histograms with the given number of bins and output as CSV files.
# There is one CSV file per test, stored in
# the folder "diagnostics" under the file names
#
# face_planarity.csv, face_orthogonality.csv, cell_convexity.csv,
# face_alignment.csv, cell_size_filtering.csv, volumetric_jump.csv,
# green_gauss.csv, gradient_err.csv, face_neighbor_angle.csv,
# face_equidistant.csv, and cell_isotropy.csv.
#
# The green_gauss.csv is given in log scale. The cell_size_filtering.csv
# always uses 10% filter size bin widths, matching the terminal output.
histogram bins = 0
# If the following is activated, user manually mark additional problem cells
# by listing their global ids (ids as in the provided grid file) in an ASCII file
#problem cell file = problemcells.txt
#
# When enabled, write the geometry and flow solution of any problem cells to
# volume/Unst.problemCells.<step>.cgns at every startup (fresh start and restart).
# On an abort triggered by robust mode, the file is named
# volume/ABORT_Unst.problemCells.<step>.cgns instead.
# Output is skipped automatically if no problem cells exist.
# This option is TRUE by default
dump problem cells = false
}
Tip
At every startup, if any problem cells are found, the solver automatically writes their geometry and flow solution to volume/Unst.problemCells.<step>.cgns. This file can be opened in ParaView to visually inspect where the problematic cells are located in the mesh.
Warning
If you encounter a segfault during problem cell output, please try tunring it off and running again.
Another use of the diagnostics for runs using explicit time integration is to filter-out cells that are too small. The filtered cells do not contribute to CFL computation and do not cause time step size restrictions. By default, each filtered cell is merged with a neighbouring cell into a single control volume (agglomeration); a filtered cell that cannot be merged is treated like the other problem cells. You can leave this unspecified if not using explicit time integration.
diagnostics {
# Specify minimum cell size intended when grid was created
target size filter = 4e-3
# The solver places the filter between half the target size and the target size, where the
# tail of undersized cells ends (size filter method = knee, the default), and never filters
# more than this percentage of the cells. With size filter method = percent, it raises the
# filter from the minimum size toward the target size as far as this percentage allows.
max percent filtered = 0.05 # default
# You can also manually specify a hard cut-off for the minimum allowed cell size; cells
# below it are always filtered. By default, it is half of the target size filter
min size filter = 2e-3
}
Periodic
The domain can be setup as periodic in x,y,z directions. However the grid must be built with special considerations in one of two ways. One option is to apply extra grid cell padding (at least two cells thick on both periodic ends) to act as periodic fringe exchange locations. Ideally, these padding cells, when shifted in the periodic direction by the domain width, should match interior cells perfectly on the other end. There are tools to mirror and extrude the cells to fit this criteria. Alternatively, the connectivity between cells at the periodic boundary must be correctly accounted for during the mesh generation step. This can be achieved in the LAVA Voronoi mesher, for example, by creating ghost periodic cells with the correct parent id where necessary. The end product is a seamless periodic domain generation.
If the first option is chosen and the grid is prepared, inputs for periodic setup are:
periodic {
# Activate periodicity in y-direction
do y = true
# Interior domain bounds in periodic direction
ymin = -0.0325
ymax = 0.0325
# In case periodic fringes do not exactly overlap with donor cells,
# perform interpolation
do interpolation = false # default
# Test the periodic setup by performing an interpolation
# for coordinates and checking linear exactness
# false by default
do test projection = true
}
The example above is only for y-direction. Periodicity can be activated in other directions at the same time. Here is an example for a triple periodic setup:
periodic {
# Activate periodicity in all 3 directions
do x = true
do y = true
do z = true
# Interior domain bounds in periodic direction
xmin = -0.5
xmax = 0.5
ymin = -0.5
ymax = 0.5
zmin = -0.5
zmax = 0.5
}
Alternatively, if the periodicity was included in the mesh generation process in a way that correctly accounts for the periodicity and connectivity of the cells, then the user should inform the domain boundaries in each axial direction and turn on the face translation corrections via the following parameters: