added comment

tutorials/mesh/snappyHexMesh/iglooWithFridges/system/snappyHexMeshDict

@@ -15,12 +15,18 @@ FoamFile
 }
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
+// Which of the steps to run
 castellatedMesh true;
-
 snap            true;
-
 addLayers       true;
 
+
+// Geometry. Definition of all surfaces. All surfaces are of class
+// searchableSurface.
+// Surfaces are used
+// - to specify refinement for any mesh cell intersecting it
+// - to specify refinement for any mesh cell inside/outside/near
+// - to 'snap' the mesh boundary to the surface
 geometry
 {
     fridgeA
@@ -45,17 +51,68 @@ geometry
     }
 }
 
+
+
+// Settings for the castellatedMesh generation.
 castellatedMeshControls
 {
+
+    // Refinement parameters
+    // ~~~~~~~~~~~~~~~~~~~~~
+
+    // While refining maximum number of cells per processor. This is basically
+    // the number of cells that fit on a processor. If you choose this too small
+    // it will do just more refinement iterations to obtain a similar mesh.
     maxLocalCells   1000000;
+
+    // Overall cell limit (approximately). Refinement will stop immediately
+    // upon reaching this number so a refinement level might not complete.
+    // Note that this is the number of cells before removing the part which
+    // is not 'visible' from the keepPoint. The final number of cells might
+    // actually be a lot less.
     maxGlobalCells  2000000;
+
+    // The surface refinement loop might spend lots of iterations refining just a
+    // few cells. This setting will cause refinement to stop if <= minimumRefine
+    // are selected for refinement. Note: it will at least do one iteration
+    // (unless the number of cells to refine is 0)
     minRefinementCells 0;
+
+    // Number of buffer layers between different levels.
+    // 1 means normal 2:1 refinement restriction, larger means slower
+    // refinement.
     nCellsBetweenLevels 1;
-    features        ( );
+
+
+
+    // Explicit feature edge refinement
+    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    // Specifies a level for any cell intersected by its edges.
+    // This is a featureEdgeMesh, read from constant/triSurface for now.
+    features
+    (
+        //{
+        //    file "someLine.eMesh";
+        //    level 2;
+        //}
+    );
+
+
+
+    // Surface based refinement
+    // ~~~~~~~~~~~~~~~~~~~~~~~~
+
+    // Specifies two levels for every surface. The first is the minimum level,
+    // every cell intersecting a surface gets refined up to the minimum level.
+    // The second level is the maximum level. Cells that 'see' multiple
+    // intersections where the intersections make an
+    // angle > resolveFeatureAngle get refined up to the maximum level.
     refinementSurfaces
     {
         fridgeA
         {
+            // Surface-wise min and max refinement level
             level           ( 2 2 );
         }
 
@@ -71,23 +128,64 @@ castellatedMeshControls
     }
 
     resolveFeatureAngle 60;
+
+    // Region-wise refinement
+    // ~~~~~~~~~~~~~~~~~~~~~~
+
+    // Specifies refinement level for cells in relation to a surface. One of
+    // three modes
+    // - distance. 'levels' specifies per distance to the surface the
+    //   wanted refinement level. The distances need to be specified in
+    //   descending order.
+    // - inside. 'levels' is only one entry and only the level is used. All
+    //   cells inside the surface get refined up to the level. The surface
+    //   needs to be closed for this to be possible.
+    // - outside. Same but cells outside.
+
     refinementRegions
     {
     }
 
+
+    // Mesh selection
+    // ~~~~~~~~~~~~~~
+
+    // After refinement patches get added for all refinementSurfaces and
+    // all cells intersecting the surfaces get put into these patches. The
+    // section reachable from the locationInMesh is kept.
+    // NOTE: This point should never be on a face, always inside a cell, even
+    // after refinement.
     locationInMesh  ( 3 0.28 0.43 );
 }
 
+
+
+// Settings for the snapping.
 snapControls
 {
+    //- Number of patch smoothing iterations before finding correspondence
+    //  to surface
     nSmoothPatch    3;
+
+    //- Relative distance for points to be attracted by surface feature point
+    //  or edge. True distance is this factor times local
+    //  maximum edge length.
     tolerance       4;
+
+    //- Number of mesh displacement relaxation iterations.
     nSolveIter      30;
+
+    //- Maximum number of snapping relaxation iterations. Should stop
+    //  before upon reaching a correct mesh.
     nRelaxIter      5;
 }
 
