Mastering The Su2msh Utility: Convert And Optimize Mesh Files For SU2 CFD Simulations

To convert external grids to the native format required by the SU2 open-source CFD solver, computational engineers rely on the su2msh workflow embedded within the SU2_MSH executable. This process reads structured or unstructured mesh configurations from standard formats like Gmsh or CGNS and outputs an optimized spatial matrix with verified boundary markers. Standardizing this translation sequence ensures perfect alignment of node coordinates, prevents element inversion, and guarantees numerical stability during high-fidelity aerodynamic simulations.

Pre-Conversion Setup and Mesh Validation Requirements

CFD solvers demand rigorous control over mesh topology to avoid divergence during the initialization phase of Navier-Stokes or Euler calculations. Before initiating the mesh conversion process with the SU2 mesh utility, you must verify that your source grid conforms to clean geometric constraints and that your local environment contains the compiled SU2 binaries.

Essential Gear, Software, and System Requirements:

• SU2 Suite Installation: A compiled distribution of SU2 containing the SU2_MSH executable. Ensure the binary path is added to your system environment variables so it can be called from any working directory.
• Source Mesh File: A fully generated grid exported from software such as Gmsh, Pointwise, or ANSYS ICEM. Supported formats include CGNS, Gmsh (.msh), or Plot3D (.xyz).
• Text Editor: A raw text editor capable of modifying SU2 configuration (.cfg) files without adding hidden formatting characters or encoding wrappers.
• Visualization Tool: ParaView or Tecplot for post-conversion quality assurance and boundary visualization.

Mandatory Prerequisite Knowledge and Standards:

• Dimension Consistency: The source mesh must strictly match the dimensional space of your target simulation (either 2D or 3D). Mixing 2D planar meshes with 3D boundaries without explicit projection will cause solver failure.
• Boundary Condition Mapping: Every physical surface where boundary conditions apply (e.g., inlet, outlet, farfield, viscous wall) must have a unique identifier group assigned prior to conversion.
• Coordinate System: SU2 operates on a standard Cartesian coordinate system. Ensure your mesh generation tool does not export in cylindrical or spherical coordinates unless explicitly configured.

Estimated Process Benchmarks:

• Setup and configuration file generation: 5 to 10 minutes.
• Execution of the conversion binary: Under 10 seconds for small grids (under 1 million elements); up to 5 minutes for large-scale external aerodynamic meshes (over 50 million elements).
• Verification and boundary audit: 10 minutes.

Executing the su2msh Conversion Workflow

Converting external grids into native SU2 format requires a methodical approach that links geometric boundaries with physical boundary conditions. Follow these five procedural steps to complete the mesh conversion.

Step 1: Exporting the Grid from Your Generator

To begin, you must export your computational mesh from your grid generation utility in a format compatible with SU2. If you are utilizing Gmsh, export the grid as a mesh file. You must select Gmsh Version 2 ASCII format or Version 4 ASCII format depending on your specific SU2 build compatibility, although Version 2 remains the most universally compatible legacy standard. If using Pointwise or ICEM, export the grid as an unstructured CGNS file. Ensure that all cell zones and boundary patches are grouped and named logically during this export phase.

Step 2: Defining Physical Groups and Boundary Markers

The SU2 solver relies on named markers to apply specific thermodynamic and aerodynamic boundary conditions. In your mesh generation tool, you must explicitly declare physical groups. For example, assign your airfoil surface to a physical group named airfoil, your inlet boundaries to inlet, and your outlets to outlet. The su2msh utility will parse these physical group names and map them directly into the marker section of the final SU2 file.

Warning: Failure to define physical groups before export will result in a native mesh file containing a single default boundary marker or, in worse cases, no boundary markers at all, rendering the mesh useless for applying distinct boundary conditions.

Step 3: Configuring the SU2 Translation Settings

Rather than running as a blind converter, the mesh utility reads specific configuration directives. Open your simulation's master configuration file, typically named config_CFD.cfg, and locate the input/output file section. You must specify the source format using the key-value pair MESH_FORMAT equal to GMSH, CGNS, or PLOT3D. Next, define the input file name using MESH_FILENAME followed by the path to your exported grid file. Finally, define the destination output file using MESH_OUT_FILENAME followed by your desired filename ending with the .su2 extension.

Pro-Tip: Ensure the dimensional setting NDIM in your configuration file matches the spatial dimensions of your grid. Setting NDIM to 2 for a 3D mesh will truncate coordinate arrays and corrupt your node topology.

Step 4: Running the Conversion Binary

With your configuration file saved and your source mesh in the working directory, open your command terminal. Navigate to the folder containing your files and invoke the SU2 mesh converter. Type the command SU2_MSH followed by the name of your configuration file, such as SU2_MSH config_CFD.cfg, and press enter. The system will initialize the reader, load the elements into memory, parse the connectivity arrays, map the physical boundaries to SU2 markers, and write the output file to disk. Keep a close eye on the terminal output to monitor progress.

Step 5: Auditing the Output .su2 Mesh

