Documentation: Tutorials

docs/documentation/conf.py

@@ -85,6 +85,9 @@
 # of the sidebar.
 html_logo = '../HOPR.png'
 
+# Extra path to copy
+html_extra_path = ['tutorials/figures/']
+
 # -- Bibliography ------------------------------------------------------------
 
 bibtex_bibfiles = ['references.bib']

docs/documentation/developerguide/examples.md

@@ -35,8 +35,16 @@ Hindenlang [bibcite key=Hindenlang2015], Gassner [bibcite key=gassner2011disp]
 ## Figures, caption
 ![This is the caption\label{mylabel}](https://github.com/hopr-framework/hopr/blob/master/docs/doxygen/HOPR.png?raw=true)
 
-See figure \ref{mylabel}.
+```{figure} https://github.com/piclas-framework/piclas/blob/master/docs/logo.png?raw=true
+---
+name: fig:mylabel
+width: 400px
+align: center
+---
 
+This is an example caption.
+```
+See {numref}`fig:mylabel` for an image from the web embedded in this documentation.
 
 ```{figure} figures/HOPR.png
 ---
@@ -47,7 +55,7 @@ align: center
 
 This is an example caption.
 ```
-See {numref}`fig:example`.
+See {numref}`fig:example` for embedding a local file.
 
 ## tables
 ## unnumbered section headings

docs/documentation/index.md

@@ -29,6 +29,18 @@ caption: Developer Guide
 developerguide/index.md
 ```
 
+```{toctree}
+---
+maxdepth: 4
+caption: Tutorials
+---
+tutorials/index_builtinmeshgenerators.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,163 @@
+# 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_CGNS_sphere/parameter.ini
+
+## External Mesh
+The external mesh file that is to be used has to be available in the directory of the executed parameter file as a CGNS format 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` cannot 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 normally assigns the boundary 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="../CGNSviewer_spheremesh04.png"><img alt="../CGNSviewer_spheremesh04.png" src="../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 a value unequal to zero. Whether curved boundaries are generated or not is controlled by the parameter `useCurveds`. In this tutorial, `useCurveds=F`. The case `useCurveds=T` is the topic of the next tutorial which explains how to use mesh curving techniques to generate curved boundaries.
+
+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 necessary files have to be available in the directory of the executed parameter file as CGNS files. |
+  | `meshscale`      | ` 	0.001`     |  	Scales all input mesh coordinates by a fixed 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 parameter file 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="../Exmeshwo_spheremesh01_surfaces.jpg"><img alt="../Exmeshwo_spheremesh01_surfaces.jpg" src="../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="../Exmeshwo_spheremesh01_mesh.jpg"><img alt="../Exmeshwo_spheremesh01_mesh.jpg" src="../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="../Exmeshwo_spheremesh01_innerbc.jpg"><img alt="../Exmeshwo_spheremesh01_innerbc.jpg" src="../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="../Exmeshwo_spheremesh02_surfaces.jpg"><img alt="../Exmeshwo_spheremesh02_surfaces.jpg" src="../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="../Exmeshwo_spheremesh02_mesh.jpg"><img alt="../Exmeshwo_spheremesh02_mesh.jpg" src="../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="../Exmeshwo_spheremesh02_innerbc.jpg"><img alt="../Exmeshwo_spheremesh02_innerbc.jpg" src="../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="../Exmeshwo_spheremesh04_surfaces.jpg"><img alt="../Exmeshwo_spheremesh04_surfaces.jpg" src="../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="../Exmeshwo_spheremesh04_mesh.jpg"><img alt="../Exmeshwo_spheremesh04_mesh.jpg" src="../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="../Exmeshwo_spheremesh04_innerbc.jpg"><img alt="../Exmeshwo_spheremesh04_innerbc.jpg" src="../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
+
+Since 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. Also note that this option is currently limited 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="../Splittohex0.png"><img alt="../Splittohex0.png" src="../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="../Splittohex1.png"><img alt="../Splittohex1.png" src="../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` (Tetrahedron) or `106` (Prism with triangular base) 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 parameter file 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_builtinmeshgenerators.md

@@ -0,0 +1,12 @@
+# Built-In Mesh Generators
+
+```{toctree}
+---
+maxdepth: 1
+caption: Table of Contents
+numbered:
+---
+straightedgedboxes.md
+curvedmeshes.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: 200px
+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_postprocessing.md

@@ -0,0 +1,14 @@
+# Post-processing Meshes
+
+Once a mesh is built there are several post-processing options available.
+
+```{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
+```