+
+
+// Settings for the layer addition.
 addLayersControls
 {
+    // Per final patch (so not geometry!) the layer information
     layers
     {
         fridgeA_region0
@@ -106,41 +204,129 @@ addLayersControls
         }
     }
 
+
+    // Expansion factor for layer mesh
     expansionRatio  1;
+
+    //- Wanted thickness of final added cell layer. If multiple layers
+    //  is the
+    //  thickness of the layer furthest away from the wall.
+    //  Relative to undistorted size of cell outside layer.
     finalLayerRatio 0.5;
+
+    //- Minimum thickness of cell layer. If for any reason layer
+    //  cannot be above minThickness do not add layer.
+    //  Relative to undistorted size of cell outside layer.
     minThickness    0.25;
+
+    //- If points get not extruded do nGrow layers of connected faces that are
+    //  also not grown. This helps convergence of the layer addition process
+    //  close to features.
     nGrow           0;
+
+
+    // Advanced settings
+
+    //- When not to extrude surface. 0 is flat surface, 90 is when two faces
+    //  make straight angle.
     featureAngle    60;
+
+    //- Maximum number of snapping relaxation iterations. Should stop
+    //  before upon reaching a correct mesh.
     nRelaxIter      5;
+
+    // Number of smoothing iterations of surface normals
     nSmoothSurfaceNormals 1;
+
+    // Number of smoothing iterations of interior mesh movement direction
     nSmoothNormals  3;
+
+    // Smooth layer thickness over surface patches
     nSmoothThickness 10;
+
+    // Stop layer growth on highly warped cells
     maxFaceThicknessRatio 0.5;
+
+    // Reduce layer growth where ratio thickness to medial
+    // distance is large
     maxThicknessToMedialRatio 0.3;
+
+    // Angle used to pick up medial axis points
     minMedianAxisAngle 130;
+
+    // Create buffer region for new layer terminations
     nBufferCellsNoExtrude 0;
 }
 
+
+
+// Generic mesh quality settings. At any undoable phase these determine
+// where to undo.
 meshQualityControls
 {
+    //- Maximum non-orthogonality allowed. Set to 180 to disable.
     maxNonOrtho     65;
+
+    //- Max skewness allowed. Set to <0 to disable.
     maxBoundarySkewness 20;
     maxInternalSkewness 4;
+
+    //- Max concaveness allowed. Is angle (in degrees) below which concavity
+    //  is allowed. 0 is straight face, <0 would be convex face.
+    //  Set to 180 to disable.
     maxConcave      80;
+
+    //- Minimum projected area v.s. actual area. Set to -1 to disable.
     minFlatness     0.5;
+
+    //- Minimum pyramid volume. Is absolute volume of cell pyramid.
+    //  Set to a sensible fraction of the smallest cell volume expected.
+    //  Set to very negative number (e.g. -1E30) to disable.
     minVol          1e-13;
+
+    //- Minimum face area. Set to <0 to disable.
     minArea         -1;
+
+    //- Minimum face twist. Set to <-1 to disable. dot product of face normal
+    //- and face centre triangles normal
     minTwist        0.05;
+
+    //- minimum normalised cell determinant
+    //- 1 = hex, <= 0 = folded or flattened illegal cell
     minDeterminant  0.001;
+
+    //- minFaceWeight (0 -> 0.5)
     minFaceWeight   0.05;
+
+    //- minVolRatio (0 -> 1)
     minVolRatio     0.01;
+
+    //must be >0 for Fluent compatibility
     minTriangleTwist -1;
+
+
+    // Advanced
+
+    //- Number of error distribution iterations
     nSmoothScale    4;
+    //- amount to scale back displacement at error points
     errorReduction  0.75;
 }
 
+
+
+// Advanced
+
+// Flags for optional output
+// 0 : only write final meshes
+// 1 : write intermediate meshes
+// 2 : write volScalarField with cellLevel for postprocessing
+// 4 : write current intersections as .obj files
 debug           0;
 
+
+// Merge tolerance. Is fraction of overall bounding box of initial mesh.
+// Note: the write tolerance needs to be higher than this.
 mergeTolerance  1e-06;
 
 

