SU2 mainly uses a native mesh file format as input into the various suite components. Limited support for the CGNS data format has also been included as an input mesh format. CGNS support can be useful when it is necessary to create complex geometries in a third party mesh generation package that can export CGNS files. A converter from CGNS to the native format is built in to SU2. Details on how to create and use these mesh formats is given below.
The native format is straightforward and readable, and meshes for simple or analytic geometries can be made very easily using scripts like those provided below. However, for creating meshes around very complex geometries, third party meshing software can make the process much simpler than attempting to build meshes via scripting. With this in mind, support for the CGNS data standard has been included within SU2. Support is currently limited to mesh file input, but additional CGNS capability will be added in future releases. The main advantage gained here is that complex meshes created in a third party software package (one that supports unstructured CGNS file export) can be used directly within SU2. Furthermore, a converter from CGNS to the .su2 format has been built into SU2. While serial simulations with input CGNS meshes will execute in SU2_CFD, based upon the current level of CGNS support in SU2 (currently no parallel support or solution output in CGNS format, for example), it is recommended that the user converts their meshes to the .su2 format, in general.
Compiling with CGNS Support
First, obtain and follow the instructions supplied for building the CGNS library (Version 3.1.3 recommended) on the machine where SU2 will be running. The resulting library will be linked during the build process of SU2_CFD which is the only module that officially supports CGNS meshes at the moment. There are two methods for compiling with CGNS support: using the build_SU2.py script with special options, or by directly manipulating the makefiles.
To use the python build script to compile with CGNS support, the user needs to include the "--with-cgns" option followed by the paths to the CGNS library and header file. The options for the build script can always be viewed by typing "python build_SU2.py -h" at the command line. A typical call to the build script on Mac OS X for compiling with CGNS support might look like the following:
By default, it is assumed that the CGNS library and header file can be found in /usr/local/lib/ and /usr/local/include/, respectively. If your CGNS installation is in the default location, the "--cgns-inc-path" and "--cgns-lib-path" flags are optional. Otherwise, supply the paths to these files on your machine.
As mentioned, CGNS support can also be included by direct manipulation of the makefiles. A typical makefile.in for your machine might look like the following (found in the SU2_CFD/config/ directory):
To compile with CGNS support, first remove the "-DNO_CGNS" options from the list of C++ compiler flags. If this flag does not appear, the conditional statement below will activate, and the paths to both the CGNS library and header file must be supplied in the "LIB_CGNS" and "INC_CGNS" variables, respectively. Again, it is assumed that the CGNS library was built and installed in /usr/local/lib/ under the name libcgns.a and that the header file, cgnslib.h can be found in usr/local/include/. If you have built the library elsewhere, simply adjust the two paths to match their location on your machine. Note that if you are not building with CGNS support, these paths are ignored completely.
Using and Converting CGNS Meshes
In order to use a CGNS mesh (assuming the CGNS library has been installed and SU2 successfully compiled), the user simply needs to specify the input mesh format to be "CGNS" in the configuration file for their simulation. The configuration file option is "MESH_FORMAT=" and appears as:
Furthermore, a CGNS mesh can be converted to the .su2 format by setting the "CONVERT_TO_SU2=" flag to "YES" and supplying a new filename for the converted mesh in the "NEW_SU2_FILENAME=" option. These options might appear as follows in the configuration file:
It is important to note that SU2 will not use any specific boundary conditions which are set in the meshing software package before exporting the CGNS mesh. However, it will use the names given to each boundary as the marker tags. These marker tags are used to set the boundary conditions in the configuration file. Therefore, it is recommended that the user give names to each boundary in their mesh generation package before exporting to CGNS. If you do not know the number of markers or their tags within a CGNS file, you can simply attempt a simulation in SU2_CFD (leaving out the boundary information in the configuration file at first), and during the preprocessing stage, SU2 will read and print the names of all boundary markers to the console along with other grid information before throwing an error for incomplete boundary definitions. The user can then incorporate these marker tags into the configuration file with the appropriate boundary conditions.
Native Format (.su2)
In keeping with the open source nature of the project, SU2 relies mostly on its own native mesh format. The format is meant to be simple and readable. A description of the mesh and some examples are below.
The SU2 mesh format carries an extension of .su2, and the files are in a readable ASCII format. As an unstructured code, SU2 requires information about both the node locations as well as their connectivity. The connectivity description provides information about the types of elements (triangle, rectangle, tetrahedron, hexahedral, etc.) that make up the volumes in the mesh and also which nodes make up each of those elements. Lastly, the boundaries of the mesh, or markers, are given names, or tags, and their connectivity is specified in a similar manner as the interior nodes.
Consider the following simple, 2-D mesh for a square domain consisting of 8 triangular elements. It will be used to explain the .su2 mesh format.
The first line of the .su2 mesh declares the dimensionality of the problem. SU2 can handle 2-D or 3-D geometries. As a note, for 2-D simulations, it is recommended that a truly 2-D mesh is used (no z-coordinates) rather than a quasi-2-D mesh (one or more cells deep in the third dimension with symmetry boundary conditions). For the 2-D square, the dimension is defined as follows:
SU2 searches specifically for the keyword "NDIME=" in order to set the dimension, and the dimension value will be stored for use throughout the code. This value would be 3 for a 3-D mesh. Note that while "%" is used here to denote comments, SU2 does not officially recognize it as such. Extra text added to the mesh file between sections (such as lines following a "%") will simply be ignored. The next part of the file describes the interior element connectivity.
SU2 is based on unstructured mesh technology, and thus supports several element types for both 2-D and 3-D elements. Unlike for structured meshes where a logical, ordered indexing can be assumed for neighboring nodes and their corresponding cells (rectangles in 2-D and hexahedral elements in 3-D), for an unstructured mesh, a list of nodes that make up each element, or the connectivity as it is often called, must be provided. First, SU2 will search for the string "NELEM=" and then store the number of interior elements. This value is given first, as it is used to set up a loop over all of the elements which must immediately follow this line. For the square mesh above, this corresponds to the 8 triangular interior elements which are labeled from 1 to 8.
Each following line describes the connectivity of a single element. The first integer on each line is a unique identifier for the type of element that is described. SU2 supports line, triangle, rectangle, tetrahedral, pyramid, wedge, and hexahedral elements. The identifiers follow the VTK format:
VTK format guide for the correct ordering for each supported element type (page 9).Note that the .su2 format indexes the nodes and elements starting from zero, as opposed to starting from 1 as Tecplot does, which was used to create the mesh image. For example, take the triangular element described in the first line which is indexed as 0 (1 in Tecplot). The SU2 nodes are given as (0,1,3) which would correspond to (1,2,4) in Tecplot. Looking at the figure of the mesh above, we see that this is the lower left triangular element. The ordering of the nodes given in the connectivity list for a specific element is important, and the user is referred to the
After the connectivity information for all interior elements, the coordinates for each of the nodes are given. This is specified in the .su2 format as:
Again, SU2 searches for the string "NPOIN=" and stores the total number of nodes in the mesh. In this case, there are 9 nodes in the 3x3 square above. Immediately after the node number specification comes the list of node coordinates in cartesian (x,y,z) space. Each line gives the coordinates for a single node followed by its index number. The node index numbers are the indices used for specifying the connectivity information for elements. For a 2-D mesh, the x and y coordinates are given followed by the index, but a 3-D mesh would give x, y, and z, followed by the index. The location of each node can be confirmed in space by comparing with the figure above after adding 1 to the index value.
The final component of the mesh is a description of all boundaries (which we call markers), including a name (what we call a tag). For each boundary, the connectivity information is given which is based off of the same node indices given above. For a 2-D mesh, only line elements are supported along the boundaries. For a 3-D mesh, triangular and rectangular elements are the possible options for boundary elements. This section of the .su2 mesh file appears as:
First, the number of boundaries, or markers, is specified using the "NMARK=" string. Then for each marker, a name, or tag, is specified using "MARKER_TAG=." This tag can be any string name, and the tag name is used in the configuration file for the solver when specifying boundary conditions. Here, the tags "lower," "right," "upper," and "left" would be used. The number of elements on each marker, using "MARKER_ELEMS=," must then be specified before listing the connectivity information as is done for the interior mesh elements at the start of the file. Again, the unique VTK identifier is given at the start of each line followed by the node list for that element. Note that no index is given for boundary elements. For our example, only line elements (identifier 3) exist along the markers, and on each boundary of the square there are 2 edges of a triangle that make up the marker. These elements can again be verified with the mesh figure above.
Third Party Meshing
We are continuously working to integrate SU2 with industry-standard tools. Our most recent success was building an output plugin for the Pointwise(R) meshing software. This custom addition allows users of Pointwise version 17.00 and later to directly output their meshes in the native SU2 format. The plugin is available from this website, and will be included with the next version of Pointwise (V17.0R2).
Attached here is the simple square mesh from above in .su2 format, along with codes for creating this file in the Python, C++, and Fortran 90 programming languages. These scripts are meant to be examples of how to write .su2 meshes in a few common languages which can be easily modified for creating new meshes: