Tutorials

docs/documentation/index.md

@@ -29,6 +29,18 @@ caption: Developer Guide
 developerguide/index.md
 ```
 
+```{toctree}
+---
+maxdepth: 4
+caption: Tutorials
+---
+tutorials/index_inbuiltmeshgenerators.md
+tutorials/index_externalmeshes.md
+tutorials/index_agglomeration.md
+tutorials/index_postprocessing.md
+tutorials/index_visualization.md
+```
+
 ```{toctree}
 ---
 maxdepth: 1

docs/documentation/tutorials/externalmesheswithoutcurvedboundaries.md

@@ -0,0 +1,162 @@
+# External Meshes without Curved Boundaries
+This tutorial shows how to read in externally generated unstructured and structured meshes with straight-edged elements.
+
+The parameter file can be found in
+
+    tutorials/2-01-external_mesh_sphere/parameter.ini
+
+## External Mesh
+The external mesh which shall read in have to be available in the directory of the executed parameter file as CGNS file. This file is read-in by introducing the parameter `filename`. As one can see from the `parameter.ini`'s excerpt and <a class="reference internal" href="#fig-cgnsviewer-spheremesh04"><span class="std std-numref">Fig. 1.1</span></a>, the parameters of the parameter file have to be adapted to the definitions in the CGNS mesh file. This means that the parameters Mode, `nZones`, `BoundaryName` and `BoundaryType` can not be set freely anymore because the structure of the external mesh must be retained. In this case, the external mesh `spheremesh02` is available as CGNS file and consists of three zones. Therefore, the settings of the parameters are `Mode=3`, `nZones=3`, `filename=spheremesh02.cgns`.
+
+Another important fact is that for external meshes no `BCIndex` parameter is needed which assigns normally bondary conditions to the surfaces of the mesh. The reason for this is that the boundary conditions are assigned to their belonging surfaces by their names. The boundary condition, for example, of `Zone_1` of the CGNS file (`BC_sphere`) has to be defined as `BoundaryName=sphere` in the parameter file. 
+
+    !================================================================= !
+    ! MESH
+    !================================================================= !
+    Mode    =3                  ! 1 Cartesian 3 CGNS 4 STAR-CD V3 
+    nZones  =3                  ! number of zones
+    filename=spheremesh02.cgns  ! name of mesh file
+    ...
+    ...
+
+    !================================================================= !
+    ! CURVED
+    !================================================================= !
+    useCurveds=F                ! T to generate curved boundaries 
+
+
+    !================================================================= !
+    ! BOUNDARY CONDITIONS
+    !================================================================= !
+    BoundaryName=sphere         ! BC_Name must be defined in mesh file
+    BoundaryType=(/4,1,0,0/)    
+    BoundaryName=inflow               
+    BoundaryType=(/2,0,0,0/)
+    BoundaryName=outflow             
+    BoundaryType=(/2,0,0,0/)
+    BoundaryName=mantel           
+    BoundaryType=(/2,0,0,0/)
+
+
+<figure class="align-center" id="fig-cgnsviewer-spheremesh04">
+    <a class="reference internal image-reference" href="../_images/CGNSviewer_spheremesh04.png"><img alt="../_images/CGNSviewer_spheremesh04.png" src="../_images/CGNSviewer_spheremesh04.png" style="width: 30%;" /></a>
+    <figcaption>
+    <p><span class="caption-number">Fig. 1.1 </span><span class="caption-text">Screenshot of the folder structure of a CGNS mesh.</span><a class="headerlink" href="#fig-cgnsviewer-spheremesh04" title="Permalink to this image"></a></p>
+    </figcaption>
+</figure>
+
+Furthermore, the `BoundaryType` parameter has to be adapted to the definitions in the CGNS mesh file. If a boundary of the external mesh is curved the `curveIndex` component (2nd component) of the `BoundaryType` parameter has to be an value unequal to zero. Wether curved boundaries shall be generated or not can be controlled by the parameter `useCurveds`. In this tutorial `useCurveds=F`. The case `useCurveds=T` is the topic of the next tutorial which explaines how to use mesh curving techniques to get curved boundaries for your mesh.
+
+All new parameters of the parameter file of this tutorial are explained below.
+
+```{table} External Mesh Parameters.
+---
+name: tab:External Mesh Parameters
+---
+  | Parameters      |Setting                | Description | 
+  | :------         | :----------:          | :---------------------------     |
+  | `filename`      | `spheremesh.cgns`     |  	The name of the external mesh file. The belonging files have to be available in the directory of the executed parameter file as CGNS files. |
+  | `meshscale`      | ` 	0.001`     |  	Scales all input meshes by a factor |
+  | `SpaceQuandt`      | ` 	1000`     |  	Characteristic length of the mesh  |
+  | `useCurveds`      | `T`     |  	 	T (True): If curved boundaries are defined<br>F (False): If no curved boundaries are defined . |
+```
+
+A description of all parameters of the parameterfile can be found in {ref}`userguide/parameters:List of Parameters`.
+
+## Output Visualization
+If there is a need for assistance of visualizing the HOPR output visit {ref}`tutorials/index_visualization:Visualization`.
+
+The figures below show the visualizations of the `SPHERE_Debugmesh.vtu` file. In Addition, a visualization of the surfaces the first boundary condition sphere was assigned to (the `curveIndex` of the `BoundaryType` parameter is set to 1) of the `SPHERE_Debugmesh_BC.vtu` file is shown for each external mesh (see <a class="reference internal" href="#fig-exmeshwo-spheremesh01-innerbc"><span class="std std-numref">Fig. 1.4</span></a>, <a class="reference internal" href="#fig-exmeshwo-spheremesh02-innerbc"><span class="std std-numref">Fig. 1.7</span></a>, <a class="reference internal" href="#fig-exmeshwo-spheremesh04-innerbc"><span class="std std-numref">Fig. 1.10</span></a>)
+
+<h4>spheremesh01<a class="headerlink" href="#spheremesh01" title="Permalink to this heading"></a></h4>
+
+<table align="center" style="width:100%">
+  <tr>
+    <td style="width:33%">
+        <figure id="fig-exmeshwo-spheremesh01-surfaces">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh01_surfaces.jpg"><img alt="../_images/Exmeshwo_spheremesh01_surfaces.jpg" src="../_images/Exmeshwo_spheremesh01_surfaces.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.2 </span><span class="caption-text">HOPR output of spheremesh01.cgns</span><a class="headerlink" href="#fig-exmeshwo-spheremesh01-surfaces" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+    <td style="width:33%">
+        <figure id="fig-exmeshwo-spheremesh01-mesh">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh01_mesh.jpg"><img alt="../_images/Exmeshwo_spheremesh01_mesh.jpg" src="../_images/Exmeshwo_spheremesh01_mesh.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.3 </span><span class="caption-text">HOPR output of spheremesh01.cgns with extracted edges.</span><a class="headerlink" href="#fig-exmeshwo-spheremesh01-mesh" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td style="width:33%">
+        <td>
+        <figure id="fig-exmeshwo-spheremesh01-innerbc">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh01_innerbc.jpg"><img alt="../_images/Exmeshwo_spheremesh01_innerbc.jpg" src="../_images/Exmeshwo_spheremesh01_innerbc.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.4 </span><span class="caption-text">Element surfaces (6) of spheremesh01.cgns the boundary condition sphere was assigned to.</span><a class="headerlink" href="#fig-exmeshwo-spheremesh01-innerbc" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+  </tr>
+</table>
+
+<h4>spheremesh02<a class="headerlink" href="#spheremesh02" title="Permalink to this heading"></a></h4>
+
+<table align="center" style="width:100%">
+  <tr>
+    <td style="width:33%">
+        <figure id="fig-exmeshwo-spheremesh02-surfaces">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh02_surfaces.jpg"><img alt="../_images/Exmeshwo_spheremesh02_surfaces.jpg" src="../_images/Exmeshwo_spheremesh02_surfaces.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.5 </span><span class="caption-text">HOPR output of spheremesh02.cgns</span><a class="headerlink" href="#fig-exmeshwo-spheremesh02-surfaces" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+    <td style="width:33%">
+        <figure id="fig-exmeshwo-spheremesh02-mesh">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh02_mesh.jpg"><img alt="../_images/Exmeshwo_spheremesh02_mesh.jpg" src="../_images/Exmeshwo_spheremesh02_mesh.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.6 </span><span class="caption-text">HOPR output of spheremesh02.cgns with extracted edges.</span><a class="headerlink" href="#fig-exmeshwo-spheremesh02-mesh" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td style="width:33%">
+        <td>
+        <figure id="fig-exmeshwo-spheremesh02-innerbc">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh02_innerbc.jpg"><img alt="../_images/Exmeshwo_spheremesh02_innerbc.jpg" src="../_images/Exmeshwo_spheremesh02_innerbc.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.7 </span><span class="caption-text">Element surfaces (24) of spheremesh02.cgns the boundary condition sphere was assigned to.</span><a class="headerlink" href="#fig-exmeshwo-spheremesh02-innerbc" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+  </tr>
+</table>
+
+<h4>spheremesh04<a class="headerlink" href="#spheremesh04" title="Permalink to this heading"></a></h4>
+
+<table align="center" style="width:100%">
+  <tr>
+    <td style="width:33%">
+        <figure id="fig-exmeshwo-spheremesh04-surfaces">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh04_surfaces.jpg"><img alt="../_images/Exmeshwo_spheremesh04_surfaces.jpg" src="../_images/Exmeshwo_spheremesh04_surfaces.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.8 </span><span class="caption-text">HOPR output of spheremesh04.cgns</span><a class="headerlink" href="#fig-exmeshwo-spheremesh04-surfaces" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+    <td style="width:33%">
+        <figure id="fig-exmeshwo-spheremesh04-mesh">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh04_mesh.jpg"><img alt="../_images/Exmeshwo_spheremesh04_mesh.jpg" src="../_images/Exmeshwo_spheremesh04_mesh.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.9 </span><span class="caption-text">HOPR output of spheremesh04.cgns with extracted edges.</span><a class="headerlink" href="#fig-exmeshwo-spheremesh02-mesh" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td style="width:33%">
+        <td>
+        <figure id="fig-exmeshwo-spheremesh04-innerbc">
+        <a class="reference internal image-reference" href="../_images/Exmeshwo_spheremesh04_innerbc.jpg"><img alt="../_images/Exmeshwo_spheremesh04_innerbc.jpg" src="../_images/Exmeshwo_spheremesh04_innerbc.jpg" style="height:300px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 1.10 </span><span class="caption-text">Element surfaces (64) of spheremesh04.cgns the boundary condition sphere was assigned to.</span><a class="headerlink" href="#fig-exmeshwo-spheremesh04-innerbc" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+  </tr>
+</table>

docs/documentation/tutorials/generationofhexahedralmeshes.md

@@ -0,0 +1,30 @@
+# Generation of Hexahedral Meshes
+
+As many solvers require purely hexahedral meshes, HOPR implements a subdivision strategy to split meshes consisting of tetrahedra, prisms and hexahedra into purely hexahedral meshes. This feature is activated using the parameter `splitToHex=T`. Note, that pyramids cannot be decomposed to hexahedra in a straightforward way, thus this feature cannot be applied to meshes containing pyramids. Note also that this option is up to now restricted to linear meshes. 
+
+<table align="center" style="width:100%">
+  <tr>
+    <td style="width:50%">
+        <figure id="fig-splittohex0">
+        <a class="reference internal image-reference" href="../_images/Splittohex0.png"><img alt="../_images/Splittohex0.png" src="../_images/Splittohex0.png" style="height: 350px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 3.1 </span><span class="caption-text">Mesh consisting of 6 tetrahedra</span><a class="headerlink" href="#fig-splittohex0" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+    <td style="width:50%">
+        <figure id="fig-splittohex1">
+        <a class="reference internal image-reference" href="../_images/Splittohex1.png"><img alt="../_images/Splittohex1.png" src="../_images/Splittohex1.png" style="height: 350px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 3.2 </span><span class="caption-text">Each tetrahedron subdivided into 4 hexahedra</span><a class="headerlink" href="#fig-splittohex1" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+  </tr>
+</table>
+
+<h4>Parameter File<a class="headerlink" href="#parameter-file" title="Permalink to this heading"></a></h4>
+
+To test this feature, set elemtype to either 104 or 106 and add `splitToHex=T` to the parameter file, which is found in
+
+    tutorials/1-01-cartbox/parameter.ini