tutorials/mesh/snappyHexMesh/motorBike/system/snappyHexMeshDict

@@ -13,14 +13,21 @@ FoamFile
     location    "system";
     object      snappyHexMeshDict;
 }
+
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
+// Which of the steps to run
 castellatedMesh true;
-
 snap            true;
-
 addLayers       true;
 
+
+// Geometry. Definition of all surfaces. All surfaces are of class
+// searchableSurface.
+// Surfaces are used
+// - to specify refinement for any mesh cell intersecting it
+// - to specify refinement for any mesh cell inside/outside/near
+// - to 'snap' the mesh boundary to the surface
 geometry
 {
     motorBike.stl
@@ -37,22 +44,89 @@ geometry
     }
 }
 
+
+// Settings for the castellatedMesh generation.
 castellatedMeshControls
 {
+
+    // Refinement parameters
+    // ~~~~~~~~~~~~~~~~~~~~~
+
+    // While refining maximum number of cells per processor. This is basically
+    // the number of cells that fit on a processor. If you choose this too small
+    // it will do just more refinement iterations to obtain a similar mesh.
     maxLocalCells   1000000;
+
+
+    // Overall cell limit (approximately). Refinement will stop immediately
+    // upon reaching this number so a refinement level might not complete.
+    // Note that this is the number of cells before removing the part which
+    // is not 'visible' from the keepPoint. The final number of cells might
+    // actually be a lot less.
     maxGlobalCells  2000000;
+
+    // The surface refinement loop might spend lots of iterations refining just a
+    // few cells. This setting will cause refinement to stop if <= minimumRefine
+    // are selected for refinement. Note: it will at least do one iteration
+    // (unless the number of cells to refine is 0)
     minRefinementCells 10;
+
+    // Number of buffer layers between different levels.
+    // 1 means normal 2:1 refinement restriction, larger means slower
+    // refinement.
     nCellsBetweenLevels 2;
-    features        ( );
+
+
+
+    // Explicit feature edge refinement
+    // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    // Specifies a level for any cell intersected by its edges.
+    // This is a featureEdgeMesh, read from constant/triSurface for now.
+    features
+    (
+        //{
+        //    file "someLine.eMesh";
+        //    level 2;
+        //}
+    );
+
+
+
+    // Surface based refinement
+    // ~~~~~~~~~~~~~~~~~~~~~~~~
+
+    // Specifies two levels for every surface. The first is the minimum level,
+    // every cell intersecting a surface gets refined up to the minimum level.
+    // The second level is the maximum level. Cells that 'see' multiple
+    // intersections where the intersections make an
+    // angle > resolveFeatureAngle get refined up to the maximum level.
+
     refinementSurfaces
     {
         motorBike
         {
+            // Surface-wise min and max refinement level
             level           ( 5 6 );
         }
     }
 
+    // Resolve sharp angles
     resolveFeatureAngle 30;
+
+
+    // Region-wise refinement
+    // ~~~~~~~~~~~~~~~~~~~~~~
+
+    // Specifies refinement level for cells in relation to a surface. One of
+    // three modes
+    // - distance. 'levels' specifies per distance to the surface the
+    //   wanted refinement level. The distances need to be specified in
+    //   descending order.
+    // - inside. 'levels' is only one entry and only the level is used. All
+    //   cells inside the surface get refined up to the level. The surface
+    //   needs to be closed for this to be possible.
+    // - outside. Same but cells outside.
     refinementRegions
     {
         refinementBox
@@ -62,19 +136,45 @@ castellatedMeshControls
         }
     }
 
+
+
+    // Mesh selection
+    // ~~~~~~~~~~~~~~
+
+    // After refinement patches get added for all refinementSurfaces and
+    // all cells intersecting the surfaces get put into these patches. The
+    // section reachable from the locationInMesh is kept.
+    // NOTE: This point should never be on a face, always inside a cell, even
+    // after refinement.
     locationInMesh  ( 3 3 0.43 );
 }
 
+
+// Settings for the snapping.
 snapControls
 {
+    //- Number of patch smoothing iterations before finding correspondence
+    //  to surface
     nSmoothPatch    3;
+
+    //- Relative distance for points to be attracted by surface feature point
+    //  or edge. True distance is this factor times local
+    //  maximum edge length.
     tolerance       4;
+
+    //- Number of mesh displacement relaxation iterations.
     nSolveIter      30;
+
+    //- Maximum number of snapping relaxation iterations. Should stop
+    //  before upon reaching a correct mesh.
     nRelaxIter      5;
 }
 
