SnappyHexMesh

From OpenFOAMWiki


1 Introduction

In a nutshell, snappyHexMesh is a mesh generator that takes an already existing mesh (usually created with blockMesh) and chisels it into the mesh you want. But for this, it requires:

  • A very well defined dictionary, namely system/snappyHexMeshDict.
  • Good geometrical definitions, such as:
    • STL/OBJ files with well defined surfaces;
    • eMesh feature edge files, that define feature edges that have describe sharp corners.


Valid versions: OF version 15.png OF version 16.png OF version 17.png OF Version 20.png OF Version 21.png OF Version 22.png OF Version 23.png OF Version 15dev.png OF Version 16ext.png OF Version 30ext.png OF Version 31ext.png

Note: feature edges only available in: OF Version 20.png OF Version 21.png OF Version 22.png OF Version 23.png


Configuring both the dictionary file and providing good geometries can be a very arduous task. Therefore, at the moment of this writing (11:06, 18 August 2012 (CEST)), this wiki page will try to point you in the right direction, without describing each and every detail related to using snappyHexMesh. Feel free to contribute to this page!


1.1 Synopsis

snappyHexMesh [OPTIONS]

1.2 Description

snappyHexMesh is more of a mesh sculptor than a mesh generator, because it requires an already existing base mesh to work with. Depending on the options given through the file "system/snappyHexMeshDict", it can:

  • refine the mesh;
  • adjust the mesh to fit onto provided geometries;
  • and add boundary layers near the requested patches.

The following options can be used with snappyHexMesh:

-case DIR

Execute the command on the case directory DIR. If not provided, use the current directory

-dict FILE

Read dictionary from specified location.

-checkGeometry

OF Version 22.png OF Version 23.png Check all surface geometry for quality

-noFunctionObjects

Skip the execution of the functionObjects

-overwrite

Overwrite existing mesh/results files

-parallel

Run the utility in parallel

-roots "(DIR1 [...DIRN])"

Directories through which the data are distributed

-help

Display the help and exit

1.3 Examples

Several examples can be found in OpenFOAM, simply by running the following commands: 

find $FOAM_UTILITIES -name "snappyHexMeshDict"
find $FOAM_TUTORIALS -name "snappyHexMeshDict"

2 Tutorials and Guides

Here are listed links to tutorials and guides on using snappyHexMesh:

  • Training sessions given at the OFW community workshops, by people working at Engys:
  • Dedicated wiki to snappyHexMesh by Elia Agnani: snappyWiki
  • NTNU HPC Group wiki includes an interesting practical tutorial on how to use snappyHexMesh with great success: OpenFOAM - Spillway Tutorial
  • Several realistic tutorials by Tobias Holzmann that use snappyHexMesh are available for free and more advanced ones for a fee to help support its updating and development: Advanced Tutorials


3 Tips

On this chapter are listed links and direct tips on using snappyHexMesh.


3.1 Can't find the resulting mesh

Creating a mesh with snappyHexMesh requires the following crucial steps:

  1. To already have a mesh ready, even if it's a simple brick-like mesh. For example, a simple mesh generated with blockMesh that has the dimensions of 10x4x2 meters and is divided in cells of 1 meter.
  2. The dictionary file snappyHexMeshDict should be properly configured. Look into the examples and tutorials for more information.
  3. snappyHexMesh must be executed with success.

If after these steps you can only find the original base mesh that was generated with blockMesh, then there are a few possibilities:

  • snappyHexMesh might not have ran with success.
  • If the option -overwrite was not used, then the resulting meshes should be in the next time folders, possibly inside the folders "1", "2" and/or "3".
  • If the location in mesh given is on the outside of the geometry, then in ParaView you should either use the filter Clip or Extract Cells by Region, for inspecting how the mesh looks inside.


3.2 Generate 2D meshes

Instructions/examples on how to generate 2D meshes using snappyHexMesh can be found in at least two places:

Other tutorials:

  • This is an awesome tutorial: Dynamic Mesh for a Gear Pump.
  • See in the previous section Tutorials and Guide from Tobias Holzmann. There you will find 2D cases, too.

3.3 Multi-region meshes

There are a few instructions/examples on how to generate multi-region meshes with snappyHexMesh:

3.4 Running in parallel

