UTF8 Documentation rework (#104)

* update documentation to use more utf8, especially in math.
* update documentation, where this might not be that useful.
* Adds a notation page.


This closes #101 .

CONTRIBUTING.md

@@ -52,7 +52,7 @@ This can best be achieved by adding a docstring to the method with a general sig
 ````julia
     struct MyManifold <: Manifold end
 
-    @doc doc"""
+    @doc raw"""
         exp(M::MyManifold, x, v)
 
     Describe the function.

docs/make.jl

@@ -4,7 +4,8 @@ makedocs(
     # for development, we disable prettyurls
     format = Documenter.HTML(prettyurls = false),
     modules = [Manifolds, ManifoldsBase],
-    sitename = "Manifolds",
+    authors = "Seth Axen, Mateusz Baran, Ronny Bergmann, and contributors.",
+    sitename = "Manifolds.jl",
     pages = [
         "Home" => "index.md",
         "ManifoldsBase.jl" => "interface.md",
@@ -38,6 +39,7 @@ makedocs(
         "Statistics" => "statistics.md",
         "Distributions" => "distributions.md",
         "Orthonormal bases" => "orthonormal_bases.md",
+        "Notation" => "notation.md",
         "Library" => [
             "Number systems" => "lib/numbers.md",
             "Public" => "lib/public.md",

docs/src/interface.md

@@ -36,6 +36,7 @@ Allocation of new points is performed using a custom mechanism that relies on th
   For more complex types, such as nested representations of [`PowerManifold`](@ref) (see [`NestedPowerRepresentation`](@ref)), [`FVector`](@ref) types, checked types like [`ArrayMPoint`](@ref) and more it operates differently.
   While `similar` only concerns itself with the higher level of nested structures, `allocate` maps itself through all levels of nesting until a simple array of numbers is reached and then calls `similar`.
   The difference can be most easily seen in the following example:
+
 ```julia
 julia> x = similar([[1.0], [2.0]])
 2-element Array{Array{Float64,1},1}:
@@ -56,6 +57,8 @@ Stacktrace:
 julia> y[1]
 1-element Array{Float64,1}:
  6.90031725726027e-310
+
 ```
+
 * [`allocate_result`](@ref) allocates a result of a particular function (for example [`exp`], [`flat`], etc.) on a particular manifold with particular arguments.
   It takes into account the possibility that different arguments may have different numeric [`number_eltype`](@ref) types thorough the [`ManifoldsBase.allocate_result_type`](@ref) function.

docs/src/lib/internals.md

@@ -13,11 +13,9 @@ Manifolds.SizedAbstractArray
 ```@docs
 Manifolds._gradient
 Manifolds._jacobian
-ManifoldsBase.allocate_result_type
 Manifolds.eigen_safe
 Manifolds.find_pv
 Manifolds.log_safe
-ManifoldsBase.number_eltype
 Manifolds.size_to_tuple
 Manifolds.select_from_tuple
 Manifolds.usinc

docs/src/lib/public.md

@@ -3,7 +3,6 @@
 Documentation for `Manifolds.jl`'s public interface.
 
 ```@docs
-allocate
 Manifolds.ShapeSpecification
 submanifold_component
 submanifold_components

docs/src/manifolds/euclidean.md

@@ -1,6 +1,6 @@
 # Euclidean space
 
-The Euclidean space $\mathbb R^n$ is a simple model space, since it has curvature constantly zero everywhere; hence, nearly all operations simplify.
+The Euclidean space $ℝ^n$ is a simple model space, since it has curvature constantly zero everywhere; hence, nearly all operations simplify.
 
 ```@autodocs
 Modules = [Manifolds]

docs/src/manifolds/graph.md

@@ -3,9 +3,10 @@
 For a given graph $G(V,E)$ implemented using [`LightGraphs.jl`](https://juliagraphs.github.io/LightGraphs.jl/latest/), the [`GraphManifold`](@ref) models a [`PowerManifold`](@ref) either on the nodes or edges of the graph, depending on the [`GraphManifoldType`](@ref).
 i.e., it's either a $\mathcal M^{\lvert V \rvert}$ for the case of a vertex manifold or a $\mathcal M^{\lvert E \rvert}$ for the case of a edge manifold.
 
-## Example:
+## Example
+
+To make a graph manifold over $ℝ^2$ with three vertices and two edges, one can use
 
-To make a graph manifold over $\mathbb{R}^2$ with three vertices and two edges, one can use
 ```@example
 using Manifolds
 using LightGraphs
@@ -18,6 +19,7 @@ add_edge!(G, 1, 2)
 add_edge!(G, 2, 3)
 N = GraphManifold(G, M, VertexManifold())
 ```
+
 It supports all [`AbstractPowerManifold`](@ref) operations (it is based on [`NestedPowerRepresentation`](@ref)) and furthermore it is possible to compute a graph logarithm:
 
 ```@setup graph-1

docs/src/manifolds/product.md

@@ -1,7 +1,7 @@
 # Product manifold
 
-Product manifold $M = M_1 \times M_2 \times \dots M_n$ of manifolds $M_1, M_2, \dots, M_n$.
-Points on the product manifold can be constructed using [`ProductRepr`](@ref) with canonical projections $\Pi_i \colon M \to M_i$ for $i \in 1, 2, \dots, n$ provided by [`submanifold_component`](@ref).
+Product manifold $M = M_1 × M_2 × … M_n$ of manifolds $M_1, M_2, …, M_n$.
+Points on the product manifold can be constructed using [`ProductRepr`](@ref) with canonical projections $Π_i : M → M_i$ for $i ∈ 1, 2, …, n$ provided by [`submanifold_component`](@ref).
 
 ```@autodocs
 Modules = [Manifolds]

docs/src/manifolds/rotations.md

@@ -1,9 +1,9 @@
 # Rotations
 
-The manifold $\mathrm{SO}(n)$ of orthogonal matrices with determinant $+1$ in $\mathbb R^{n\times n}$, i.e.
+The manifold $\mathrm{SO}(n)$ of orthogonal matrices with determinant $+1$ in $ℝ^{n× n}$, i.e.
 
-$\mathrm{SO}(n) = \bigl\{R \in \mathbb{R}^{n\times n} \big| RR^{\mathrm{T}} =
-R^{\mathrm{T}}R = \mathrm{I}_n, \det(R) = 1 \bigr\}$
+$\mathrm{SO}(n) = \bigl\{R ∈ ℝ^{n × n} \big| RR^{\mathrm{T}} =
+R^{\mathrm{T}}R = I_n, \det(R) = 1 \bigr\}$
 
 The Lie group $\mathrm{SO}(n)$ is a subgroup of the orthogonal group $\mathrm{O}(n)$ and also known as the special orthogonal group or the set of rotations group.
 See also [`SpecialOrthogonal`](@ref), which is this manifold equipped with the group operation.
@@ -12,9 +12,9 @@ Tangent vectors are represented by elements of the corresponding Lie algebra, wh
 This convention allows for more efficient operations on tangent vectors.
 Tangent spaces at different points are different vector spaces.
 
-Let $L_R\colon \mathrm{SO}(n) \to \mathrm{SO}(n)$ where $R \in \mathrm{SO}(n)$ be the left-multiplication by $R$, that is $L_R(S) = RS$.
-The tangent space at rotation $R$, $T_R \mathrm{SO}(n)$, is related to the tangent space at the identity rotation $\mathrm{I}_n$ by the differential of $L_R$ at identity, $(\mathrm{d}L_R)_{\mathrm{I}_n} \colon T_{\mathrm{I}_n} \mathrm{SO}(n) \to T_R \mathrm{SO}(n)$.
-For a tangent vector at the identity rotation $v \in T_{\mathrm{I}_n} \mathrm{SO}(n)$ the matrix representation of the corresponding tangent vector $w$ at a rotation $R$ can be obtained by matrix multiplication: $w=Rv \in T_R \mathrm{SO}(n)$.
+Let $L_R: \mathrm{SO}(n) → \mathrm{SO}(n)$ where $R ∈ \mathrm{SO}(n)$ be the left-multiplication by $R$, that is $L_R(S) = RS$.
+The tangent space at rotation $R$, $T_R \mathrm{SO}(n)$, is related to the tangent space at the identity rotation $I_n$ by the differential of $L_R$ at identity, $(\mathrm{d}L_R)_{I_n} : T_{I_n} \mathrm{SO}(n) → T_R \mathrm{SO}(n)$.
+For a tangent vector at the identity rotation $v ∈ T_{I_n} \mathrm{SO}(n)$ the matrix representation of the corresponding tangent vector $w$ at a rotation $R$ can be obtained by matrix multiplication: $w=Rv ∈ T_R \mathrm{SO}(n)$.
 You can compare the functions [`log!(::Manifolds.Rotations, v, x, y)`](@ref) and [`exp!(::Manifolds.Rotations, y, x, v)`](@ref) to see how it works in practice.
 
 ```@autodocs

docs/src/manifolds/symmetricpositivedefinite.md

@@ -3,7 +3,7 @@
 The symmetric positive definite matrices
 
 ```math
-\mathcal P(n) = \bigl\{ A \in \mathbb R^{n\times n}\ \big|\ A = A^{\mathrm{T}} \text{ and } x^{\mathrm{T}}Ax > 0 \text{ for } 0\neq x \in\mathbb R^n \bigr\}
+\mathcal P(n) = \bigl\{ A ∈ ℝ^{n × n}\ \big|\ A = A^{\mathrm{T}} \text{ and } x^{\mathrm{T}}Ax > 0 \text{ for } 0 ≠ x ∈ ℝ^n \bigr\}
 ```
 
 ```@docs

docs/src/manifolds/torus.md

@@ -1,11 +1,11 @@
 # Torus
-The torus $\mathbb T^d \equiv [-π,π)^d$ is modeled as an [`AbstractPowerManifold`](@ref) of
+The torus $𝕋^d \cong [-π,π)^d$ is modeled as an [`AbstractPowerManifold`](@ref) of
 the (real-valued) [`Circle`](@ref) and uses [`MultidimentionalArrayPowerRepresentation`](@ref).
-Points on the torus are hence row vectors, $x\in\mathbb R^{d}$.
+Points on the torus are hence row vectors, $x ∈ ℝ^{d}$.
 
 ## Example
 
-The following code can be used to make a three-dimensional torus $\mathbb{T}^3$ and compute a tangent vector.
+The following code can be used to make a three-dimensional torus $𝕋^3$ and compute a tangent vector.
 ```@example
 using Manifolds
 M = Torus(3)

docs/src/manifolds/vector_bundle.md

@@ -1,7 +1,7 @@
 # Vector bundles
 
-Vector bundle $E$ is a manifold that is built on top of another manifold $M$ (base space).
-It is characterized by a continuous function $\Pi \colon E \to M$, such that for each point $x \in M$ the preimage of $x$ by $\Pi$, $\Pi^{-1}(\{x\})$, has a structure of a vector space.
+Vector bundle $E$ is a manifold that is built on top of another manifold $\mathcal M$ (base space).
+It is characterized by a continuous function $Π : E → \mathcal M$, such that for each point $p ∈ \mathcal M$ the preimage of $p$ by $Π$, $Π^{-1}(\{p\})$, has a structure of a vector space.
 These vector spaces are called fibers.
 Bundle projection can be performed using function [`bundle_projection`](@ref).
 

docs/src/notation.md

@@ -0,0 +1,41 @@
+# Notation overview
+
+Since manifolds include a reasonable amount of elements and functions, the following list tries to keep an overview of used notation throughout `Manifolds.jl`.
+The order is alphabetically by name.
+They might be used in a plain form within the code or when referring to that code.
+This is for example the case the calligraphic symbols.
+
+Within the documented functions the utf8 symbols are used whenever possible,
+as long as that renders still in $\TeX$ within this documentation.
+
+| Symbol | Description | Also used | Comment |
+|:--:|:--------------- |:--:|:-- |
+| $\times$ | Cartesian product of two manifolds | | see [`ProductManifold`](@ref) |
+| $^{\wedge}$ | (n-ary) Cartesian power of a manifold | | see [`PowerManifold`](@ref) |
+| $T^*_p \mathcal M$ | the cotangent space at $p$ | | |
+| $\xi$ | a cotangent vector from $T^*_p \mathcal M$ | $\xi_1, \xi_2,\ldots,\eta,\zeta$ | sometimes written with base point $\xi_p$. |
+| $n$ | dimension (of a manifold) | $n_1,n_2,\ldots,m, \dim(\mathcal M)$| for the real dimension sometimes also $\dim_{\mathbb R}(\mathcal M)$|
+| $d(\cdot,\cdot)$ | (Riemannian) distance | $d_{\mathcal M}(\cdot,\cdot)$ | |
+| $F$ | a fiber | | |
+| $\mathbb F$ | a field | | field a manifold is based on, usually $\mathbb F \in \{\mathbb R,\mathbb C\}$ |
+| $\gamma$ | a geodesic | $\gamma_{p;q}$, $\gamma_{p,X}$ | connecting two points $p,q$ or starting in $p$ with velocity $X$. |
+| $\circ$ | a group operation | |
+| $\cdot^\mathrm{H}$ | Hermitian or conjugate transposed| |
+| $e$ | identity element of a group | |
+| $I_k$ | identity matrix of size $k\times k$ | |
+| $k$ | indices | $i,j$ | |
+| $\langle\cdot,\cdot\rangle$ | inner product (in $T_p \mathcal M$) | $\langle\cdot,\cdot\rangle_p, g_p(\cdot,\cdot)$ |
+| $\mathfrak g$ | a Lie algebra | |
+| $\mathcal{G}$ | a (Lie) group | |
+| $\mathcal M$ | a manifold | $\mathcal M_1, \mathcal M_2,\ldots,\mathcal N$ | |
+| $\operatorname{Exp}$ | the matrix exponential | |
+| $\operatorname{Log}$ | the matrix logarithm | |
+| $\mathcal P_{q\gets p}X$ | parallel transport | | of the vector $X$ from $T_p\mathcal M$ to $T_q\mathcal M$
+| $p$ | a point on $\mathcal M$ | $p_1, p_2, \ldots,q$ | for 3 points one might use $x,y,z$ |
+| $\Xi$ | a set of tangent vectors | $\{X_1,\ldots,X_n\}$ | |
+| $T_p \mathcal M$ | the tangent space at $p$ | | |
+| $X$ | a tangent vector from $T_p \mathcal M$ | $X_1,X_2,\ldots,Y,Z$ | sometimes written with base point $X_p$ |
+| $\operatorname{tr}$ | trace (of a matrix) | |
+| $\cdot^\mathrm{T}$ | transposed | |
+| $B$ | a vector bundle | |
+| $0_k$ | the $k\times k$ zero matrix. | |

docs/src/orthonormal_bases.md

@@ -1,8 +1,8 @@
 # Orthonormal bases
 
 The following functions and types provide support for orthonormal bases of the tangent space of different manifolds.
-An orthonormal basis of the tangent space $T_x M$ of (real) dimension $N$ has a real-coefficient basis $e_1, e_2, \dots, e_N$ if $\mathrm{Re}(g_x(e_i, e_j)) = \delta_{ij}$ for each $i,j \in \{1, 2, \dots, N\}$ where $g_x$ is the Riemannian metric at point $x$.
-A vector $v$ from the tangent space $T_x M$ can be expressed as a sum $v = v^i e_i$ where coefficients $v^i$ are calculated as $v^i = \mathrm{Re}(g_x(v, e_i))$.
+An orthonormal basis of the tangent space $T_x \mathcal M$ of (real) dimension $N$ has a real-coefficient basis $e_1, e_2, …, e_N$ if $\mathrm{Re}(g_x(e_i, e_j)) = \delta_{ij}$ for each $i,j ∈ \{1, 2, …, N\}$ where $g_x$ is the Riemannian metric at point $x$.
+A vector $v$ from the tangent space $T_x \mathcal M$ can be expressed in Einstein notation as a sum $v = v^i e_i$ where coefficients $v^i$ are calculated as $v^i = \mathrm{Re}(g_x(v, e_i))$.
 
 The main types are:
 * [`ArbitraryOrthonormalBasis`](@ref), which is designed to work when no special properties of the tangent space basis are required.

src/Manifolds.jl

@@ -108,63 +108,63 @@ Abstract type for defining statistical estimation methods.
 """
 abstract type AbstractEstimationMethod end
 
-@doc doc"""
-    hat(M::Manifold, x, vⁱ)
+@doc raw"""
+    hat(M::Manifold, p, Xⁱ)
 
-Given a basis $e_i$ on the tangent space at a point $x$ and tangent
-component vector $v^i$, compute the equivalent vector representation
-$v=v^i e_i$, where Einstein summation notation is used:
+Given a basis $e_i$ on the tangent space at a point `p` and tangent
+component vector $X^i$, compute the equivalent vector representation
+$X=X^i e_i$, where Einstein summation notation is used:
 
 ````math
-\wedge: v^i \mapsto v^i e_i
+∧ : X^i ↦ X^i e_i
 ````
 
 For array manifolds, this converts a vector representation of the tangent
 vector to an array representation. The [`vee`](@ref) map is the `hat` map's
 inverse.
 """
-function hat(M::Manifold, x, vⁱ)
-    v = allocate_result(M, hat, x, vⁱ)
-    return hat!(M, v, x, vⁱ)
+function hat(M::Manifold, p, Xⁱ)
+    X = allocate_result(M, hat, p, Xⁱ)
+    return hat!(M, X, p, Xⁱ)
 end
 
-function hat!(M::Manifold, v, x, vⁱ)
-    is_decorator_manifold(M) === Val(true) && return hat!(base_manifold(M), v, x, vⁱ)
-    error("hat! operator not defined for manifold $(typeof(M)), array $(typeof(v)), point $(typeof(x)), and vector $(typeof(vⁱ))")
+function hat!(M::Manifold, X, p, Xⁱ)
+    is_decorator_manifold(M) === Val(true) && return hat!(base_manifold(M), X, p, Xⁱ)
+    error("hat! operator not defined for manifold $(typeof(M)), array $(typeof(X)), point $(typeof(p)), and vector $(typeof(Xⁱ))")
 end
 
-@doc doc"""
-    vee(M::Manifold, x, v)
+@doc raw"""
+    vee(M::Manifold, p, X)
 
-Given a basis $e_i$ on the tangent space at a point $x$ and tangent
-vector $v$, compute the vector components $v^i$, such that $v = v^i e_i$, where
+Given a basis $e_i$ on the tangent space at a point `p` and tangent
+vector `X`, compute the vector components $X^i$, such that $X = X^i e_i$, where
 Einstein summation notation is used:
 
 ````math
-\vee: v^i e_i \mapsto v^i
+\vee : X^i e_i ↦ X^i
 ````
 
 For array manifolds, this converts an array representation of the tangent
 vector to a vector representation. The [`hat`](@ref) map is the `vee` map's
 inverse.
 """
-function vee(M::Manifold, x, v)
-    vⁱ = allocate_result(M, vee, x, v)
-    return vee!(M, vⁱ, x, v)
+function vee(M::Manifold, p, X)
+    Xⁱ = allocate_result(M, vee, p, X)
+    return vee!(M, Xⁱ, p, X)
 end
 
-function vee!(M::Manifold, vⁱ, x, v)
-    is_decorator_manifold(M) === Val(true) && return vee!(base_manifold(M), vⁱ, x, v)
-    error("vee! operator not defined for manifold $(typeof(M)), vector $(typeof(vⁱ)), point $(typeof(x)), and array $(typeof(v))")
+function vee!(M::Manifold, Xⁱ, p, X)
+    is_decorator_manifold(M) === Val(true) && return vee!(base_manifold(M), Xⁱ, p, X)
+    error("vee! operator not defined for manifold $(typeof(M)), vector $(typeof(Xⁱ)), point $(typeof(p)), and array $(typeof(X))")
 end
 
-function allocate_result(M::Manifold, f::typeof(vee), x, v)
-    T = allocate_result_type(M, f, (x, v))
-    return allocate(x, T, manifold_dimension(M))
+function allocate_result(M::Manifold, f::typeof(vee), p, X)
+    T = allocate_result_type(M, f, (p, X))
+    return allocate(p, T, manifold_dimension(M))
 end
-function allocate_result(M::Manifold, f::typeof(vee), x::StaticArray, v)
-    T = allocate_result_type(M, f, (x, v))
-    return allocate(x, T, Size(manifold_dimension(M)))
+function allocate_result(M::Manifold, f::typeof(vee), p::StaticArray, X)
+    T = allocate_result_type(M, f, (p, X))
+    return allocate(p, T, Size(manifold_dimension(M)))
 end
 
 """

src/autodiff.jl

@@ -40,22 +40,22 @@ Get vector of currently valid AD backends.
 adbackends() = _adbackends
 
 """
-    _gradient(f, x::Number, backend = adbackend()) -> Number
-    _gradient(f, x::Array, backend = adbackend()) -> Array
+    _gradient(f, p::Number, backend = adbackend()) -> Number
+    _gradient(f, p::Array, backend = adbackend()) -> Array
 
-Compute gradient of function `f` at point `x` using AD backend `backend`.
+Compute gradient of function `f` at `x` using AD backend `backend`.
 """
-_gradient(f, x) = _gradient(f, x, Val(adbackend()))
-_gradient(f, x, backend::Symbol) = _gradient(f, x, Val(adbackend(backend)))
+_gradient(f, p) = _gradient(f, p, Val(adbackend()))
+_gradient(f, p, backend::Symbol) = _gradient(f, p, Val(adbackend(backend)))
 
 """
-    _jacobian(f, x::Array, backend = adbackend()) -> Array
+    _jacobian(f, p, backend = adbackend()) -> Array
 
-Compute Jacobian matrix of function `f` at point `x` using AD backend `backend`.
+Compute Jacobian matrix of function `f` at `p` using AD backend `backend`.
 Inputs and outputs of `f` are vectorized.
 """
-_jacobian(f, x) = _jacobian(f, x, Val(adbackend()))
-_jacobian(f, x, backend::Symbol) = _jacobian(f, x, Val(adbackend(backend)))
+_jacobian(f, p) = _jacobian(f, p, Val(adbackend()))
+_jacobian(f, p, backend::Symbol) = _jacobian(f, p, Val(adbackend(backend)))
 
 # Finite differences
 
@@ -64,14 +64,14 @@ adbackend!(:finitedifferences)
 
 _default_fdm() = central_fdm(5, 1)
 
-_gradient(f, x, backend::Val{:finitedifferences}) = _gradient(f, x, _default_fdm())
+_gradient(f, p, backend::Val{:finitedifferences}) = _gradient(f, p, _default_fdm())
 
-function _gradient(f, x, fdm::FiniteDifferences.FiniteDifferenceMethod)
-    return FiniteDifferences.grad(fdm, f, x)[1]
+function _gradient(f, p, fdm::FiniteDifferences.FiniteDifferenceMethod)
+    return FiniteDifferences.grad(fdm, f, p)[1]
 end
 
-_jacobian(f, x, backend::Val{:finitedifferences}) = _jacobian(f, x, _default_fdm())
+_jacobian(f, p, backend::Val{:finitedifferences}) = _jacobian(f, p, _default_fdm())
 
-function _jacobian(f, x, fdm::FiniteDifferences.FiniteDifferenceMethod)
-    return FiniteDifferences.jacobian(fdm, f, x)[1]
+function _jacobian(f, p, fdm::FiniteDifferences.FiniteDifferenceMethod)
+    return FiniteDifferences.jacobian(fdm, f, p)[1]
 end

src/distributions.jl

@@ -10,12 +10,12 @@ struct FVectorvariate <: VariateForm end
     FVectorSupport(space::Manifold, VectorBundleFibers)
 
 Value support for vector bundle fiber-valued distributions (values from a fiber of a vector
-bundle at point `x` from the given manifold).
+bundle at a `point` from the given manifold).
 For example used for tangent vector-valued distributions.
 """
 struct FVectorSupport{TSpace<:VectorBundleFibers,T} <: ValueSupport
     space::TSpace
-    x::T
+    point::T
 end
 
 """