Merge pull request #6198 from gassmoeller/fix_documentation_tex

Fix latex errors in documentation

.readthedocs.yaml

@@ -18,8 +18,7 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF and ePub
 formats:
   - htmlzip
-# TODO: reenable once the pdf errors are fixed
-#  - pdf
+  - pdf
 
 conda:
   environment: ./doc/sphinx/environment.yml

contrib/utilities/jsontomarkdown.py

@@ -106,7 +106,7 @@ def escape_doc_string(text) :
 
     # Finally escape some characters that have special meaning in markdown:
     tmp = re.sub(r'\[(.*)\]\(',
-                 r'\[\1\](',
+                 r'{\1}(',
                  tmp)
 
     return tmp;

doc/sphinx/conf.py

@@ -89,6 +89,18 @@
     "primary_sidebar_end": "navbar_end.html"
 }
 
+latex_engine = 'xelatex'
+latex_elements = {
+# Additional stuff for the LaTeX preamble.
+'preamble': r'''
+% to allow for the degree symbol
+\usepackage{gensymb}
+\usepackage{siunitx}
+\usepackage{etoolbox}
+\pretocmd{\hyperlink}{\protect}{}{}
+'''
+}
+
 bibtex_bibfiles = ["references.bib"]
 bibtex_default_style = "alpha"
 bibtex_reference_style = "author_year"

doc/sphinx/environment.yml

@@ -6,6 +6,7 @@ dependencies:
   - myst-parser
   - sphinx-book-theme
   - sphinxcontrib-bibtex
+  - cairosvg
   - pip>=20.1
   - pip:
     - sphinxcontrib-tikz

doc/sphinx/parameters/Geometry_20model.md

@@ -33,7 +33,7 @@ The dimensions of the model are specified by parameters of the following form: C
 
 When used in 2d, this geometry does not imply the use of a spherical coordinate system. Indeed, in 2d the geometry is simply a sector of an annulus in a Cartesian coordinate system and consequently would correspond to a sector of a cross section of the fluid filled space between two infinite cylinders where one has made the assumption that the velocity in direction of the cylinder axes is zero. This is consistent with the definition of what we consider the two-dimension case given in {ref}`sec:methods:2d-models`. It is also possible to add initial topography to the chunk geometry, based on an ascii data file.
 
-‘ellipsoidal chunk’: A 3d chunk geometry that accounts for Earth’s ellipticity (default assuming the WGS84 ellipsoid definition) which can be defined in non-coordinate directions. In the description of the ellipsoidal chunk, two of the ellipsoidal axes have the same length so that there is only a semi-major axis and a semi-minor axis. The user has two options for creating an ellipsoidal chunk geometry: 1) by defining two opposing points (SW and NE or NW and SE) a coordinate parallel ellipsoidal chunk geometry will be created. 2) by defining three points a non-coordinate parallel ellipsoidal chunk will be created. The points are defined in the input file by longitude:latitude. It is also possible to define additional subdivisions of the mesh in each direction. The boundary of the domain is formed by linear interpolation in longitude-latitude space between adjacent points (i.e. $\[lon, lat\](f) = [lon1 \cdot f + lon2 \cdot(1-f), lat1 \cdot f + lat2 \cdot (1-f)]$, where f is a value between 0 and 1). Faces of the model are defined as 0, west; 1,east; 2, south; 3, north; 4, inner; 5, outer.
+‘ellipsoidal chunk’: A 3d chunk geometry that accounts for Earth’s ellipticity (default assuming the WGS84 ellipsoid definition) which can be defined in non-coordinate directions. In the description of the ellipsoidal chunk, two of the ellipsoidal axes have the same length so that there is only a semi-major axis and a semi-minor axis. The user has two options for creating an ellipsoidal chunk geometry: 1) by defining two opposing points (SW and NE or NW and SE) a coordinate parallel ellipsoidal chunk geometry will be created. 2) by defining three points a non-coordinate parallel ellipsoidal chunk will be created. The points are defined in the input file by longitude:latitude. It is also possible to define additional subdivisions of the mesh in each direction. The boundary of the domain is formed by linear interpolation in longitude-latitude space between adjacent points (i.e. ${lon, lat}(f) = [lon1 \cdot f + lon2 \cdot(1-f), lat1 \cdot f + lat2 \cdot (1-f)]$, where f is a value between 0 and 1). Faces of the model are defined as 0, west; 1,east; 2, south; 3, north; 4, inner; 5, outer.
 
 This geometry model supports initial topography for deforming the initial mesh.
 

doc/sphinx/parameters/Material_20model.md

@@ -2682,7 +2682,7 @@ Also note that the melting time scale has to be larger than or equal to the reac
 
 **Pattern:** [Double 0...MAX_DOUBLE (inclusive)]
 
-**Documentation:** The value of the constant melt viscosity $\viscosity_fluid$. Units: \si{\pascal\second}.
+**Documentation:** The value of the constant melt viscosity $\eta_f$. Units: \si{\pascal\second}.
 
 (parameters:Material_20model/Melt_20simple/Reference_20permeability)=
 ### __Parameter name:__ Reference permeability
@@ -3542,7 +3542,7 @@ Also note that the melting time scale has to be larger than or equal to the reac
 
 **Pattern:** [Double 0...MAX_DOUBLE (inclusive)]
 
