How To Use Su2msh For Seamless CFD Mesh Conversion

The su2msh utility converts external mesh files—such as Gmsh, Fluent, or CGNS formats—into the native SU2 format required for high-fidelity computational fluid dynamics simulations. By utilizing precise command-line arguments and structured configuration parameters, users can translate complex unstructured topologies while preserving critical boundary markers and spatial dimensions. Mastering this conversion process ensures optimal solver compatibility, proper boundary condition mapping, and reliable numerical convergence.

Pre-Conversion Requirements and Mesh Planning

Before initiating the mesh conversion process with the su2msh utility, proper preparation of the input grid is essential. The su2msh utility functions as a translator that parses node coordinates, element connectivity, and boundary markers from third-party grid generators. It then reformats them into the unstructured format required by the SU2 solver. If the source file contains geometric errors, inverted elements, or unassigned boundary surfaces, the conversion will either fail outright or produce a corrupted file that causes the solver to diverge during the first iteration.

To ensure a smooth transition from your grid generation software to the SU2 ecosystem, you must verify both the hardware environment and the structural integrity of your source mesh. The converting system must have enough random access memory to load the entire source mesh into memory alongside the generated node tables. For extremely large meshes exceeding fifty million elements, this requires a high-performance workstation rather than a standard laptop.

Essential Gear, Software, and System Requirements

• SU2 Suite Installation: Ensure that the SU2 executable suite, which includes the mesh utility (frequently compiled as SU2_MSH or invoked via su2msh depending on your installation path), is correctly installed and added to your system environment variables.
• Grid Source File: A validated mesh file exported from an external pre-processor. Supported formats include Gmsh (version 2.2 ASCII format is highly recommended for stability), Fluent (MSH format), CGNS (binary or ASCII), or Plot3D.
• Text Editor: A robust plain-text editor capable of handling large files, such as VS Code, Notepad++, or Vim, to create and edit configuration files.
• Boundary Mapping Blueprint: A pre-defined list of all physical boundaries (e.g., wing_surface, farfield, inlet, outlet) matching the exact names or ID numbers assigned in your mesh generation tool.
• System Budget and Time Benchmarks: Conversion times range from less than five seconds for small two-dimensional research grids to thirty minutes for complex, multi-million-element aerospace configurations. Memory allocation requires approximately two gigabytes of RAM per ten million mesh elements during translation.

Step-by-Step Grid Translation and Boundary Setup

Converting a mesh file using the su2msh utility requires a systematic workflow. This workflow spans from the initial export in the native generator to verifying the structural validity of the final output file.

Step 1: Exporting the Source Mesh Correctly

The most common point of failure in mesh conversion occurs at the export stage within the parent grid generator. If you are using Gmsh, you must export the grid in the legacy Version 2.0 or 2.2 ASCII format. Modern versions of Gmsh default to Version 4.0, which contains structural differences that the SU2 parser may not read correctly without specific flags.

When defining boundaries in your mesh generator, you must assign every boundary face to a unique physical group. Do not leave surfaces as elementary entities. If a surface is not assigned to a physical group, the su2msh tool will omit those boundary faces, leaving the solver unable to apply boundary conditions.

Warning: Never use spaces, mathematical symbols, or special characters (such as slashes, asterisks, or hash signs) in your physical group names. Use underscores to separate words, as special characters can corrupt the output configuration file parsing.

Step 2: Preparing the SU2 Configuration File

The su2msh utility relies on an SU2 configuration file with a dot-cfg extension to guide the conversion process. This configuration file defines the input format, output format, dimension constraints, and path variables.

Create a new file named mesh_conversion.cfg in your working directory and define the following key-value pairs:

• MESH_FILENAME = input_mesh_file.msh (Replace this with the exact name of your source mesh file).
• MESH_FORMAT = GMSH (Specify GMSH, FLUENT, CGNS, or PLOT3D depending on your source grid type).
• MESH_OUT_FILENAME = converted_mesh.su2 (This defines the destination name of your translated grid).
• NDIM = 3 (Set this to 2 for two-dimensional grids, or 3 for three-dimensional grids).

If you are working with a two-dimensional grid, make sure that your source mesh is strictly aligned on the Z-axis plane (Z = 0) and that you have designated the active plane in your generator before exporting.

Step 3: Running the Converter via Command Line

Open your terminal or command prompt and navigate directly to the folder containing your configuration file and your source mesh file. To execute the conversion utility, call the mesh executable followed by your configuration file as the primary argument.

Enter the command: SU2_MSH mesh_conversion.cfg

Once executed, the terminal will print live telemetry of the conversion process. You will observe the utility initializing, reading the configuration file, parsing the source nodes, mapping the element connectivity arrays, and writing the final native SU2 format blocks.

Pro-Tip: If your system path is not configured, you may need to call the executable using its full directory path, such as /usr/local/bin/SU2_MSH mesh_conversion.cfg on Unix-based systems, or verify that the executable has execution permissions (chmod +x SU2_MSH) before running.

Step 4: Verifying Boundary Marker Mapping

Once the terminal prints a successful completion message, open your newly generated converted_mesh.su2 file using your plain-text editor. If the mesh file is exceptionally large, avoid opening the entire file in a standard editor; instead, read the first fifty lines and the last one hundred lines using command-line utilities.

