better Polynomials docstrings

src/Polynomials/CompWiseTensorPolyBases.jl

@@ -18,7 +18,7 @@ with `L`>1, where the scalar multivariate spaces 𝕊ˡ (for 1 ≤ l ≤ `L`) of
 𝕊ᴸ = ℙα(`L`,1) ⊗ … ⊗ ℙα(`L`,`D`)
 
 The `L`×`D` matrix of orders α is given in the constructor, and `K` is the
-maximum of α. Any 1D polynomial basis `PT` is usable.
+maximum of α. Any 1D polynomial family `PT<:Polynomial` is usable.
 """
 struct CompWiseTensorPolyBasis{D,V,K,PT,L} <: PolynomialBasis{D,V,K,PT}
   orders::SMatrix{L,D,Int}
@@ -40,11 +40,11 @@ end
 Base.size(a::CompWiseTensorPolyBasis) = ( sum(prod.(eachrow(a.orders .+ 1))), )
 
 """
-    get_comp_terms(f::CompWiseTensorPolyBasis)
+    get_comp_terms(f::CompWiseTensorPolyBasis{D,V})
 
-Return a `NTuple{L,CartesianIndices{D}}` containing, for each component
-1 ≤ l ≤ `L`, the Cartesian indices iterator over the terms
-in ⟦1,`o`(l,1)+1⟧ × ⟦1,`o`(l,2)+1⟧ × … × ⟦1,`o`(l,D)+1⟧ that define 𝕊ˡ.
+Return a tuple (terms\\_1, ..., terms\\_l, ..., terms\\_L) containing, for each
+component of V, the Cartesian indices iterator over the terms that define 𝕊ˡ,
+that is all elements of ⟦1,`o`(l,1)+1⟧ × ⟦1,`o`(l,2)+1⟧ × … × ⟦1,`o`(l,D)+1⟧.
 
 E.g., if `orders=[ 0 1; 1 0]`, then the `comp_terms` are
 `( CartesianIndices{2}((1,2)), CartesianIndices{2}((2,1)) )`.