Currently there are several official tutorials on how to use snappyHexMesh in parallel:

  • incompressible/windSimpleFoam/turbineSiting - Valid versions: OF Version 20.png
  • incompressible/simpleFoam/turbineSiting - Valid versions: OF Version 21.png OF Version 22.png OF Version 23.png OF Version 24.png OF Version 30.png OF Version 4.png OF Version 5.png
  • incompressible/pisoFoam/les/motorBike/motorBike - Valid versions: OF Version 21.png OF Version 22.png OF Version 23.png OF Version 24.png OF Version 30.png OF Version 4.png OF Version 5.png

Other tutorials:

3.5 GUI (Graphical User Interfaces)

Currently there are several interactive ways (using GUI) of generating meshes with snappyHexMesh. Here will only be listed the ones that are open-source:

CfdOF
A comprehensive OF GUI for FreeCAD.
Contrib/SnappyHexMesh_GUI_Addon_for_Blender
Discretizer 
Check the Screencasts page for more information.
SwiftSnap 
(outdated) A very useful plug-in for Blender for configuring snappyHexMeshDict. There is SwiftBlock for blockMeshDict as well!
HelyxOS 
A GUI for using OpenFOAM. See the video tutorials:
Rheologic STL export addon 
A very handy blender addon that exports all objects in a blender scene as individual STL files using the object name as filename. Saves lots of time when frequent exporting of changes in geometry is needed. It's already part of Blender in the more recent versions, but if it's not available in your older version of Blender, you can grab it here: Rheologic Blender Addon: export multiple objects as separate STLs
pyVTK script GUI for getting a sense for feature angles 
There is a script which uses pyVTK to give a GUI for seeing feature edges, which is made available on this thread: GUI for surfaceFeatureExtract

3.6 Another way of projection of a mesh on an STL surface

Adding boundary layers with snappyHexMesh can sometimes be very stressing, specially when it sometimes stops the layers in the wrong places. Trying to improve this feature was one of several works made in the MSc/PhD course in CFD with OpenSource software, 2011 at Chalmers, namely:

Other important links:

  • Thread dedicated to discussing on this subject: [4]
  • Adjusted code for working with the latest OpenFOAM versions: [5]


3.7 Isolate and Conquer

Since snappyHexMesh has so many mesh quality parameters, these sometimes to get in the way of the meshes you're trying to generate. The solution apparently is simple:

  1. Disable all quality controls.
  2. Diagnose visually the resulting mesh.
  3. Gradually turn back on one quality indicator at a time, while checking the resulting mesh with both checkMesh and ParaView.

For more on this, read the following posts/threads:


3.8 Valid and invalid solid names

