improved documentation and show functions

supported by gitlab copilot

Author: chmerdon

docs/src/coefficients.md

@@ -1,9 +1,19 @@
 # Stochastic Coefficients
 
-Coefficients are assumed to be represented by a Karhunen-Loeve expansion (KLE)
-that have the following general structure and API.
+Stochastic coefficients play a central role in uncertainty quantification and stochastic finite element methods. In this package, coefficients are represented using a Karhunen-Loève expansion (KLE), which allows for the efficient representation of random fields with prescribed covariance structure.
+
+## Overview
+
+The Karhunen-Loève expansion expresses a stochastic process as a series of orthogonal functions weighted by uncorrelated random variables:
+
+$$
+    a(x, \omega) = a_0(x) + \sum_{n=1}^N \sqrt{\lambda_n} \phi_n(x) \xi_n(\omega)
+$$
+
+where $a_0(x)$ is the mean, $\lambda_n$ and $\phi_n(x)$ are the eigenvalues and eigenfunctions of the covariance operator, and $\xi_n$ are independent standard normal random variables.
 
 ## API
+
 ```@autodocs
 Modules = [ExtendableASGFEM]
 Pages = ["coefficients/coefficients.jl"]

docs/src/estimators.md

@@ -1,14 +1,9 @@
 # Adaptivity and error control
 
 ## Residual-based a posteriori error estimation
-Spatial error estimation refers to classical residual-based error estimation
-for the zero-th multi index that refers to the mean value.
-Stochastic error control has to estimate which stochastic mode needs to be refined
-in the sense that either the polynomial degree is increased or neighbouring
-stochastic modes are activated. Both is represented by the multi-indices.
-Then unified error control allows to perform residual-based error estimation for
-the subresiduals that are associated to each multi-index and depend on the model
-problem (see references on the main page for details).
+Spatial error estimation refers to classical residual-based error estimation for the zero-th multi-index, which corresponds to the mean value.
+Stochastic error control determines which stochastic mode should be refined, either by increasing the polynomial degree or by activating neighboring stochastic modes. Both are represented by multi-indices.
+Unified error control enables residual-based error estimation for the subresiduals associated with each multi-index, depending on the model problem (see references on the main page for details).
 
 
 ```@autodocs
@@ -17,12 +12,10 @@ Pages = ["estimate.jl"]
 Order   = [:type, :function]
 ```
 
-## Multi index management
+## Multi-index management
 
-Depending on the model problem and stochastic coefficient the
-amount of multi indices that should be added to the error estimation
-varies.
-Here are some methods that help with enriching the set of multi-indices.
+Depending on the model problem and stochastic coefficient, the number of multi-indices to be added for error estimation varies.
+The following methods assist in enriching the set of multi-indices.
 
 
 ```@autodocs
@@ -31,12 +24,10 @@ Pages = ["mopcontrol.jl"]
 Order   = [:type, :function]
 ```
 
-## Monte carlo sampling estimator
+## Monte Carlo sampling estimator
+
+A hierarchical Monte Carlo error estimator is also available. It compares the solution with a higher-order discrete solution for sampled deterministic problems. This is mainly intended to compute a reference error to assess the efficiency of the residual-based error estimator.
 
-There is also a hierarchical Monte carlo error estimator available that
-compares the solution with a higher order discrete solution for sampled
-deterministic problems. This is merely intended as a way to compute the
-reference error to assess the efficiency of the residual-based error estimator.
 
 ```@autodocs
 Modules = [ExtendableASGFEM]

docs/src/index.md

@@ -1,26 +1,22 @@
 # ExtendableASGFEM
 
