Merge branch 'documentation.rtd.width.98' into 'master.dev'

[documentation.rtd.width.98] Added new extension to RTD to increase the width of the page to 98%

See merge request piclas/piclas!882

docs/documentation/conf.py

@@ -40,9 +40,13 @@
         'sphinx.ext.autosectionlabel',
         'sphinxcontrib.bibtex',
         'sphinx_rtd_theme',
+        'sphinx_rtd_size',
         'myst_parser'
         ]
 
+# Set width
+sphinx_rtd_size_width='98%'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/documentation/index.md

@@ -7,7 +7,11 @@
 
 # Welcome to the PICLas Documentation!
 
-![alt](../logo.png)
+```{image} ../logo.png
+:alt: logo
+:width: 600px
+:align: center
+```
 
 [**PICLas**](https://github.com/piclas-framework/piclas)  is a three-dimensional simulation
 framework for Particle-in-Cell, Direct Simulation Monte Carlo and other particle methods that can be coupled for

docs/documentation/requirements.txt

@@ -3,6 +3,7 @@
 # Defining the exact version will make sure things don't break
 sphinx==4.2.0
 sphinx_rtd_theme==0.5.2
+sphinx_rtd_size==0.2.0
 readthedocs-sphinx-search==0.1.0rc3
 myst_parser==0.15.1
 sphinxcontrib.bibtex==2.3.0

docs/documentation/userguide/tutorials/dsmc-cone-2D/dsmc-cone-2D.md

@@ -16,7 +16,7 @@ Before the actual simulation is conducted, a mesh file in the HDF5 format has to
 ```{figure} mesh/dsmc-cone-mesh-bcs.jpg
 ---
 name: fig:dsmc-cone-mesh
-width: 90%
+width: 600px
 ---
 
 Mesh of the 70° Cone.
@@ -71,7 +71,7 @@ ranges from zero to a positive value. Additionally, the mesh shall be centered a
 row. As the loaded file only consists of a surface, which is meshed with Gmsh and then extruded using Hopr, the surface needs to be translated:
 
     Translate {0, 0, -1} {
-        Surface{1}; 
+        Surface{1};
     }
 
 Physical groups are used to define the boundary conditions at all curves:
@@ -113,7 +113,7 @@ The mesh can be created by simplying executing Gmsh from the terminal:
     gmsh 70degCone_2DSurf.geo
 
 The resulting mesh shall consist of quad elements and not triangles. Finally, it has to be converted to the file format used by **piclas** using HOPR by supplying an input file `hopr.ini` using the corresponding mode:
-    
+
     Mode = 5
 
 To extrude the 2D quadrangular mesh to a 3D hexahedral mesh with only one element in the third direction, the following commands next to be set in the `hopr.ini`:
@@ -130,7 +130,7 @@ Again, to create the `.h5` mesh file, you would simply run
 
     hopr hopr_gmsh.ini
 
-This would create the mesh file `70degCone_2D_mesh.h5` in HDF5 format. 
+This would create the mesh file `70degCone_2D_mesh.h5` in HDF5 format.
 
 ## Flow simulation with DSMC
 
@@ -180,7 +180,7 @@ In axially symmetrical cases, the simulation effort can be greatly reduced. For
     Particles-Symmetry-Order         = 2
     Particles-Symmetry2DAxisymmetric = T
 
-First of all, certain requirements are placed on the grid. The $y$-axis acts as the symmetry axis, while the $x$-axis defines the radial direction. Therefore grid lies in the $xy$-plane and should have an extension of one cell in the $z$-direction, the extent in $z$-direction is irrelevant whilst it is centered on $z=0$. In addition, the boundary at $y = 0$ must be provided with the condition `symmetric_axis` and the boundaries parallel to the $xy$-plane with the condition `symmetric`. 
+First of all, certain requirements are placed on the grid. The $y$-axis acts as the symmetry axis, while the $x$-axis defines the radial direction. Therefore grid lies in the $xy$-plane and should have an extension of one cell in the $z$-direction, the extent in $z$-direction is irrelevant whilst it is centered on $z=0$. In addition, the boundary at $y = 0$ must be provided with the condition `symmetric_axis` and the boundaries parallel to the $xy$-plane with the condition `symmetric`.
 
     Part-Boundary4-SourceName  = SYMAXIS
     Part-Boundary4-Condition   = symmetric_axis
@@ -281,9 +281,9 @@ re-balancing step via HDF5, which will create a state file and restart from this
 
 After running a simulation, especially if done for the first time it is strongly recommended to ensure the quality of the results. For this purpose, the `Particles-DSMC-CalcQualityFactors = T` should be set, to enable the calculation of quality factors such as the maximum collision probability and the mean collision separation distance over the mean free path. All needed datasets can be found in the `*_DSMCState_*.h5` or the converted `*_visuDSMC_*.vtu`.
 
-First of all, it should be ensured that a sufficient number of simulation particles were available for the averaging, which forms the basis of the shown data. The value `*_SimPartNum` indicates the average number of simulated particles in the respective cell. For a sufficient sampling size, it should be guaranteed that at least 10 particles are in each cell, however, this number is very case-specific. The value `DSMC_MCSoverMFP` is an other indicator for the quality of the particle discretization of the simulation area. A value above 1 indicates that the mean collision separation distance is greater than the mean free path, which is a signal for too few simulation particles. For 3D simulations it is sufficient to adjust the `Part-Species[$]-MacroParticleFactor` accordingly in **parameter.ini**. In 2D axisymmetric simulations, the associated scaling factors such as `Particles-RadialWeighting-PartScaleFactor` can also be optimized (see Section {ref}`sec:2D-axisymmetric`). 
+First of all, it should be ensured that a sufficient number of simulation particles were available for the averaging, which forms the basis of the shown data. The value `*_SimPartNum` indicates the average number of simulated particles in the respective cell. For a sufficient sampling size, it should be guaranteed that at least 10 particles are in each cell, however, this number is very case-specific. The value `DSMC_MCSoverMFP` is an other indicator for the quality of the particle discretization of the simulation area. A value above 1 indicates that the mean collision separation distance is greater than the mean free path, which is a signal for too few simulation particles. For 3D simulations it is sufficient to adjust the `Part-Species[$]-MacroParticleFactor` accordingly in **parameter.ini**. In 2D axisymmetric simulations, the associated scaling factors such as `Particles-RadialWeighting-PartScaleFactor` can also be optimized (see Section {ref}`sec:2D-axisymmetric`).
 
-Similarly, the values `DSMC_MeanCollProb` and` DSMC_MaxCollProb` should be below 1 in order to avoid nonphysical values. While the former indicates the averaged collision probability per timestep, the latter stores the maximum collision probability. If this limit is not met, more collisions should have ocurred within a time step than possible. A refinement of the time step `ManualTimeStep` in **parameter.ini** is therefore necessary. If a variable timestep is also used in the simulation, there are further options (see Section {ref}`sec:variable-time-step`). 
+Similarly, the values `DSMC_MeanCollProb` and` DSMC_MaxCollProb` should be below 1 in order to avoid nonphysical values. While the former indicates the averaged collision probability per timestep, the latter stores the maximum collision probability. If this limit is not met, more collisions should have ocurred within a time step than possible. A refinement of the time step `ManualTimeStep` in **parameter.ini** is therefore necessary. If a variable timestep is also used in the simulation, there are further options (see Section {ref}`sec:variable-time-step`).
 
 ```{table} Target value to ensure physical results and a connected input parameter
 ---
@@ -304,12 +304,12 @@ To visualize the data which represents the properties in the domain (e.g. temper
 
     ./piclas2vtk dsmc_cone_DSMCState_000.00*
 
-to generate the corresponding VTK files, which can then be loaded into your visualization tool. The resulting translational temperature and velocity in the domain are shown in {numref}`fig:dsmc-cone-visu`. The visualized variables are `Total_TempTransMean`, which is mean translational temperature and the magnitude of the velocities `Total_VeloX`, `Total_VeloX`, `Total_VeloX` (which is automatically generated by ParaView). Since the data is stored on the original mesh (and not the internally refined octree mesh), the data initially looks as shown in the two upper halves. **ParaView** offers the possibility to interpolate this data using the `CellDatatoPointData` filter. The data visualized in this way can be seen in the lower half of the image. 
+to generate the corresponding VTK files, which can then be loaded into your visualization tool. The resulting translational temperature and velocity in the domain are shown in {numref}`fig:dsmc-cone-visu`. The visualized variables are `Total_TempTransMean`, which is mean translational temperature and the magnitude of the velocities `Total_VeloX`, `Total_VeloX`, `Total_VeloX` (which is automatically generated by ParaView). Since the data is stored on the original mesh (and not the internally refined octree mesh), the data initially looks as shown in the two upper halves. **ParaView** offers the possibility to interpolate this data using the `CellDatatoPointData` filter. The data visualized in this way can be seen in the lower half of the image.
 
 ```{figure} results/dsmc-cone-visu.jpg
 ---
 name: fig:dsmc-cone-visu
-width: 90%
+width: 600px
 ---
 
 Translational temperature and velocity in front of the 70° Cone, top: original data; bottom: interpolated data.
@@ -327,7 +327,7 @@ to generate the corresponding VTK files, which can then be loaded into your visu
 ```{figure} results/dsmc-cone-heatflux.svg
 ---
 name: fig:dsmc-cone-heatflux
-width: 50%
+width: 400px
 ---
 
 Experimental heat flux data compared with simulation results from PIClas.

docs/documentation/userguide/tutorials/dsmc-cone-3D/dsmc-cone-3D.md

@@ -60,15 +60,15 @@ The following commands are required to save all elements even if they are not pa
     Save "70degCone_3D.msh";
 
 The mesh file in the file format `.h5` used by **piclas** has to be converted using HOPR by supplying an input file `hopr.ini` using the corresponding mode:
-    
+
     Mode = 5
 
 As another possibility, the `SplitToHex` option can be enabled in the `hopr.ini` file instead of using the `SubdivionAlgorithm` command in Gmsh. The expected result for the 3D mesh is shown in {numref}`fig:dsmc-cone-gmsh-mesh`.
 
 ```{figure} mesh/dsmc-cone-gmsh-mesh.jpg
 ---
 name: fig:dsmc-cone-gmsh-mesh
-width: 90%
+width: 600px
 ---
 
 3D mesh of the 70° cone.
@@ -109,7 +109,7 @@ An exemplary simulation result using the 3D mesh generated with Gmsh is shown in
 ```{figure} results/dsmc-cone-gmsh-visu.jpg
 ---
 name: fig:dsmc-cone-gmsh-visu
-width: 90%
+width: 600px
 ---
 
 Translational temperature around the 70° cone.

docs/documentation/userguide/tutorials/dsmc-reservoir/dsmc-reservoir.md

@@ -25,7 +25,7 @@ The size of the simulation domain is set to [$\pu{4.64e-6}\times\pu{4.64e-6}\tim
 ```{figure} mesh/dsmc-reservoir-mesh-corners.svg
 ---
 name: fig:dsmc-reservoir-mesh-corners
-width: 50%
+width: 400px
 ---
 Order of the corners to define the used mesh. The first node is placed at the origin.
 ```
@@ -273,7 +273,7 @@ In addition to `std.out`, which contains information about the simulation proces
 ```{figure} results/dsmc-reservoir-temperature-relaxation.svg
 ---
 name: fig:dsmc-reservoir-temperature-relaxation
-width: 50%
+width: 400px
 ---
 
 Temperature relaxation process towards thermal equilibrium.
@@ -375,7 +375,7 @@ The `Projectname_visuPart_Timestamp.vtu` files contain simulation particle speci
 ```{figure} results/dsmc-reservoir-species.jpg
 ---
 name: fig:dsmc-reservoir-species
-width: 100%
+width: 600px
 ---
 
 Comparison of the present species (simulation particles) at start (left) and end (right) time of the simulation.
@@ -386,7 +386,7 @@ While the figure above is only capable of giving a general overview about the pr
 ```{figure} results/dsmc-reservoir-reaction.jpg
 ---
 name: fig:dsmc-reservoir-reaction
-width: 100%
+width: 600px
 ---
 
 Development of species composition (left) and translational temperature and dissociation rate (right) over time.

docs/documentation/userguide/tutorials/pic-poisson-plasma-wave/pic-poisson-plasma-wave.md

@@ -80,6 +80,7 @@ boundary for the same periodic vector.
 ```{figure} mesh/tut-pic-pw-mesh.jpg
 ---
 name: fig:plasma-wave-mesh
+width: 700px
 ---
 
 Mesh with $60\times1\times1$ elements and a size of [$2\pi\times0.2\times0.2$] m$^{3}$.
@@ -306,7 +307,7 @@ Each type of the initialization set might have a different set of parameters and
 
 
 To calculate the number of simulation particles of, e.g. electrons, defined by `Part-Species1-Init1-ParticleNumber`, the given
-number density $n_{e}$ in {numref}`tab:pic_poisson_plasma_wave_phys`, the selected weighting factor $w_{e}$ and the volume of the 
+number density $n_{e}$ in {numref}`tab:pic_poisson_plasma_wave_phys`, the selected weighting factor $w_{e}$ and the volume of the
 complete domain ($V=2\pi\cdot0.2\cdot0.2\pu{m^{3}}$) are utilized.
 
 $$ N_{e,sim} = \frac{n_{e} V}{w_{e}} $$
@@ -351,7 +352,7 @@ The command
 
 executes the code and dumps all output into the file *std.out*.
 To reduce the computation time, the simulation can be run using the Message Passing Interface (MPI) on multiple cores, in this case 4
-	
+
     mpirun -np 4 piclas parameter.ini | tee std.out
 
 If the run has completed successfully, which should take only a brief moment, the contents of the working folder should look like
@@ -413,7 +414,7 @@ The parameters for **piclas2vtk** are stored in the **parameter.ini** file under
 where `NVisu` is the polynomial visualization degree on which the field solution is interpolated.
 Depending on the used polynomial degree `N` and subsequently the degree of visualization `NVisu`, which should always be higher than
 `N`, the resulting electric potential $\Phi$ and its derivative the electric field strength **E** might show signs of oscillations.
-This is because the PIC simulation is always subject to noise that is influenced by the discretization (number of elements and 
+This is because the PIC simulation is always subject to noise that is influenced by the discretization (number of elements and
 polynomial degree as well as number of particles) and is visible in the solution as this is a snapshot of the current simulation.
 
 Additionally, the flag `VisuParticles` activates the output of particle position, velocity and species to the *vtk*-files.
@@ -431,6 +432,7 @@ The electric potential field can be viewed, e.g., by opening `plasma_wave_Soluti
 ```{figure} results/tut-pic-pw-results.jpg
 ---
 name: fig:plasma-wave-results
+width: 700px
 ---
 
 Resulting electric potential and field.