Confirm that the header starts with the parameter NDIM= followed by the correct number of spatial dimensions. Scroll toward the bottom of the file to inspect the marker definitions. You should see entries starting with the keyword MARKER_TAG= followed by your physical boundary names, such as wing or symmetry, along with the exact count of boundary elements allocated to that tag.

If the boundary tags appear as numeric placeholders or are completely missing, your physical groups were not successfully packaged during the original mesh export. In this case, you must return to Step 1 and re-export the file.

Step 5: Visualizing and Quality-Checking the Output

The final validation step is loading the converted file into a visualization engine to inspect the mesh quality. Since many visualization tools do not natively read raw SU2 files, you can use the SU2_CFD solver to run a zero-iteration dummy test. This test will output standard visualization formats like VTU or PLT.

Set your configuration file run limit to zero iterations (EXT_ITER = 0) and run the solver using: SU2_CFD mesh_conversion.cfg

The solver will process the SU2 mesh, construct the internal dual-grid volume arrays, evaluate the element aspect ratios, and export a visualization file named flow.vtu. Open this file in Paraview or Tecplot to inspect the surface mesh for distorted elements, gaps, or overlapping boundary faces.

Grid Formats and Configuration Parameters Comparison

The su2msh utility is designed to handle multiple input structures. The following table provides the operational specifications, formatting requirements, and limitations for each supported input mesh format.

Common Conversion Failures and Grid Corrections

Scenario 1: Missing Boundary Markers

• Root Cause: The physical groups in the parent mesh generation tool were saved as geometric elements rather than mesh entities, or they were exported using unsupported modern formatting standards (such as Gmsh 4.0 format without backward compatibility settings).
• Actionable Fix: Re-open your source mesh in the generator. Explicitly define physical surfaces for boundaries and physical volumes for the computational domain. If you are using Gmsh, ensure you check the box to force Version 2.0 ASCII export, or append the legacy save flag in your script options.

Scenario 2: Negative Volume Elements or Negative Jacobians

• Root Cause: The node numbering order of the elements is inverted during translation. This typically happens when converting 2D planar meshes that do not conform to a strict counter-clockwise node sequencing rule.
• Actionable Fix: In your SU2 configuration file, locate the element processing parameters. Enable the automatic reorientation setting by setting the parameter REORIENT_ELEMENTS = YES. If this fails to resolve the issue, verify that your 2D grid lies entirely on the Z = 0 coordinate plane without any out-of-plane skewness.

Scenario 3: Missing CGNS Library Compilation Error

• Root Cause: The terminal outputs an error stating that CGNS format support is not compiled. This happens because the SU2 binaries were built without active links to the external CGNS developer libraries.
• Actionable Fix: Recompile your SU2 installation with CGNS support enabled. Alternatively, convert the .cgns file to an intermediary Fluent .msh or Gmsh format using external conversion scripts before running the su2msh tool.

Scenario 4: Command Line Execution Fails to Parse File Paths

• Root Cause: The pathing variables inside the .cfg file contain relative paths with spaces or special characters, or the executing terminal does not have read-write privileges for the output directory.
• Actionable Fix: Move all configuration files, input meshes, and utility executables into a single directory that does not contain spaces in its path name (e.g., C:/CFD_Simulations/ instead of C:/CFD Simulations/). Always run the command terminal as an administrator on Windows, or use sudo privileges on Linux systems when accessing restricted system directories.

Frequently Asked Questions

Can I convert high-order curved meshes using the SU2 mesh tool?

Yes, the SU2 mesh utility supports the conversion of quadratic and higher-order elements, particularly when importing from a Gmsh source file. When importing high-order grids, make sure that the configuration parameters are set to match the exact polynomial order of your source grid. This ensures that curved boundary faces are correctly parsed and that mid-side nodes are accurately mapped.

How do I handle internal boundaries, such as actuator disks or thin baffles, during conversion?

Internal boundaries must be defined as double-sided physical surfaces inside your mesh generator before running the conversion tool. When su2msh processes these boundaries, it will assign two distinct boundary marker tags to the same spatial coordinates. This setup allows the solver to apply internal conditions like pressure drops or fan curves across the interface.

Why does my converted SU2 mesh file have an extremely large file size compared to the source?

The SU2 native mesh format is a plain-text ASCII format. It contains explicit listings of all node coordinates, element connectivity, and boundary markers. This open structure is highly readable and easy to debug, but it requires significantly more storage space than highly compressed binary formats like CGNS. To save space, you can compress your final converted mesh using standard compression tools (such as gzip) to produce a .su2.gz file, which the SU2 solver can read directly.

Can I convert structured multi-block grids to the unstructured SU2 format?

Yes, the conversion utility can parse structured multi-block grids (such as Plot3D) and automatically decompose them into unstructured hexahedral, tetrahedral, or prismatic elements. The tool maps the block interfaces and outputs a single, cohesive unstructured grid file. This conversion retains your original grid refinement settings and boundary alignments.

Elevate Your Aerodynamic Simulations

Streamlining your grid generation workflow is the first step toward achieving fast, converged CFD solutions in aerospace and mechanical design. Explore our advanced engineering consultancy services or check out our premium simulation training programs to master complex aerodynamic workflows today.