-This package implements the stochastic Galerkin finite element method for certain two dimensional
-model problems involving KLE of stochastic coefficients. The rather huge systems have a tensorized
-structure and are solved by iterative solvers. A posteriori error estimators steer the spatial
-and stochastic refinement.
-
-The spatial discretization is based on the finite element package [ExtendableFEM.jl](https://github.com/WIAS-PDELib/ExtendableFEM.jl)/[ExtendableFEMBase.jl](https://github.com/WIAS-PDELib/ExtendableFEMBase.jl)
+This package provides an implementation of the stochastic Galerkin finite element method (SGFEM) for selected two-dimensional model problems involving Karhunen-Loève expansions (KLE) of stochastic coefficients. The resulting large-scale systems exhibit a tensorized structure and are efficiently solved using iterative solvers. Adaptive a posteriori error estimators guide both spatial and stochastic refinement to ensure accuracy and efficiency.
 
+Spatial discretization is performed using the finite element packages [ExtendableFEM.jl](https://github.com/WIAS-PDELib/ExtendableFEM.jl) and [ExtendableFEMBase.jl](https://github.com/WIAS-PDELib/ExtendableFEMBase.jl).
 
 ## References
 
-- [1]   "Adaptive stochastic Galerkin FEM"\
-        M. Eigel, C.J. Gittelson, C. Schwab, E. Zander\
-        CMAME 270, 1 (2014), 247--269\
-        [>Journal-Link<](https://www.doi.org/10.1016/J.CMA.2013.11.015)
-        [>Preprint-Link<](https://www.research-collection.ethz.ch/handle/20.500.11850/154941)
-- [2]   "A posteriori error control for stochastic Galerkin FEM with high-dimensional random parametric PDEs",\
-        M. Eigel, C. Merdon\
-        to be published in: Error Control, Adaptive Discretizations, and Applications, Part 3, Academic Press\
-        [>Preprint-Link<](https://www.wias-berlin.de/publications/wias-publ/run.jsp?template=abstract&type=Preprint&year=&number=3174)
-- [3]   "Local equilibration error estimators for guaranteed error control in adaptive higher-order stochastic  Galerkin finite element methods"\
-        M. Eigel and C. Merdon\
-        SIAM/ASA J. Uncertainty Quantification 4(1) (2016), 1372--1397"\
-        [>Journal-Link<](https://epubs.siam.org/doi/10.1137/15M102188X)
-        [>Preprint-Link<](http://www.wias-berlin.de/publications/wias-publ/run.jsp?template=abstract&type=Preprint&year=2014&number=1997)
+- [1]   "Adaptive stochastic Galerkin FEM"  
+        M. Eigel, C.J. Gittelson, C. Schwab, E. Zander  
+        CMAME 270, 1 (2014), 247–269  
+        [Journal-Link](https://www.doi.org/10.1016/J.CMA.2013.11.015)  
+        [Preprint-Link](https://www.research-collection.ethz.ch/handle/20.500.11850/154941)
+- [2]   "A posteriori error control for stochastic Galerkin FEM with high-dimensional random parametric PDEs"  
+        M. Eigel, C. Merdon  
+        To appear in: Error Control, Adaptive Discretizations, and Applications, Part 3, Academic Press  
+        [Preprint-Link](https://www.wias-berlin.de/publications/wias-publ/run.jsp?template=abstract&type=Preprint&year=&number=3174)
+- [3]   "Local equilibration error estimators for guaranteed error control in adaptive higher-order stochastic Galerkin finite element methods"  
+        M. Eigel and C. Merdon  
+        SIAM/ASA J. Uncertainty Quantification 4(1) (2016), 1372–1397  
+        [Journal-Link](https://epubs.siam.org/doi/10.1137/15M102188X)  
+        [Preprint-Link](http://www.wias-berlin.de/publications/wias-publ/run.jsp?template=abstract&type=Preprint&year=2014&number=1997)

docs/src/index.pdf

@@ -1,10 +1,6 @@
 # ONBasis
 
-An ONBasis (=orthonormal basis) stores information for the orthogonal polynomials
-of the disctribution, like norms, quadrature rules and cached evaluations at quadrature points.
-It is the main building brick for the tensorized basis associated to the multi-indices
-of the stochastic discretization.
-
+An ONBasis (orthonormal basis) encapsulates information about the orthogonal polynomials associated with a given probability distribution. This includes norms, quadrature rules, and cached evaluations at quadrature points. The ONBasis serves as a fundamental building block for constructing the tensorized basis linked to the multi-indices in the stochastic discretization.
 
 ```@autodocs
 Modules = [ExtendableASGFEM]

docs/src/onbasis.md

@@ -1,41 +1,34 @@
 # Orthogonal Polynomials
 
-The stochastic discretization of random variables involves global
-polynomials that are orthogonal with respect to the involved
-random distribution of the `y_m`. These polynomials
-can be generated by some recurrence relation with coefficients
-that depend on the distribution.
+In the stochastic discretization of random variables, global polynomials that are orthogonal with respect to the probability distribution of each random variable $y_m$ are used. These orthogonal polynomials can be generated via recurrence relations, with coefficients determined by the underlying distribution.
+
+## Recurrence Relations
+Orthogonal polynomials $H_n$ with respect to a weight function $\omega$ satisfy
 
-## Recurrence relations
-Orthogonal polynomials
-$H_n$ with respect to some weight function $\omega$, i.e.,
 ```math
-\int_\Gamma \omega(y) H_{n}(y) H_m(y) dy = N^2_{nm}\delta_{nm}
+\int_\Gamma \omega(y) H_{n}(y) H_m(y) \,dy = N^2_{nm}\delta_{nm}
 ```
-where 
+where
 ```math
-  N_{nn} := \| H_n \|_{\omega}^2 := \int_\Gamma \omega(y) H_{n}(y) H_n(y) dy
+N_{nn} := \| H_n \|_{\omega}^2 := \int_\Gamma \omega(y) H_{n}(y) H_n(y) \,dy
 ```
-satisfy the three-term recurrence relation
+The polynomials satisfy the three-term recurrence relation:
 ```math
 \begin{aligned}
-  H_{n+2}(y) & = (a_n y-b_n) H_{n+1}(y) - c_n H_{n}(y)
-  \end{aligned}
+  H_{n+2}(y) & = (a_n y - b_n) H_{n+1}(y) - c_n H_{n}(y)
+\end{aligned}
 ```
-initialized by $H_0  = 0$ and $H_1 = 1$.
-
+with initial values $H_0 = 0$ and $H_1 = 1$.
 
 ```@autodocs
 Modules = [ExtendableASGFEM]
 Pages = ["orthogonal_polynomials/orthogonal_polynomials.jl"]
 Order   = [:type, :function]
 ```
 
-## Legendre Polynomials (uniform distribution)
+## Legendre Polynomials (Uniform Distribution)
 
-For the weight function $\omega(y) = 1/2$ in the interval $[-1,1]$ (uniform distribution),
-take $a_n = (2n+1)/(n+1)$, $b_n = 0$ and $c_n = n/(n+1)$. The norms
-of the resulting Legendre polynomials are given by
+For the weight function $\omega(y) = 1/2$ on the interval $[-1,1]$ (uniform distribution), the recurrence coefficients are $a_n = (2n+1)/(n+1)$, $b_n = 0$, and $c_n = n/(n+1)$. The norms of the resulting Legendre polynomials are
 ```math
     \| H_n \|^2_\omega = \frac{2}{2n+1}
 ```
@@ -46,21 +39,20 @@ Pages = ["orthogonal_polynomials/Legendre_uniform.jl"]
 Order   = [:type, :function]
 ```
 
+## Hermite Polynomials (Normal Distribution)
 
-## Hermite Polynomials (normal distribution)
-
-For the weight function $\omega(y) = \exp(-y^2/2)/(2\pi)$ (normal distribution), take $a_n = 1$, $b_n = 0$ and $c_n = n$. Then, the first six polynomials read
+For the weight function $\omega(y) = \exp(-y^2/2)/(2\pi)$ (normal distribution), the recurrence coefficients are $a_n = 1$, $b_n = 0$, and $c_n = n$. The first six Hermite polynomials are:
 ```math
 \begin{aligned}
 H_0 & = 0\\
 H_1 & = 1\\
 H_2 & = y\\
 H_3 & = y^2 - 1\\
 H_4 & = y^3 - 3y\\
-H_5 & = y^4 - 6y^2 +3\\
+H_5 & = y^4 - 6y^2 + 3\\
 \end{aligned}
 ```
-and their norms are given by
+Their norms are given by
 ```math
     \| H_n \|^2_\omega = n!
 ```

docs/src/onbasis.pdf

@@ -1,30 +1,21 @@
 # Solver
 
-Solving requires a spatial and stochastic discretization.
-Both are connected in a special vector structure
-that is passed to a solve function that runs a special
-iterative solver for each model problem.
+Solving a problem requires both spatial and stochastic discretization. These are combined into a specialized vector structure, which is then passed to a solver function that executes an iterative algorithm tailored to each model problem.
 
 ## SGFEVector
 
-The spatial discretization is represented by
-s single finite element space from [ExtendableFEM.jl](https://github.com/WIAS-PDELib/ExtendableFEM.jl),
-while the stochastic discretization is represented by a tensorized basis
-for the parameter space of the stochastic coefficient. Both have to be prepared in
-advance.
+The spatial discretization is defined by a single finite element space from [ExtendableFEM.jl](https://github.com/WIAS-PDELib/ExtendableFEM.jl), while the stochastic discretization uses a tensorized basis for the parameter space of the stochastic coefficient. Both components must be set up in advance.
 
 !!! note
-
-    Currently it is not possible to use different finite element spaces for different multi-indices,
-    but this feature might be added in the future.
+    Currently, it is not possible to use different finite element spaces for different multi-indices. This feature may be added in the future.
 
 ```@autodocs
 Modules = [ExtendableASGFEM]
 Pages = ["sgfevector.jl"]
 Order   = [:type, :function]
 ```
 
-## Solve function
+## Solve Function
 
 ```@autodocs
 Modules = [ExtendableASGFEM]

docs/src/orthogonal_polynomials.md

@@ -1,19 +1,8 @@
 # TensorizedBasis
 
-Each multi-index ``\mu = [\mu_1,\mu_2,\ldots,\mu_M]``
-encodes a tensorized basis function for the parameter space
-of the form ``H_\mu = \prod_{k=1}^M H_k`` where the
-``H_k`` are the orthogonal polynomials.
-The TensorizedBasis collects all information necessary
-to evaluate those basis functions, i.e. the set of multi-indices
-and the triple products of the form ``(y_mH_\mu, H_\lambda)``
-for each ``m`` and ``\mu, \lambda`` in the set of multi-indices
-as a sparse matrix. There are analytic formulas to evaluate
-these triple products in terms of recurrence coefficients, but it makes
-sense to store them for faster evaluation times.
-
-
+Each multi-index $\mu = [\mu_1, \mu_2, \ldots, \mu_M]$ defines a tensorized basis function for the parameter space of the form $H_\mu = \prod_{k=1}^M H_k$, where each $H_k$ is an orthogonal polynomial.
 
+The `TensorizedBasis` object collects all information required to evaluate these basis functions, including the set of multi-indices and the triple products of the form $(y_m H_\mu, H_\lambda)$ for each $m$ and $\mu, \lambda$ in the set of multi-indices, stored as a sparse matrix. While analytic formulas exist to compute these triple products using recurrence coefficients, storing them can significantly speed up evaluations.
 
 ```@autodocs
 Modules = [ExtendableASGFEM]