+
+// Settings for the layer addition.
 addLayersControls
 {
+    // Per final patch (so not geometry!) the layer information
     layers
     {
         minZ
@@ -418,41 +518,126 @@ addLayersControls
         }
     }
 
+    // Expansion factor for layer mesh
     expansionRatio  1;
+
+    //- Wanted thickness of final added cell layer. If multiple layers
+    //  is the
+    //  thickness of the layer furthest away from the wall.
+    //  Relative to undistorted size of cell outside layer.
     finalLayerRatio 0.3;
+
+    //- Minimum thickness of cell layer. If for any reason layer
+    //  cannot be above minThickness do not add layer.
+    //  Relative to undistorted size of cell outside layer.
     minThickness    0.1;
+
+    //- If points get not extruded do nGrow layers of connected faces that are
+    //  also not grown. This helps convergence of the layer addition process
+    //  close to features.
     nGrow           1;
+
+
+    // Advanced settings
+
+    //- When not to extrude surface. 0 is flat surface, 90 is when two faces
+    //  make straight angle.
     featureAngle    30;
+
+    //- Maximum number of snapping relaxation iterations. Should stop
+    //  before upon reaching a correct mesh.
     nRelaxIter      3;
+
+    // Number of smoothing iterations of surface normals
     nSmoothSurfaceNormals 1;
+
+    // Number of smoothing iterations of interior mesh movement direction
     nSmoothNormals  3;
+
+    // Smooth layer thickness over surface patches
     nSmoothThickness 10;
+
+    // Stop layer growth on highly warped cells
     maxFaceThicknessRatio 0.5;
+
+    // Reduce layer growth where ratio thickness to medial
+    // distance is large
     maxThicknessToMedialRatio 0.3;
+
+    // Angle used to pick up medial axis points
     minMedianAxisAngle 130;
+
+    // Create buffer region for new layer terminations
     nBufferCellsNoExtrude 0;
 }
 
+
+// Generic mesh quality settings. At any undoable phase these determine
+// where to undo.
 meshQualityControls
 {
+    //- Maximum non-orthogonality allowed. Set to 180 to disable.
     maxNonOrtho     65;
+
+    //- Max skewness allowed. Set to <0 to disable.
     maxBoundarySkewness 20;
     maxInternalSkewness 4;
+
+    //- Max concaveness allowed. Is angle (in degrees) below which concavity
+    //  is allowed. 0 is straight face, <0 would be convex face.
+    //  Set to 180 to disable.
     maxConcave      80;
+
+    //- Minimum projected area v.s. actual area. Set to -1 to disable.
     minFlatness     0.5;
+
+    //- Minimum pyramid volume. Is absolute volume of cell pyramid.
+    //  Set to very negative number (e.g. -1E30) to disable.
     minVol          1e-13;
+
+    //- Minimum face area. Set to <0 to disable.
     minArea         -1;
+
+    //- Minimum face twist. Set to <-1 to disable. dot product of face normal
+    //- and face centre triangles normal
     minTwist        0.02;
+
+    //- minimum normalised cell determinant
+    //- 1 = hex, <= 0 = folded or flattened illegal cell
     minDeterminant  0.001;
+
+    //- minFaceWeight (0 -> 0.5)
     minFaceWeight   0.02;
+
+    //- minVolRatio (0 -> 1)
     minVolRatio     0.01;
+
+    //must be >0 for Fluent compatibility
     minTriangleTwist -1;
+
+
+    // Advanced
+
+    //- Number of error distribution iterations
     nSmoothScale    4;
+    //- amount to scale back displacement at error points
     errorReduction  0.75;
 }
 
+
+
+// Advanced
+
+// Flags for optional output
+// 0 : only write final meshes
+// 1 : write intermediate meshes
+// 2 : write volScalarField with cellLevel for postprocessing
+// 4 : write current intersections as .obj files
 debug           0;
 
+
+// Merge tolerance. Is fraction of overall bounding box of initial mesh.
+// Note: the write tolerance needs to be higher than this.
 mergeTolerance  1e-06;