release task: update manual

doc/sphinx/parameters/Particles.md

@@ -147,7 +147,7 @@ The following properties are available:
 
 ‘quadrature points’: Generates particles at the quadrature points of each active cell of the triangulation. Here, Gauss quadrature of degree (velocity\_degree + 1), is used similarly to the assembly of Stokes matrix.
 
-‘random uniform’: Generates a random uniform distribution of particles over the entire simulation domain.
+‘random uniform’: Generates a random uniform distribution of particles over the entire simulation domain. This generator can be understood as the special case of the ’probability density function’ generator where the probability density is constant over the domain.
 
 ‘reference cell’: Generates a uniform distribution of particles per cell and spatial direction in the unit cell and transforms each of the particles back to real region in the model domain. Uniform here means the particles will be generated with an equal spacing in each spatial dimension.
 
@@ -387,13 +387,11 @@ A typical example would be to set this runtime parameter to ‘pi=3.14159265
 
 (parameters:Particles/Generator/Probability_20density_20function/Function_20expression)=
 ### __Parameter name:__ Function expression
-**Default value:** 0
+**Default value:** 1.0
 
 **Pattern:** [Anything]
 
-**Documentation:** The formula that denotes the function you want to evaluate for particular values of the independent variables. This expression may contain any of the usual operations such as addition or multiplication, as well as all of the common functions such as ‘sin’ or ‘cos’. In addition, it may contain expressions like ‘if(x>0, 1, -1)’ where the expression evaluates to the second argument if the first argument is true, and to the third argument otherwise. For a full overview of possible expressions accepted see the documentation of the muparser library at http://muparser.beltoforion.de/.
-
-If the function you are describing represents a vector-valued function with multiple components, then separate the expressions for individual components by a semicolon.
+**Documentation:** The formula that denotes the spatially variable probability density function. This expression may contain any of the usual operations such as addition or multiplication, as well as all of the common functions such as ‘sin’ or ‘cos’. In addition, it may contain expressions like ‘if(x>0, 1, 0)’ where the expression evaluates to the second argument if the first argument is true, and to the third argument otherwise; this example would result in no particles at all in that part of the domain where $x==0$, and a constant particle density in the rest of the domain. For a full overview of possible expressions accepted see the documentation of the muparser library at http://muparser.beltoforion.de/. Note that the function has to be non-negative everywhere in the domain, and needs to be positive in at least some parts of the domain.
 
 (parameters:Particles/Generator/Probability_20density_20function/Number_20of_20particles)=
 ### __Parameter name:__ Number of particles

doc/sphinx/parameters/Particles_202.md

@@ -139,7 +139,7 @@ The following properties are available:
 
 ‘quadrature points’: Generates particles at the quadrature points of each active cell of the triangulation. Here, Gauss quadrature of degree (velocity\_degree + 1), is used similarly to the assembly of Stokes matrix.
 
-‘random uniform’: Generates a random uniform distribution of particles over the entire simulation domain.
+‘random uniform’: Generates a random uniform distribution of particles over the entire simulation domain. This generator can be understood as the special case of the ’probability density function’ generator where the probability density is constant over the domain.
 
 ‘reference cell’: Generates a uniform distribution of particles per cell and spatial direction in the unit cell and transforms each of the particles back to real region in the model domain. Uniform here means the particles will be generated with an equal spacing in each spatial dimension.
 
@@ -379,13 +379,11 @@ A typical example would be to set this runtime parameter to ‘pi=3.14159265
 
 (parameters:Particles_202/Generator/Probability_20density_20function/Function_20expression)=
 ### __Parameter name:__ Function expression
-**Default value:** 0
+**Default value:** 1.0
 
 **Pattern:** [Anything]
 