docs/documentation/tutorials/hoproutputparameter.md

@@ -0,0 +1,17 @@
+# HOPR Output Parameter
+
+```{table} HOPR Output Parameter.
+---
+name: tab:HOPR Output Parameter
+---
+  | Parameters      | Example               | Data Type | Array Dim. | Default Value | Description |
+  | :------         | :----------:          | :------:  | :------:   | :------:      | :------     |
+  | `Debugvisu`     | `Debugvisu=T`         |  Logical  |   1        |    F          | T (True): Files will be generated, which enable you to visualize the mesh and the boundary mesh for debugging. These files can be found in the directory of the executed `parameter.ini` file.<br>F (False): Files for visualization will not generated during executing of the `parameter.ini` file.             |
+  | `DebugvisuLevel`| `DebugvisuLevel=1`    |  Int      |   1        |    0          | 0: Visualization of linear mesh and BC (default).<br>1: Visualization of linear mesh and BC and an additional curved surface visualization (`_SplineSurf.*`) if `useCurveds=T`.<br>2: Visualization of linear mesh and BC and an additional curved volume visualization (`_SplineVol.*`) if `useCurveds=T`.             |
+  | `NVisu`         | `NVisu=5`             |  Int      |   1        |    0          | Number of visualization points per element edge if `useCurveds=T`.             |
+  | `outputFormat`  | `outputFormat=1`      |  Int      |   1        |    0          | 0: Paraview vtk (ASCII)<br>1: Tecplot (ASCII)<br>2: CGNS (binary)             |
+  | `ProjectName`   | `ProjectName=cartbox` |  Str      |   1        | OBLIGATORY    | Part of the output files' name which will be generated during the execution. These Files can be found in the directory of the executed `parameter.ini` file.             |
+```
+
+A description of all parameters of the parameterfile can be found in
+{ref}`userguide/parameters:List of Parameters`