Once the terminal indicates that the conversion has successfully finished, open the newly generated .su2 file in a standard text editor to verify its structural integrity. The top lines of a native SU2 mesh file must state the dimension (NDIM= value) followed by the number of elements (NELEM= value). Scroll down to verify that the MARKER_TAG variables correspond exactly to the physical groups you defined in your mesh generator. Additionally, load the .su2 file into a post-processor or run a quick grid check using SU2_CFD in grid-test mode to confirm there are no hanging nodes or negative volumes.

Mesh Format Compatibility and Dimension Thresholds

The su2msh utility supports several input formats, each possessing unique element mapping capabilities and coordinate translation properties. The following table provides the performance profiles and compatibility thresholds for each primary input file type supported by the conversion tool.

Resolving Conversion Failures and Boundary Mappings

When working with complex geometries or multi-block topologies, the mesh translation process can encounter fatal errors. Below are common real-world failure scenarios and their technical resolutions.

Scenario 1: Unidentified Boundary Markers or Missing Physical Groups

• Root Cause: The mesh generator exported the elements successfully but did not save the boundary patch grouping names in a metadata format that the SU2 parser can recognize. This often happens in Gmsh when exporting without defining physical entities, or in CGNS when boundary conditions are not formally assigned within the zone tree.
• Actionable Fix: Reopen the mesh in your grid generator. In Gmsh, go to the geometry or mesh module, select Physical Groups, and explicitly add physical curves for 2D boundaries or physical surfaces for 3D boundaries. Ensure these groups encompass all boundary elements. Re-export the mesh and re-run the SU2_MSH command.

Scenario 2: Inverted Elements or Negative Volume Errors

• Root Cause: Node ordering conventions differ between mesh generators and the native SU2 format. When converting left-handed coordinate systems or specific prism topologies, the Jacobian matrix calculation yields negative volumes, leading to solver divergence during simulation initialization.
• Actionable Fix: Open your configuration file and enable the automatic correction option by setting the parameter reorient_elements or utilizing the coordinate correction flags. Alternatively, if using Gmsh, use the mesh optimization tools to optimize 3D volume elements and correct element orientation before exporting the source grid.

Scenario 3: Mismatch in Coordinate Dimensionality

• Root Cause: The input mesh file contains 3D coordinates (with z-coordinates set to zero) but the simulation configuration file is set to run a 2D case (NDIM=2). The SU2_MSH utility will detect a mismatch between the flat 3D coordinate space and the expected 2D planar structure.
• Actionable Fix: Check the source mesh export settings and ensure it is strictly written as a 2D grid. If the mesh generator automatically outputs three coordinates, modify your config file to NDIM=3 temporarily to convert the mesh, and then use the SU2 command-line tools to slice or project the mesh back to a true 2D plane with zero z-planes.

Scenario 4: Command Terminated by Segmentation Fault

• Root Cause: This occurs when converting massive meshes that exceed system memory limits, or when trying to read binary CGNS files compiled with a different HDF5 library version than the one linked to your SU2 installation.
• Actionable Fix: If dealing with library version mismatches, export your mesh in an ASCII format instead of binary, or recompile SU2 with the matching HDF5 and CGNS library paths. For memory-related crashes, ensure you have allocated sufficient swap space or perform the conversion on a high-performance computing node with larger RAM allocation.

Frequently Asked Questions

Can su2msh handle polyhedral meshes?

The native SU2 mesh format supports standard unstructured element types including triangles, quadrilaterals, tetrahedra, hexahedra, prisms, and pyramids. It does not natively support arbitrary polyhedral elements with variable face counts per cell. If you have a polyhedral mesh, you must decompose it into standard dual-mesh elements before initiating conversion.

How do I define periodic boundaries using the mesh converter?

To establish periodic boundaries, you must define the sending and receiving boundary surfaces as distinct physical groups in your source grid generator. Once converted to the .su2 format, navigate to the periodic marker definition section of your SU2 configuration file, where you will map these two markers to each other along with their corresponding translation or rotation vectors.

Why does my converted mesh show zero boundary elements in the solver?

This issue occurs when boundary faces are not explicitly defined in the mesh file as lower-dimensional elements. For example, in a 3D mesh, the boundary faces must be explicitly saved as 2D triangles or quadrilaterals associated with a boundary group, rather than just being faces of the 3D volume elements. Ensure your mesh generator exports boundary face elements alongside the volume elements.

Can I use su2msh to convert OpenFOAM meshes?

You cannot convert OpenFOAM meshes directly with the legacy su2msh tool as it does not read the native polyMesh folder structure. To convert an OpenFOAM mesh, you must first use an intermediate utility such as foamToCgns or export the mesh from your primary meshing tool to a neutral format like CGNS before running the SU2_MSH converter.

Is it possible to convert meshes without a configuration file?

No, the SU2_MSH executable requires a configuration file to resolve input formats, output destinations, and dimensions. However, you do not need a complete simulation setup; a minimal configuration file containing only the input/output mesh parameters, format types, and spatial dimension settings is sufficient to complete the conversion process.

Optimize Your Aerodynamic Design Pipeline

Streamline your computational fluid dynamics workflow by integrating high-fidelity mesh conversions directly into your automated simulation scripts. Leverage the robust conversion capabilities of SU2 to ensure seamless transition from CAD design to solver convergence.