-**Documentation:** The value of the constant melt viscosity $\viscosity_fluid$. Units: \si{\pascal\second}.
+**Documentation:** The value of the constant melt viscosity $\eta_f$. Units: \si{\pascal\second}.
 
 (parameters:Material_20model/Reactive_20Fluid_20Transport_20Model/Katz_202003_20model/Reference_20permeability)=
 ### __Parameter name:__ Reference permeability
@@ -4150,6 +4150,14 @@ Note that melt does not freeze unless the ’Freezing rate’ parameter
 
 **Documentation:** List of the Stress thresholds below which the strain rate is solved for as a quadratic function of stress to aid with convergence when stress exponent n=0. Units: \si{\pascal}
 
+(parameters:Material_20model/Visco_20Plastic/Data_20directory)=
+### __Parameter name:__ Data directory
+**Default value:** $ASPECT_SOURCE_DIR/data/material-model/entropy-table/pyrtable
+
+**Pattern:** [DirectoryName]
+
+**Documentation:** The path to the model data. The path may also include the special text ’$ASPECT_SOURCE_DIR’ which will be interpreted as the path in which the ASPECT source files were located when ASPECT was compiled. This interpretation allows, for example, to reference files located in the ‘data/’ subdirectory of ASPECT.
+
 (parameters:Material_20model/Visco_20Plastic/Define_20thermal_20conductivities)=
 ### __Parameter name:__ Define thermal conductivities
 **Default value:** false
@@ -4308,6 +4316,14 @@ Note that melt does not freeze unless the ’Freezing rate’ parameter
 
 **Documentation:** List of lower temperature for onset of strain weakening for background material and compositional fields, for a total of N+1 values, where N is the number of all compositional fields or only those corresponding to chemical compositions. If only one value is given, then all use the same value. Units: \si{\kelvin}.
 
+(parameters:Material_20model/Visco_20Plastic/Material_20file_20names)=
+### __Parameter name:__ Material file names
+**Default value:** material_table_temperature_pressure_small.txt
+
+**Pattern:** [List of <[Anything]> of length 0...4294967295 (inclusive)]
+
+**Documentation:** The file names of the material data (material data is assumed to be in order with the ordering of the compositional fields). Note that there are two options on how many files need to be listed here: 1. If only one file is provided, it is used for the whole model domain, and compositional fields are ignored. 2. If there is one more file name than the number of compositional fields, then the first file is assumed to define a &lsquo;background composition&rsquo; that is modified by the compositional fields. These data files need to have the same structure as the one necessary for equation of state plus a new column for the phase indexes, which amounts to 8 columns in total.
+
 (parameters:Material_20model/Visco_20Plastic/Maximum_20Peierls_20strain_20rate_20iterations)=
 ### __Parameter name:__ Maximum Peierls strain rate iterations
 **Default value:** 40
@@ -4420,6 +4436,14 @@ Note that melt does not freeze unless the &rsquo;Freezing rate&rsquo; parameter
 
 **Documentation:** A list of depths where phase transitions occur. Values must monotonically increase. Units: \si{\meter}.
 
+(parameters:Material_20model/Visco_20Plastic/Phase_20transition_20indicators)=
+### __Parameter name:__ Phase transition indicators
+**Default value:**
+
+**Pattern:** [Anything]
+
+**Documentation:** A list of phase indicators in a look-up table for each phase transition. This parameter selectively assign different rheologies to specific phases, rather than having a unique rheology for each phase in the table. For example, if the table has phases 0, 1, and 2, and one only want a distinct rheology for phase 2, then only phase 2 is needed in the list of indicator. And phases 0, 1 will just be assigned the rheology of the base phase.
+
 (parameters:Material_20model/Visco_20Plastic/Phase_20transition_20pressure_20widths)=
 ### __Parameter name:__ Phase transition pressure widths
 **Default value:**
@@ -4728,6 +4752,14 @@ If a compositional field named &rsquo;noninitial\_plastic\_strain&rsquo; is incl
 
 **Documentation:** Whether to use the adiabatic pressure instead of the full pressure when calculating plastic yield stress. This may be helpful in models where the full pressure has unusually large variations, resulting in solver convergence issues. Be aware that this setting will change the plastic shear band angle.
 
+(parameters:Material_20model/Visco_20Plastic/Use_20dominant_20phase_20for_20viscosity)=
+### __Parameter name:__ Use dominant phase for viscosity
+**Default value:** false
+
+**Pattern:** [Bool]
+
+**Documentation:** Whether to look up the dominant phase for each composition in its respective material data file to calculate viscosity. This allows each phase to have distinct rheological parameterizations.
+
 (parameters:Material_20model/Visco_20Plastic/Use_20fixed_20elastic_20time_20step)=
 ### __Parameter name:__ Use fixed elastic time step
 **Default value:** unspecified

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.

source/material_model/reaction_model/katz2003_mantle_melting.cc

@@ -470,7 +470,7 @@ namespace aspect
                            "dependencies. Units: \\si{\\pascal\\second}.");
         prm.declare_entry ("Reference melt viscosity", "10.",
                            Patterns::Double (0.),
-                           "The value of the constant melt viscosity $\\viscosity_fluid$. Units: \\si{\\pascal\\second}.");
+                           "The value of the constant melt viscosity $\\eta_f$. Units: \\si{\\pascal\\second}.");
         prm.declare_entry ("Exponential melt weakening factor", "27.",
                            Patterns::Double (0.),
                            "The porosity dependence of the viscosity. Units: dimensionless.");