snappyHexMesh Tutorial

Update 26.12.2012:
Download the geometry file wigley hull (33)

Update 08.07.2010:
Have a look to the second part of the snappyHexMesh tutorial!

In order to use the automatic meshing tool snappyHexMesh, you have to create a raw background mesh. This can easily be achieved by using blockMesh of OpenFOAM. For this tutorial, I assume that you wish to compute the flow around a body, such as a ship’s hull. The user’s guide can be found here.

1. Create (or copy) the blockMeshDict in $CASE_DIR/constant/polyMesh. It is not necessary to create a fine background mesh, since it will be refined by snappyHexMesh.
2. 

   Basic case directory setup

   For the execution of blockMesh, the case folder has to be set up correctly. This can either be seen in the User Guide or in lots of tutorials, such as icoFoam/cavity. For the icoFoam solver, an example case-directory can be seen in the screenshot. Goto your case-directory and execute

   blockMesh

   This creates the background mesh. One has to mention, that is is necessary to dimension it sufficiently, in order to fit the hull into that mesh and suppress numerical errors, caused by a way to small mesh.

3. Assuming, that you’ve already exported your geometry as an STL-file, you’ve to copy that file to $CASE_DIR/constant/triSurface. For the following tutorial, I assume, that the filename is hull.stl.
   

   Mesh created by blockMesh

4. Create (or copy from a snappyHexMesh tutorial) the snappyHexMeshDict in $CASE_DIR/systemand insert the standard header into that file:

   FoamFile { version 2.0; format ascii; root ""; case ""; instance ""; local ""; class dictionary; object autoHexMeshDict; }

5. Now we can start with creating the necessary dictionaries. First of all, tell snappyHexMesh, what to do (in a global sense)

   castellatedMesh true; snap true; addLayers true;

6. Secondly, snappyHexMeshneeds to know which geometry to use. You can simply add just one STL-file, or add add searchableBoxes etc. to this dictionary, if you either wish to create a geometry without an STL-file or you like to specify a region in your mesh, that should be refined specifically. Trying to map the wake field requires a specific refinement region.

   geometry { hull.stl { type triSurfaceMesh; name HULL; } };

7. Now we have to configure the settings for the mesh, generated by snappyHexMesh. This is done in the castellatedMeshControls sub-dictionary. Valid settings and options can be seen in the user-guide (table 5.8) or in the snappyHexMeshtutorials. An example for that sub-dictionary is the following

   castellatedMeshControls { maxLocalCells 10000000; maxGlobalCells 2000000; minRefinementCells 0; nCellsBetweenLevels 1; refinementSurfaces { HULL { level (4 5); } } resolveFeatureAngle 30; refinementRegions { HULL { mode distance; levels ((0.1 5) (0.4 4) (1 2)); } } locationInMesh (3.11 1.51 -1.1); }

   

   Visualized levels of region refinement

   The most important part for a working mesh refinement are locationInMesh, which specifies a point inside the mesh generated by blockMesh, but not inside the geometry (in this case the hull). Secondly, the refinementSurfaces tells snappyHexMesh, which surfaces are the ones to be refined. The level tag defines minimum and maximum refinement level. The refinementRegions tag sets the levels of refinement in various distances to the body, this can be seen in the figure.
   It doesn’t matter, how much refinementRegions are defined, but the scheme is always the same.

   levels((maxDistance refinementLevel)...)

8. After the specification of the general meshing and refinement parameters, it is essential to set up controls for the snapping process itself. (cp. [1] table 5.9)

   snapControls { nSmoothPatch 3; tolerance 4.0; nSolveIter 30; nRelaxIter 5; }

9. 

   Patch name in an ASCII STL file

   The layer addition is controlled by the addLayersControls dictionary, whose options can be seen in table 5.10 of the user guide (cp. [1]). These options are skipped for this tutorial, and sample values can be found in the user guide as well. Nevertheless, the layers sub-directory is important to talk about. As stated in [1], it tells snappyHexMesh which patches “need” layers attached and the number of those layers. Since this is an mesh oriented option, not the surface geometry has to be specified, but the patch name. If you have an ASCII STL file, you can open simply open it with an texteditor of your choice and the word after solid is the patch name. In my case, this was OBJECT.

   addLayersControls { layers { HULL_OBJECT { nSurfaceLayers 1; } } }

10. Finally, controlling the mesh’s quality is a crucial part of the whole meshing process. Thus snappyHexMesh provides a dictionary to control the quality, which is namely the meshQualityControlssub-dictionary. All options related to this can be found in table 5.11 in the user guide [1].

    meshQualityControls{ //Insert your options here }

11. 

    Model's position compared to the background mesh

    It is essential to get your model into the right position within your background mesh, created with blockMesh. You can easily check this by comparing both, the mesh and the model, with paraFoam or paraview. If you are on a linux machine, simply type

    paraFoam & // & to run paraFoam in background

    If you calculate on a linux machine and do the postprocessing on e.g. a mac, you have to convert your mesh by

    foamToVTK

    and then open paraview and your VTK file manually. After that, load your STL model into paraview/paraFoam as well. To simplify the orientation within the mesh, you should enable the option show cube axes for the mesh. If you have a symmetry plane, it is beneficial to highlight this as well. After that, the picture you get should be in a way similar to mine.

12. Move the mesh until the model is inside and in its desired position. The coordinates are obtained from paraFoam/paraview and the axes shown in there. Moving the mesh is kind of easy

    transformPoints -translate "(x y z)"

    One has to state that the coordinates have to be specified in dashes as shown, otherwise the bash will skrew up on that command.

13. Look again at the model’s position in the mesh. If it is not correct, move it again.
14. Now it’s time to execute snappyHexMeshby moving to your case directory and execute

    snappyHexMesh

15. After having run the meshing without any errors, three new timestep folders appear in your case directory. The naming differs, depending on your deltaT in your system/controlDict, but always reflects the first three timesteps. Opening the case using paraFoam gives a good nice understanding, how snappyHexMeshworks. The first timestep (folder 0) shows the background mesh, without any refinements. Timestep 1 shows the refined mesh as well as no faces, that are “snapped” to the geometry. The final result is provided by timestep 2.
    

    timestep 0: simply the background mesh

    timestep 1: Refined mesh, but no snapped faces

    timestep 2: final result with snapped faces

16. If running the solver, the improved mesh will not be used, because the old mesh is still written in constant/polyMesh. Hence the folder “lastTimeStep”/polyMesh has to be copied to constant/polyMesh.
17. Run your solver

[1] OpenFOAM – The Open Source CFD Toolbox – User Guide, Version 1.5

Tags: CFD, OpenFOAM, snappyHexMesh