Documentation and Convenience wrappers

README.md

@@ -2,6 +2,21 @@ A Julia library to handle projections on manifolds. This is useful for minimizin
 
 Currently, the sphere `{x ∈ K^n, ||x|| = r}` and the Stiefel manifold `{X ∈ K^{n × m}, X'*X = I}` as well as independent copies of these manifolds are supported.
 
+The projections implemented are retract and project_tangent (both are also available inplace `!`).
+```
+retract(M::Manifold, x) = retract!(M, copy(x))
+```
+retracts the given point `x` back onto the Manifold `M`.
+```
+project_tangent(M::Manifold, g, x) = project_tangent!(M, copy(g), x)
+```
+Projects the given vector `g` into the tangent space on the Manifold `M` around the point `x`.
+`x` is assumed to lie on the manifold. This is not checked!
+
+To combine Manifolds one can use `PowerManifold` and `ProductManifold`.
+The constructor of `PowerManifold` takes the exponentiated manifold `M`, the dimensions of this manifold `inner_dims` and the exponents `outer_dims`.
+The constructor of `ProductManifold` takes the two manifolds `m1` and `m2` and their respective dimensions `dims1` and `dims2` as arguments.
+
 Example usage:
 
 ```julia

src/ManifoldProjections.jl

@@ -20,8 +20,20 @@ abstract type Manifold
 end
 
 # fallback for out-of-place ops
+"Returns a point that corresponds to the retraction of the given point `x` back onto the Manifold `M`"
 retract(M::Manifold, x) = retract!(M, copy(x))
+"Retracts a given point `x` back onto the Manifold `M`"
+function retract!(M::Manifold, x) end
+"""
+Returns the projection of the given vector `g` into the tangent space on the Manifold `M` around the point `x`.
+`x` is assumed to lie on the manifold. This is not checked!
+"""
 project_tangent(M::Manifold, g, x) = project_tangent!(M, copy(g), x)
+"""
+Projects the given vector `g` into the tangent space on the Manifold `M` around the point `x`.
+`x` is assumed to lie on the manifold. This is not checked!
+"""
+function project_tangent!(M::Manifold, g, x) end
 
 # Fake objective function implementing a retraction
 mutable struct ManifoldObjective{T<:NLSolversBase.AbstractObjective} <: NLSolversBase.AbstractObjective
@@ -115,6 +127,9 @@ struct PowerManifold<:Manifold
     "Number of embedded manifolds"
     outer_dims::Tuple
 end
+PowerManifold(m::Manifold, inner_dim::Int, outer_dim::Int) = ProductManifold(m, Tuple(inner_dim), Tuple(outer_dim))
+PowerManifold(m::Manifold, inner_dim::Tuple, outer_dim::Int) = ProductManifold(m, inner_dim, Tuple(outer_dim))
+PowerManifold(m::Manifold, inner_dim::Int, outer_dim::Tuple) = ProductManifold(m, Tuple(inner_dim), outer_dim)
 function retract!(m::PowerManifold, x)
     for i=1:prod(m.outer_dims) # TODO: use for i in LinearIndices(m.outer_dims)?
         retract!(m.inner_manifold,get_inner(m, x, i))
@@ -145,6 +160,9 @@ struct ProductManifold<:Manifold
     dims1::Tuple
     dims2::Tuple
 end
+ProductManifold(m1::Manifold, m2::Manifold, dim1::Int, dim2::Int) = ProductManifold(m1, m2, Tuple(dim1), Tuple(dim2))
+ProductManifold(m1::Manifold, m2::Manifold, dim1::Tuple, dim2::Int) = ProductManifold(m1, m2, dim1, Tuple(dim2))
+ProductManifold(m1::Manifold, m2::Manifold, dim1::Int, dim2::Tuple) = ProductManifold(m1, m2, Tuple(dim1), dim2)
 function retract!(m::ProductManifold, x)
     retract!(m.m1, get_inner(m,x,1))
     retract!(m.m2, get_inner(m,x,2))