@@ -149,7 +149,7 @@ function _gradient_nd!(
 end
 
 """
-    _uniform_set_derivative!(r::AbstractMatrix{G},i,s,k,::Type{V})
+    _comp_wize_set_derivative!(r::AbstractMatrix{G},i,s,k,::Type{<:Real})
 
 ```
 r[i,k]     = G(s…) = (Dbᵏ)(xi)
@@ -165,7 +165,7 @@ function _comp_wize_set_derivative!(
 end
 
 """
-    _uniform_set_derivative!(r::AbstractMatrix{G},i,s,k,::Type{V})
+    _comp_wize_set_derivative!(r::AbstractMatrix{G},i,s,k,::Type{V})
 
 ```
 z = zero(s)
@@ -262,7 +262,7 @@ polynomial space for Nedelec elements on `D`-dimensional cubes with scalar type
 The `order`=n argument has the following meaning: the curl of the  functions in
 this basis is in ℚₙ.
 
-`PT<:Polynomial` is the choice of scalar 1D polynomial basis.
+`PT<:Polynomial` is the choice of the family of the scalar 1D basis polynomials.
 
 # Example:
 
@@ -300,13 +300,17 @@ end
 """
     QCurlGradBasis(::Type{PT}, ::Val{D}, ::Type{T}, order::Int) :: PolynomialBasis
 
-Return a basis of ℝ𝕋ᴰₙ(□) = (ℚₙ)ᴰ ⊕ x (ℚₙ \\ ℚₙ₋₁) with n=`order`, the polynomial
-space for Raviart-Thomas elements on `D`-dimensional cubes with scalar type `T`.
+Return a basis of
+
+ℝ𝕋ᴰₙ(□) = (ℚₙ)ᴰ ⊕ x (ℚₙ \\ ℚₙ₋₁)
+
+with n=`order`, the polynomial space for Raviart-Thomas elements on
+`D`-dimensional cubes with scalar type `T`.
 
 The `order`=n argument has the following meaning: the divergence of the functions
 in this basis is in ℚₙ.
 
-`PT<:Polynomial` is the choice of scalar 1D polynomial basis.
+`PT<:Polynomial` is the choice of the family of the scalar 1D basis polynomials.
 
 # Example:
 
@@ -315,8 +319,8 @@ in this basis is in ℚₙ.
 b = QCurlGradBasis(Bernstein, Val(2), Float64, 3)
 ```
 
-For more details, see [`CompWiseTensorPolyBasis`](@ref), as `QCurlGradBasis` returns
-an instance of\\
+For more details, see [`CompWiseTensorPolyBasis`](@ref), as `QCurlGradBasis`
+returns an instance of\\
 `CompWiseTensorPolyBasis{D, VectorValue{D,T}, order+1, PT}` for `D`>1, or\\
 `UniformPolyBasis{1, VectorValue{1,T}, order+1, PT}` for `D`=1.
 """

src/Polynomials/ModalC0Bases.jl

@@ -1,7 +1,7 @@
 """
     ModalC0 <: Polynomial
 
-Type representing ModalC0 polynomial.
+Type representing ModalC0 polynomials.
 
 Reference: Eq. (17) in https://doi.org/10.1016/j.camwa.2022.09.027
 """
@@ -91,9 +91,6 @@ end
 
 @inline Base.size(a::ModalC0Basis{D,V}) where {D,V} = (length(a.terms)*num_indep_components(V),)
 
-"""
-    get_orders(b::ModalC0Basis)
-"""
 function get_orders(b::ModalC0Basis)
   b.orders
 end

src/Polynomials/NedelecPolyBases.jl

@@ -237,8 +237,12 @@ end
 """
     PGradBasis(::Type{Monomial}, ::Val{D}, ::Type{T}, order::Int) :: PolynomialBasis
 
-Return a basis of ℕ𝔻ᴰₙ(△) = (ℙₙ)ᴰ ⊕ x × (ℙₙ \\ ℙₙ₋₁)ᴰ with n=`order`, the polynomial
-space for Nedelec elements on `D`-dimensional simplices with scalar type `T`.
+Return a basis of
+
+ℕ𝔻ᴰₙ(△) = (ℙₙ)ᴰ ⊕ x × (ℙₙ \\ ℙₙ₋₁)ᴰ
+
+with n=`order`, the polynomial space for Nedelec elements on `D`-dimensional
+simplices with scalar type `T`.
 
 The `order`=n argument has the following meaning: the curl of the  functions in
 this basis is in ℙₙ.

src/Polynomials/PolynomialInterfaces.jl

@@ -15,11 +15,11 @@ hierarchical.
 abstract type Polynomial  <: Field end
 
 """
-    isHierarchical(::Type{Polynomial})
+    isHierarchical(::Type{Polynomial})::Bool
 
-Return true if the 1D basis of order `K` of the given [`Polynomial`](@ref) type
-is the union of the basis of order `K-1` and an other order `K` polynomial.
-Equivalently, if the iᵗʰ basis polynomial is of order i-1.
+Return `true` if the 1D basis of order `K` of the given [`Polynomial`](@ref)
+basis family is the union of the basis of order `K-1` and an other order `K`
+polynomial. Equivalently, if the iᵗʰ basis polynomial is of order i-1.
 """
 isHierarchical(::Type{Polynomial}) = @abstractmethod
 
@@ -49,9 +49,9 @@ isHierarchical(::Type{Polynomial}) = @abstractmethod
 Abstract type representing a generic multivariate polynomial basis.
 The parameters are:
 - `D`: the spatial dimension
-- `V`: the image values type, of type `<:Real` or `<:MultiValue`
+- `V`: the image values type, a concrete type `<:Real` or `<:MultiValue`
 - `K`: the maximum order of a basis polynomial in a spatial component
-- `PT <: Polynomial`: the polynomial family (must be a concrete type).
+- `PT <: Polynomial`: the family of the basis polynomials (must be a concrete type).
 """
 abstract type PolynomialBasis{D,V,K,PT<:Polynomial} <: AbstractVector{PT}  end
 
@@ -191,7 +191,7 @@ Compute and assign: `r`[`i`] = ∇`b`(`xi`) = (∇`b`₁(`xi`), ..., ∇`b`ₙ(`
 where n = length(`b`) (cardinal of the basis), like [`_evaluate_nd!`](@ref) but
 for gradients of `b`ₖ(`xi`), and
 
-- `g` is a mutable `D`×`K` cache (for 1D poly deriv evals).
+- `g` is a mutable `D`×`K` cache (for the 1D polynomials first derivatives).
 - `s` is a mutable length `D` cache for ∇`b`ₖ(`xi`).
 """
 function _gradient_nd!(
@@ -213,7 +213,7 @@ Compute and assign: `r`[`i`] = H`b`(`xi`) = (H`b`₁(`xi`), ..., H`b`ₙ(`xi`))
 where n = length(`b`) (cardinal of the basis), like [`_evaluate_nd!`](@ref) but
 for hessian matrices/tensor of `b`ₖ(`xi`), and
 
-- `h` is a mutable `D`×`K` cache (for 1D poly second deriv evals).
+- `h` is a mutable `D`×`K` cache (for the 1D polynomials second derivatives).
 - `s` is a mutable `D`×`D` cache for H`b`ₖ(`xi`).
 """
 function _hessian_nd!(
@@ -282,11 +282,11 @@ end
 """
     _evaluate_1d!(PT::Type{<:Polynomial},::Val{K},c,x,d)
 
-Evaluates in place the 1D basis polynomials of the given type at one nD point `x`
-along the given coordinate 1 ≤ `d` ≤ nD.
+Evaluates in place the 1D basis polynomials of the family `PT` at one D-dim.
+point `x` along the given coordinate 1 ≤ `d` ≤ D.
 
-`c` is an AbstractMatrix of size (at least) `d`×(`K`+1), such that the 1 ≤ i ≤ `k`+1
-values are stored in `c[d,i]`.
+`c` is an AbstractMatrix of size (at least) `d`×(`K`+1), such that the
+1 ≤ i ≤ `k`+1 values are stored in `c[d,i]`.
 """
 function _evaluate_1d!(::Type{<:Polynomial},::Val{K},c::AbstractMatrix{T},x,d) where {K,T<:Number}
   @abstractmethod
@@ -295,7 +295,8 @@ end
 """
     _gradient_1d!(PT::Type{<:Polynomial},::Val{K},g,x,d)
 
-Like [`_evaluate_1d!`](@ref), but computes the first derivative of the basis functions.
+Like [`_evaluate_1d!`](@ref), but computes the first derivative of the basis
+polynomials.
 """
 function _gradient_1d!(::Type{<:Polynomial},::Val{K},g::AbstractMatrix{T},x,d) where {K,T<:Number}
   @abstractmethod
@@ -304,7 +305,8 @@ end
 """
     _hessian_1d!(PT::Type{<:Polynomial},::Val{K},g,x,d)
 
-Like [`_evaluate_1d!`](@ref), but computes the second derivative of the basis functions.
+Like [`_evaluate_1d!`](@ref), but computes the second derivative of the basis
+polynomials.
 """
 function _hessian_1d!(::Type{<:Polynomial},::Val{K},h::AbstractMatrix{T},x,d) where {K,T<:Number}
   @abstractmethod

src/Polynomials/RaviartThomasPolyBases.jl

@@ -1,21 +1,22 @@
 """
     RaviartThomasPolyBasis{D,V,K,PT} <: PolynomialBasis{D,V,K,PT}
 
-Basis of ℝ𝕋ᴰₙ = (𝕊ₙ)ᴰ ⊕ x (𝕊ₙ\\𝕊₍ₙ₋₁₎)
+Basis of the vector valued (`V<:VectorValue{D}`) space
+
+ℝ𝕋ᴰₙ = (𝕊ₙ)ᴰ ⊕ x (𝕊ₙ\\𝕊₍ₙ₋₁₎)
+
 where 𝕊ₙ is a multivariate scalar polynomial space of maximum degree n = `K`-1.
 
 This ℝ𝕋ᴰₙ is the polynomial space for Raviart-Thomas elements with divergence in 𝕊ₙ.
 Its maximum degree is n+1 = `K`. `get_order` on it returns `K`.
 
-The multivariate scalar space 𝕊ₙ, typically ℙₙ, doesn't need to have a tensor
-product structure of 1D scalar spaces. Thus, the ℝ𝕋ᴰₙ component's scalar spaces
-are not tensor products either.
-
-𝕊ₙ must admit a basis computable using products of 1D polynomials of the `PT`
-type, `PT` thus needs to be hierarchical, see [`isHierarchical`](@ref).
+The multivariate scalar space 𝕊ₙ, typically ℙₙ or ℚₙ, does not need to have a
+tensor product structure of 1D scalar spaces. Thus, the ℝ𝕋ᴰₙ component's scalar
+spaces are not tensor products either.
 
-Indeed, 𝕊ₙ is defined like a scalar valued [`UniformPolyBasis`](@ref) via
-the `_filter` argument of the constructor, by default [`_p_filter`](@ref).
+𝕊ₙ is defined like a scalar valued [`UniformPolyBasis`](@ref) via the `_filter`
+argument of the constructor, by default [`_p_filter`](@ref) for ℙₙ.
+As a consequence, `PT` must be hierarchical, see [`isHierarchical`](@ref).
 """
 struct RaviartThomasPolyBasis{D,V,K,PT} <: PolynomialBasis{D,V,K,PT}
   pterms::Vector{CartesianIndex{D}}
@@ -190,14 +191,18 @@ end
 """
     PCurlGradBasis(::Type{PT}, ::Val{D}, ::Type{T}, order::Int) :: PolynomialBasis
 
-Return a basis of ℝ𝕋ᴰₙ(△) = (ℙₙ)ᴰ ⊕ x (ℙₙ \\ ℙₙ₋₁) with n=`order`, the polynomial
-space for Raviart-Thomas elements on `D`-dimensional simplices with scalar type `T`.
+Return a basis of
+
+ℝ𝕋ᴰₙ(△) = (ℙₙ)ᴰ ⊕ x (ℙₙ \\ ℙₙ₋₁)
+
+with n=`order`, the polynomial space for Raviart-Thomas elements on
+`D`-dimensional simplices with scalar type `T`.
 
 The `order`=n argument of this function has the following meaning: the divergence
 of the functions in this basis is in ℙₙ.
 
-`PT<:Polynomial` is the choice of scalar 1D polynomial basis, it must be
-hierarchichal, see [`isHierarchichal`](@ref).
+`PT<:Polynomial` is the choice of the family of the scalar 1D basis polynomials,
+it must be hierarchichal, see [`isHierarchichal`](@ref).
 
 # Example:
 
@@ -208,8 +213,8 @@ b = PCurlGradBasis(Monomial, Val(3), Float64, 2)
 
 For more details, see [`RaviartThomasPolyBasis`](@ref), as `PCurlGradBasis` returns
 an instance of\\
-`RaviartThomasPolyBasis{D,VectorValue{D,T},order+1,PT}`  for `D`=2,3, or\\
-`UniformPolyBasis{1,VectorValue{1,T},order+1,PT}` for `D`=1.
+`RaviartThomasPolyBasis{D, VectorValue{D,T}, order+1, PT}`  for `D`>1, or\\
+`UniformPolyBasis{1, VectorValue{1,T}, order+1, PT}` for `D`=1.
 """
 function PCurlGradBasis(::Type{PT},::Val{D},::Type{T},order::Int) where {PT,D,T}
   RaviartThomasPolyBasis{D}(PT, T, order)

src/Polynomials/UniformPolyBases.jl

@@ -6,8 +6,12 @@
     struct UniformPolyBasis{D,V,K,PT} <: PolynomialBasis{D,V,K,PT}
 
 Type representing a uniform basis of (an)isotropic `D`-multivariate `V`-valued
-polynomial space `V`(𝕊, 𝕊, ..., 𝕊), where 𝕊 is a scalar polynomial space. So each
-independant component of `V` holds the same space, which is here called 'uniform'.
+polynomial space
+
+`V`(𝕊, 𝕊, ..., 𝕊)
+
+where 𝕊 is a scalar polynomial space. So each (independant) component of `V`
+holds the same space, which is here called 'uniform'.
 
 The scalar polynomial basis spanning 𝕊 is defined as
 
@@ -52,11 +56,11 @@ function UniformPolyBasis(
 end
 
 """
-    UniformPolyBasis(::Type{PT}, ::Val{D}, ::Type{V}, orders::Tuple [, filter::Function])
+    UniformPolyBasis(::Type{PT}, ::Val{D}, ::Type{V}, orders::Tuple [, filter=_q_filter])
 
-This version of the constructor allows to pass a tuple `orders` containing the
-polynomial order to be used in each of the `D` dimensions in order to construct
-a tensorial anisotropic multivariate space 𝕊.
+This constructor allows to pass a tuple `orders` containing the polynomial order
+to be used in each of the `D` spatial dimensions in order to construct a
+tensorial anisotropic multivariate space 𝕊.
 """
 function UniformPolyBasis(
   ::Type{PT}, ::Val{D}, ::Type{V}, orders::NTuple{D,Int}, filter::Function=_q_filter
@@ -67,29 +71,25 @@ function UniformPolyBasis(
 end
 
 """
-    UniformPolyBasis(::Type{V}, ::Val{D}, order::Int [, filter::Function]) where {D,V}
+    UniformPolyBasis(::Type{PT}, ::Type{V}, ::Val{D}, order::Int [, filter=_q_filter]) where {D,V}
 
-Returns an instance of `UniformPolyBasis` representing a multivariate polynomial
-basis in `D` dimensions, of polynomial degree `order`, whose value is represented
-by the type `V`. The type `V` is typically `<:Number`, e.g., `Float64` for
-scalar-valued functions and `VectorValue{D,Float64}` for vector-valued ones.
+Returns an instance of `UniformPolyBasis{D,V,order,PT}`.
 
 # Filter function
 
 The `filter` function is used to select which terms of the tensor product space
-of order `order` in `D` dimensions are to be used. If the filter is not provided,
-the full tensor-product space is used by default leading to a multivariate
-polynomial space of type ℚ. The signature of the filter function is
+of order `order` in `D` spatial dimensions are to be used. If the filter is not
+provided, the full tensor-product space is used by default leading to a
+multivariate polynomial space of type ℚ. The signature of the filter function is
 
     (e,order) -> Bool
 
 where `e` is a tuple of `D` integers containing the exponents of a multivariate
 monomial. The following filters are used to select well known polynomial spaces
 
-- ℚ space: `(e,order) -> maximum(e) <= order`
-- ℙ space: `(e,order) -> sum(e) <= order`
+- ℚ space: `_p_filter = (e,order) -> maximum(e) <= order`
+- ℙ space: `_q_filter = (e,order) -> sum(e) <= order`
 - "Serendipity" space: `(e,order) -> sum( [ i for i in e if i>1 ] ) <= order`
-
 """
 function UniformPolyBasis(
   ::Type{PT}, VD::Val{D}, ::Type{V}, order::Int, filter::Function=_q_filter) where {PT,D,V}
@@ -128,7 +128,7 @@ end
 """
     get_orders(b::UniformPolyBasis)
 
-Return the D-tuple of polynomial orders in each dimension
+Return the D-tuple of polynomial orders in each spatial dimension
 """
 function get_orders(b::UniformPolyBasis)
   b.orders