improved doc

Author: chmerdon

docs/src/estimators.md

@@ -1,14 +1,14 @@
-# A posteriori error estimation
+# Adaptivity and error control
 
-## Residual-based error estimation
+## 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
-(see references on the main page for details).
+the subresiduals that are associated to each multi-index and depend on the model
+problem (see references on the main page for details).
 
 
 ```@autodocs

docs/src/estimators.pdf

@@ -1,5 +1,11 @@
 # 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.
+
+
 ```@autodocs
 Modules = [ExtendableASGFEM]
 Pages = ["onbasis.jl"]

docs/src/onbasis.md

@@ -25,6 +25,12 @@ satisfy the three-term recurrence relation
 initialized by $H_0  = 0$ and $H_1 = 1$.
 
 
+```@autodocs
+Modules = [ExtendableASGFEM]
+Pages = ["orthogonal_polynomials/orthogonal_polynomials.jl"]
+Order   = [:type, :function]
+```
+
 ## Legendre Polynomials (uniform distribution)
 
 For the weight function $\omega(y) = 1/2$ in the interval $[-1,1]$ (uniform distribution),
@@ -34,6 +40,13 @@ of the resulting Legendre polynomials are given by
     \| H_n \|^2_\omega = \frac{2}{2n+1}
 ```
 
+```@autodocs
+Modules = [ExtendableASGFEM]
+Pages = ["orthogonal_polynomials/Legendre_uniform.jl"]
+Order   = [:type, :function]
+```
+
+
 ## 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
@@ -51,3 +64,9 @@ and their norms are given by
 ```math
     \| H_n \|^2_\omega = n!
 ```
+
+```@autodocs
+Modules = [ExtendableASGFEM]
+Pages = ["orthogonal_polynomials/Hermite_normal.jl"]
+Order   = [:type, :function]
+```

docs/src/onbasis.pdf

@@ -1,5 +1,17 @@
 # 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 = \pro_{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.
+
+
+
+
 ```@autodocs
 Modules = [ExtendableASGFEM]
 Pages = ["tensorizedbasis.jl"]

docs/src/orthogonal_polynomials.md

@@ -12,13 +12,53 @@ struct ONBasis{T <: Real, OBT <: OrthogonalPolynomialType, npoly, nquad}
     vals4xref::SMatrix{nquad, npoly, T}                           # evaluations of all ONB functions at quadrature points
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+returns the values of all polynomials at the k-th quadrature point
+"""
 vals4qp(ONB::ONBasis, k) = view(ONB.vals4xref, k, :)
+"""
+$(TYPEDSIGNATURES)
+
+returns the values of the p-th polynomial at all quadrature points
+"""
 vals4poly(ONB::ONBasis, p) = view(ONB.vals4xref, :, p + 1)
+"""
+$(TYPEDSIGNATURES)
+
+returns the quadrature weights
+"""
 qw(ONB::ONBasis) = ONB.gauss_rule[2]
+"""
+$(TYPEDSIGNATURES)
+
+returns the quadrature points
+"""
 qp(ONB::ONBasis) = ONB.gauss_rule[1]
+"""
+$(TYPEDSIGNATURES)
+
+returns the values of all polynomials at the quadrature points
+"""
 vals4xref(ONB::ONBasis) = ONB.vals4xref
+"""
+$(TYPEDSIGNATURES)
+
+returns the norm of the p-th polynomial
+"""
 norm4poly(ONB::ONBasis, p) = getindex(ONB.norms, p + 1)
+"""
+$(TYPEDSIGNATURES)
+
+returns the distribution associated to the orthogonal polynomials
+"""
 distribution(ONB::ONBasis{T, OBT}) where {T, OBT} = distribution(OBT)
+"""
+$(TYPEDSIGNATURES)
+
+returns the OrthogonalPolynomialType
+"""
 OrthogonalPolynomialType(ONB::ONBasis{T, OBT}) where {T, OBT} = OBT
 
 

docs/src/orthogonal_polynomials.pdf

@@ -1,23 +1,30 @@
+"""
+$(TYPEDEF)
+
+Type for dispatching Hermite Polynomials
+"""
 abstract type HermitePolynomials <: OrthogonalPolynomialType end
 
+"""
+$(TYPEDSIGNATURES)
 
+Returns the recurrence coefficients for the k-th Legendre polynomial
+"""
 recurrence_coefficients(::Type{HermitePolynomials}, k::Integer) =
     0, 1, k
 
 issymmetric(::Type{HermitePolynomials}) = true
 
-norms(::Type{HermitePolynomials}, k) = sqrt.(factorial.(big(k)))
-
-distribution(::Type{HermitePolynomials}) = Normal(0, 1)
-
+"""
+$(TYPEDSIGNATURES)
 
-# abstract type HermitePolynomialsNormalized <: OrthogonalPolynomialType end
-
-# recurrence_coefficients(::Type{HermitePolynomialsNormalized}, k::Integer) =
-#   0, 1/sqrt(k+2), sqrt((k+1)/(k+2))
-
-# issymmetric(::Type{HermitePolynomialsNormalized}) = true
+Returns the norm of the k-th Hermite polynomial
+"""
+norms(::Type{HermitePolynomials}, k) = sqrt.(factorial.(big(k)))
 
-# norms(::Type{HermitePolynomialsNormalized}, k) = 1
+"""
+$(TYPEDSIGNATURES)
 
-# distribution(::Type{HermitePolynomialsNormalized}) = Normal(0,1)
+Returns the distribution associated to the Hermite polynomial
+"""
+distribution(::Type{HermitePolynomials}) = Normal(0, 1)