docs/documentation/tutorials/index_agglomeration.md

@@ -0,0 +1,22 @@
+# Agglomeration of Block-Structured Meshes
+
+A simple strategy to create a fully curved mesh is to use block-structured meshes (must be given in structured CGNS format) and agglomerate linear elements to high order elements. 
+
+```{figure} figures/Periodichill_3Dview.png
+---
+name: fig:Periodichill_3Dview
+width: 400px
+align: center
+---
+Example of an agglomerated curved mesh of the periodic hill testcase
+```
+
+
+```{toctree}
+---
+maxdepth: 1
+caption: Table of Contents
+numbered:
+---
+blockstructuredmeshes.md
+```

docs/documentation/tutorials/index_externalmeshes.md

@@ -0,0 +1,23 @@
+# External Meshes
+
+In HOPR, it is possible to read unstructured meshes with straight edged elements, and, if needed, use several curving methods to account for curved domain boundaries. 
+```{figure} figures/DLRF6_bOrd5_innersplines.png
+---
+name: fig:DLRF6_bOrd5_innersplines
+width: 400px
+align: center
+---
+HOPR output: Curved surface and first layer of curved elements
+```
+To help the HOPR user to get familiar with these different features for external meshes three hands-on tutorials are provided. 
+
+```{toctree}
+---
+maxdepth: 1
+caption: Table of Contents
+numbered:
+---
+externalmesheswithoutcurvedboundaries.md
+externalmesheswithcurvedboundaries.md
+```
+

docs/documentation/tutorials/index_inbuiltmeshgenerators.md

@@ -0,0 +1,12 @@
+# In built Mesh Generators
+
+```{toctree}
+---
+maxdepth: 1
+caption: Table of Contents
+numbered:
+---
+straightedgedboxes.md
+curvedmeshes.md
+```
+

docs/documentation/tutorials/index_postprocessing.md

@@ -0,0 +1,14 @@
+# Post-processing Meshes
+
+Once a mesh is built there are several options to apply post-process meshes. 
+
+```{toctree}
+---
+maxdepth: 1
+caption: Table of Contents
+numbered:
+---
+meshuncurving.md
+meshrefinement.md
+generationofhexahedralmeshes.md
+```

docs/documentation/tutorials/index_visualization.md

@@ -0,0 +1,12 @@
+# Visualization
+
+
+```{toctree}
+---
+maxdepth: 1
+caption: Table of Contents
+numbered:
+---
+hoproutputparameter.md
+visualizationwithparaview.md
+```

docs/documentation/tutorials/meshrefinement.md

@@ -0,0 +1,31 @@
+# Mesh Refinement
+
+It is often desirable to refine existing meshes, by subdividing the elements into smaller elements. As HOPR implements this feature for Hexahedra only, it is controlled by the flag `nFineHexa=x`, where x specifies the number of subdivision of each element. For meshes containing other element types than hexahedra, this option is not applicable. Up to now, the refinement only works for hexa with linear edges. 
+
+<table align="center" style="width:100%">
+  <tr>
+    <td style="width:50%">
+        <figure id="fig-hopr-nfine1">
+        <a class="reference internal image-reference" href="../_images/Hopr_nfine1.png"><img alt="../_images/Hopr_nfine1.png" src="../_images/Hopr_nfine1.png" style="height: 350px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 2.1 </span><span class="caption-text">Standard mesh</span><a class="headerlink" href="#fig-hopr-nfine1" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+    <td style="width:50%">
+        <figure id="fig-Hopr-nfine2">
+        <a class="reference internal image-reference" href="../_images/Hopr_nfine2.png"><img alt="../_images/Hopr_nfine2.png" src="../_images/Hopr_nfine2.png" style="height: 350px;" /></a>
+        <figcaption>
+        <p><span class="caption-number">Fig. 2.2 </span><span class="caption-text">All elements refined by a factor of 2</span><a class="headerlink" href="#fig-Hopr-nfine2" title="Permalink to this image"></a></p>
+        </figcaption>
+        </figure>
+    </td>
+  </tr>
+</table>
+
+
+<h4>Parameter File<a class="headerlink" href="#parameter-file" title="Permalink to this heading"></a></h4>
+
+To test this feature add `nFineHexa=2` to the parameter file, which is also found in
+
+    tutorials/2-01-external_meshes_sphere/parameter.ini