From 5172a110c0e7c8774b5213f927a5cc0468f52d2c Mon Sep 17 00:00:00 2001 From: Stephen Copplestone Date: Mon, 27 Nov 2023 10:28:16 +0100 Subject: [PATCH 1/2] Added new extension to RTD to increase the width of the page to 98% --- docs/documentation/conf.py | 4 ++++ docs/documentation/requirements.txt | 1 + 2 files changed, 5 insertions(+) diff --git a/docs/documentation/conf.py b/docs/documentation/conf.py index 68f20396f..f42592400 100644 --- a/docs/documentation/conf.py +++ b/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'] diff --git a/docs/documentation/requirements.txt b/docs/documentation/requirements.txt index ed7a1439f..f311ed095 100644 --- a/docs/documentation/requirements.txt +++ b/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 From f898f0cfb6323e130c59862912174d8e44b0a131 Mon Sep 17 00:00:00 2001 From: Paul Nizenkov Date: Tue, 28 Nov 2023 21:43:09 +0100 Subject: [PATCH 2/2] Added absolute sizes to images to avoid oversized images on large screens --- docs/documentation/index.md | 6 +++++- .../tutorials/dsmc-cone-2D/dsmc-cone-2D.md | 20 +++++++++---------- .../tutorials/dsmc-cone-3D/dsmc-cone-3D.md | 6 +++--- .../dsmc-reservoir/dsmc-reservoir.md | 8 ++++---- .../pic-poisson-plasma-wave.md | 8 +++++--- 5 files changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/documentation/index.md b/docs/documentation/index.md index 14239c761..4b4d68496 100644 --- a/docs/documentation/index.md +++ b/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 diff --git a/docs/documentation/userguide/tutorials/dsmc-cone-2D/dsmc-cone-2D.md b/docs/documentation/userguide/tutorials/dsmc-cone-2D/dsmc-cone-2D.md index 4b54a4d83..ce641fd99 100644 --- a/docs/documentation/userguide/tutorials/dsmc-cone-2D/dsmc-cone-2D.md +++ b/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. diff --git a/docs/documentation/userguide/tutorials/dsmc-cone-3D/dsmc-cone-3D.md b/docs/documentation/userguide/tutorials/dsmc-cone-3D/dsmc-cone-3D.md index 084be3b0b..ba474bf63 100644 --- a/docs/documentation/userguide/tutorials/dsmc-cone-3D/dsmc-cone-3D.md +++ b/docs/documentation/userguide/tutorials/dsmc-cone-3D/dsmc-cone-3D.md @@ -60,7 +60,7 @@ 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`. @@ -68,7 +68,7 @@ As another possibility, the `SplitToHex` option can be enabled in the `hopr.ini` ```{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. diff --git a/docs/documentation/userguide/tutorials/dsmc-reservoir/dsmc-reservoir.md b/docs/documentation/userguide/tutorials/dsmc-reservoir/dsmc-reservoir.md index 2472ebf1c..cdf01ad0e 100644 --- a/docs/documentation/userguide/tutorials/dsmc-reservoir/dsmc-reservoir.md +++ b/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. diff --git a/docs/documentation/userguide/tutorials/pic-poisson-plasma-wave/pic-poisson-plasma-wave.md b/docs/documentation/userguide/tutorials/pic-poisson-plasma-wave/pic-poisson-plasma-wave.md index 23c8aeb74..3419df9f5 100644 --- a/docs/documentation/userguide/tutorials/pic-poisson-plasma-wave/pic-poisson-plasma-wave.md +++ b/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.