There are 2 details to always keep in mind when exporting to STL:

  • Always export to STL in ASCII or "coded" format (this means it'll be plain text).
  • Edit the resulting file with a text editor and look for the lines that start with "solid". Next to the word "solid" is the name of said solid; that name should be a single C/C++ word.

Examples of valid words/names:

  • wall
  • ladder
  • part_001_73_

Invalid names:

  • This was generated by productnamehere
  • part 001-73:
  • 70 inch wall


3.9 Handling inclined surfaces

Q: Do you have a geometry that has an inclined surface and gets a very bad mesh, due to the cells not adjusting properly to the geometry, namely the inclined surfaces?

A: Check the following thread at CFD-Online: How to get a snapped mesh with SnappyHexMesh? post #4 and #5


3.10 Fixing STL files

If you need to fill or fix small gaps, here is a list of possible applications that can help:


Short list of topic related threads at CFD-Online's forums:


3.11 Visual mesh diagnosis in ParaView

This is already explained in this FAQ: FAQ/Postprocessing - Visual mesh diagnosis in ParaView

4 Deep analysis of each parameter

This chapter is dedicated to analysing in detail how each parameter affects the resulting mesh. Please feel free to document each parameter.

4.1 castellatedMeshControls

4.1.1 refinementRegions

4.1.1.1 Using non-closed surfaces

Valid versions: OF Version 22.png OF Version 23.png OF Version 24.png

For more details, see this thread: Patch volume refinement in sHMD - solution in post #6.

4.1.2 nCellsBetweenLevels

Valid versions: OF Version 22.png OF Version 23.png OF Version 24.png

Notes
  • Older versions of OpenFOAM also have this parameter, but some versions might be have a bug related to this parameter and might not act in the same way. Please feel free to check with which older versions this parameter act differently and please document your findings on this subsection.
  • This parameter doesn't always work in the exact same way as reported here when the geometries are too complex, because the algorithm used by snappyHexMesh gets confused when there are too many corners, e.g. a geometry with shaped like a W over XY and like a T over XZ.
Valid values
nCellsBetweenLevels must be equal or greater than 1, integer values only.
Studying nCellsBetweenLevels
Using the cube case from the (unofficial) snappywiki, it's possible to easily study how this parameter affects the resulting mesh. In addition, keep in mind to follow the instructions given at FAQ/Postprocessing#Visual mesh diagnosis in ParaView. An additional test case is available at the discussion thread SnappyHexMesh Refinement nCellsBetweenLevels - post #14.

In review of how level refinement works, it's simple: for each level value, it divides a cell in the base mesh the number of times that "2 to the power of the level" equates to, in each direction. For example:

  1. Level 0: the original cell stays the same.
  2. Level 1: the original cell is divided into 8 parts, namely twice in each direction.
  3. Level 2: each level 1 cell is divided further into 8 parts, which means that the big cell has been divided into 64 cells in total.
  4. Level 3: each level 2 cell is divided further into 8 parts, which means that the big cell has been divided into 512 cells in total.

As for what a layer stands for: it's all of the cells that are at the same distance from a particular patch or wall.

Here is how the parameter affects the resulting mesh, where on the left is the image that demonstrates the mesh and on the right is the explanation:

Zoom in inside the base mesh, focused at the same point where the next pictures are looking at.
 Take into account that the mesh is set to use refinement of level 2 near the cube's wall. This means that the cells near those walls will have to be split in half twice in each direction.
Using nCellsBetweenLevels set to 1.
 When nCellsBetweenLevels is set to 1, it means that it will use at least 1 layer of cells at a particular refinement level in between changes of resolution. Furthermore:
  1. Given that near the wall each cell was split into 4 cells in each direction, this means that there is a cumulative effect working near the wall, since it would not be possible to un-refine the 2nd cell layer from the wall.
  2. Nonetheless, it's able to only have 1 layer of cells at level 1. This is because they were already cut with the right size.
  3. The cells at the centre are all of level 0, i.e. it's the base mesh untouched.
Using nCellsBetweenLevels set to 2.
 As demonstrated in the previous value, in this case it tries to have at least 2 cells before going to the next level of resolution.
Using nCellsBetweenLevels set to 3.
 This one may look a bit weird, but it's because snappyHexMesh is trying to be conservative. Why should it be necessary to have to split a third layer of cells at level 1; it's an error of 1 missing layer at level 1, but it's preferable than having an excessive number of cells.
Using nCellsBetweenLevels set to 4.
 Everything is fine on this one. It's doing at least 4 layers of cells on each level.
Using nCellsBetweenLevels set to 5.
 Here's another situation where it's able to perform somewhat well: it has 6 layers of cells at level 2 and 5 layers of cells at level 1.

Keep in mind that if you set nCellsBetweenLevels set to a much larger value, e.g. 50, it would mean that the whole cube would be at the level 2 of refinement, because the requested number of layer cells was at least 50.

And what about when it doesn't look like it's respecting at all the value you've defined?
  1. Well, keep in mind the layer indicated earlier in this subsection: what matters is that the cells are all at the same distance from a particular wall... and if the algorithm has got a hard time figuring out to which wall it was meant to be measuring the distance, then it makes it a lot harder to figure out where the layers should change resolution.
  2. The other possibility is that the algorithm is trying to be conservative and/or is respecting the parameter minRefinementCells.
  3. Or perhaps the parameters maxLocalCells and/or maxGlobalCells are the constraint that limits the how many refinement layers can in fact be used, without going over the requested limit.
Thread where this can be discussed?
Please ask questions about this parameter on this thread: SnappyHexMesh Refinement nCellsBetweenLevels
Retrieved from "https://openfoamwiki.net/index.php?title=SnappyHexMesh&oldid=20639"
  • GNU Free Documentation License 1.3
  • Powered by MediaWiki
  • Powered by Semantic MediaWiki