-**Documentation:** The formula that denotes the function you want to evaluate for particular values of the independent variables. This expression may contain any of the usual operations such as addition or multiplication, as well as all of the common functions such as ‘sin’ or ‘cos’. In addition, it may contain expressions like ‘if(x>0, 1, -1)’ where the expression evaluates to the second argument if the first argument is true, and to the third argument otherwise. For a full overview of possible expressions accepted see the documentation of the muparser library at http://muparser.beltoforion.de/.
-
-If the function you are describing represents a vector-valued function with multiple components, then separate the expressions for individual components by a semicolon.
+**Documentation:** The formula that denotes the spatially variable probability density function. This expression may contain any of the usual operations such as addition or multiplication, as well as all of the common functions such as ‘sin’ or ‘cos’. In addition, it may contain expressions like ‘if(x>0, 1, 0)’ where the expression evaluates to the second argument if the first argument is true, and to the third argument otherwise; this example would result in no particles at all in that part of the domain where $x==0$, and a constant particle density in the rest of the domain. For a full overview of possible expressions accepted see the documentation of the muparser library at http://muparser.beltoforion.de/. Note that the function has to be non-negative everywhere in the domain, and needs to be positive in at least some parts of the domain.
 
 (parameters:Particles_202/Generator/Probability_20density_20function/Number_20of_20particles)=
 ### __Parameter name:__ Number of particles

doc/sphinx/parameters/Postprocess.md

@@ -892,7 +892,8 @@ Units: years if the ’Use years in output instead of seconds’ paramet
 
 **Pattern:** [Bool]
 
-**Documentation:** deal.II offers the possibility to filter duplicate vertices for HDF5 output files. This merges the vertices of adjacent cells and therefore saves disk space, but misrepresents discontinuous output properties. Activating this function reduces the disk space by about a factor of $2^{dim}$ for HDF5 output, and currently has no effect on other output formats. :::{warning}
+**Documentation:** deal.II offers the possibility to filter duplicate vertices for HDF5 output files. This merges the vertices of adjacent cells and therefore saves disk space, but misrepresents discontinuous output properties. Activating this function reduces the disk space by about a factor of $2^{dim}$ for HDF5 output, and currently has no effect on other output formats.
+ :::{warning}
 Setting this flag to true will result in visualization output that does not accurately represent discontinuous fields. This may be because you are using a discontinuous finite element for the pressure, temperature, or compositional variables, or because you use a visualization postprocessor that outputs quantities as discontinuous fields (e.g., the strain rate, viscosity, etc.). These will then all be visualized as *continuous* quantities even though, internally, ASPECT considers them as discontinuous fields.
 :::
 
@@ -1226,7 +1227,7 @@ Physical units: \si{\per\second}.
 
 **Pattern:** [Bool]
 
-**Documentation:** deal.II offers the possibility to write vtu files with higher order representations of the output data. This means each cell will correctly show the higher order representation of the output data instead of the linear interpolation between vertices that ParaView and VisIt usually show. Note that activating this option is safe and recommended, but requires that (i) “Output format” is set to “vtu”, (ii) “Interpolate output” is set to true, (iii) you use a sufficiently new version of Paraview or VisIt to read the files (Paraview version 5.5 or newer, and VisIt version to be determined), and (iv) you use deal.II version 9.1.0 or newer.
+**Documentation:** deal.II offers the possibility to write vtu files with higher order representations of the output data. This means each cell will correctly show the higher order representation of the output data instead of the linear interpolation between vertices that ParaView and VisIt usually show. Note that activating this option is safe and recommended, but requires that (i) “Output format” is set to “vtu”, (ii) “Interpolate output” is set to true, and (iii) you use a sufficiently new version of Paraview or VisIt to read the files (Paraview version 5.5 or newer, and VisIt version to be determined).
 The effect of using this option can be seen in the following picture:
 
 \begin{center}  \includegraphics[width=0.5\textwidth]{viz/parameters/higher-order-output}\end{center}The top figure shows the plain output without interpolation or higher order output. The middle figure shows output that was interpolated as discussed for the “Interpolate output” option. The bottom panel shows higher order output that achieves better accuracy than the interpolated output at a lower memory cost.