Merge pull request #28 from JuliaNLSolvers/basis-clarification

Clarify the real- and complex-valued basis difference.

Project.toml

@@ -1,7 +1,7 @@
 name = "ManifoldsBase"
 uuid = "3362f125-f0bb-47a3-aa74-596ffd7ef2fb"
 authors = ["Seth Axen <[email protected]>", "Mateusz Baran <[email protected]>", "Ronny Bergmann <[email protected]>", "Antoine Levitt <[email protected]>"]
-version = "0.7"
+version = "0.7.1"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

src/DecoratorManifold.jl

@@ -568,6 +568,7 @@ decorated_manifold(M::Manifold) = M.manifold
 
 @decorator_transparent_signature manifold_dimension(M::AbstractDecoratorManifold)
 
+@decorator_transparent_signature number_system(M::AbstractDecoratorManifold)
 
 @decorator_transparent_signature project(M::AbstractDecoratorManifold, p)
 @decorator_transparent_signature project!(M::AbstractDecoratorManifold, q, p)

src/DefaultManifold.jl

@@ -84,6 +84,8 @@ log!(::DefaultManifold, v, x, y) = (v .= y .- x)
 
 @generated manifold_dimension(::DefaultManifold{T,𝔽}) where {T,𝔽} = *(T.parameters...)*real_dimension(𝔽)
 
+number_system(::DefaultManifold{T,𝔽}) where {T,𝔽} = 𝔽
+
 norm(::DefaultManifold, x, v) = norm(v)
 
 project!(::DefaultManifold, y, x) = copyto!(y, x)

src/bases.jl

@@ -3,7 +3,8 @@
 
 Abstract type that represents a basis on a manifold or a subset of it.
 
-The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used as scalars.
+The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used
+for the vectors elements.
 """
 abstract type AbstractBasis{𝔽} end
 
@@ -13,7 +14,8 @@ abstract type AbstractBasis{𝔽} end
 An arbitrary basis on a manifold. This will usually
 be the fastest basis available for a manifold.
 
-The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used as scalars.
+The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used
+for the vectors elements
 """
 struct DefaultBasis{𝔽} <: AbstractBasis{𝔽} end
 DefaultBasis(𝔽::AbstractNumbers = ℝ) = DefaultBasis{𝔽}()
@@ -23,7 +25,8 @@ DefaultBasis(𝔽::AbstractNumbers = ℝ) = DefaultBasis{𝔽}()
 
 Abstract type that represents an orthonormal basis on a manifold or a subset of it.
 
-The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used as scalars.
+The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used
+for the vectors elements.
 """
 abstract type AbstractOrthogonalBasis{𝔽} <: AbstractBasis{𝔽} end
 
@@ -33,7 +36,8 @@ abstract type AbstractOrthogonalBasis{𝔽} <: AbstractBasis{𝔽} end
 An arbitrary orthogonal basis on a manifold. This will usually
 be the fastest orthogonal basis available for a manifold.
 
-The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used as scalars.
+The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used
+for the vectors elements.
 """
 struct DefaultOrthogonalBasis{𝔽} <: AbstractOrthogonalBasis{𝔽} end
 DefaultOrthogonalBasis(𝔽::AbstractNumbers = ℝ) = DefaultOrthogonalBasis{𝔽}()
@@ -47,7 +51,8 @@ VeeOrthogonalBasis(𝔽::AbstractNumbers = ℝ) = VeeOrthogonalBasis{𝔽}()
 
 Abstract type that represents an orthonormal basis on a manifold or a subset of it.
 
-The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used as scalars.
+The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used
+for the vectors elements.
 """
 abstract type AbstractOrthonormalBasis{𝔽} <: AbstractOrthogonalBasis{𝔽} end
 
@@ -57,8 +62,8 @@ abstract type AbstractOrthonormalBasis{𝔽} <: AbstractOrthogonalBasis{𝔽} en
 An arbitrary orthonormal basis on a manifold. This will usually
 be the fastest orthonormal basis available for a manifold.
 
-The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used as
-scalars.
+The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used
+for the vectors elements.
 """
 struct DefaultOrthonormalBasis{𝔽} <: AbstractOrthonormalBasis{𝔽} end
 
@@ -71,8 +76,8 @@ An orthonormal basis that comes from orthonormalization of basis vectors
 of the ambient space projected onto the subspace representing the tangent space
 at a given point.
 
-The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used as
-scalars.
+The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used
+for the vectors elements.
 
 Available methods:
   - `:gram_schmidt` uses a modified Gram-Schmidt orthonormalization.
@@ -94,8 +99,8 @@ An orthonormal basis `Ξ` as a vector of tangent vectors (of length determined b
 [`manifold_dimension`](@ref)) in the tangent space that diagonalizes the curvature
 tensor $R(u,v)w$ and where the direction `frame_direction` $v$ has curvature `0`.
 
-The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used as
-scalars.
+The type parameter `𝔽` denotes the [`AbstractNumbers`](@ref) that will be used
+for the vectors elements.
 """
 struct DiagonalizingOrthonormalBasis{TV,𝔽} <: AbstractOrthonormalBasis{𝔽}
     frame_direction::TV
@@ -344,7 +349,7 @@ function get_coordinates!(
     X,
     B::CachedBasis{BT},
 ) where {BT<:AbstractBasis{ℝ}}
-    map!(vb -> real(inner(M, p, X, vb)), Y, get_vectors(M, p, B))
+    map!(vb -> inner(M, p, X, vb), Y, get_vectors(M, p, B))
     return Y
 end
 function get_coordinates!(M::Manifold, Y, p, X, B::CachedBasis{<:AbstractBasis{ℂ}})
@@ -464,7 +469,7 @@ hat!(M::Manifold, Y, p, X) = get_vector!(M, Y, p, X, VeeOrthogonalBasis())
 """
     number_system(::AbstractBasis)
 
-The number system used as scalars in the given basis.
+The number system for the vectors of the given basis.
 """
 number_system(::AbstractBasis{𝔽}) where {𝔽} = 𝔽
 
@@ -506,7 +511,7 @@ end
 function show(io::IO, mime::MIME"text/plain", onb::DiagonalizingOrthonormalBasis)
     println(
         io,
-        "DiagonalizingOrthonormalBasis with coordinates in $(number_system(onb)) and eigenvalue 0 in direction:",
+        "DiagonalizingOrthonormalBasis($(number_system(onb))) and eigenvalue 0 in direction:",
     )
     sk = sprint(show, "text/plain", onb.frame_direction, context = io, sizehint = 0)
     sk = replace(sk, '\n' => "\n ")
@@ -519,7 +524,8 @@ function show(
 ) where {T<:AbstractBasis,D,𝔽}
     print(
         io,
-        "$(T()) with coordinates in $(number_system(B)) and $(length(_get_vectors(B))) basis vector$(length(_get_vectors(B)) == 1 ? "" : "s"):",
+
+        "$(T()) and $(length(_get_vectors(B))) basis vector$(length(_get_vectors(B)) == 1 ? "" : "s"):",
     )
     _show_basis_vector_range_noheader(
         io,

src/numbers.jl

@@ -52,3 +52,11 @@ end
 real_dimension(::RealNumbers) = 1
 real_dimension(::ComplexNumbers) = 2
 real_dimension(::QuaternionNumbers) = 4
+
+@doc raw"""
+    number_system(M::Manifold)
+
+Return the number system the manifold `M` is based on. The default of the number system is
+real-valued, i.e. `number_system(M) = ℝ`.
+"""
+number_system(M::Manifold) = ℝ

test/bases.jl

@@ -272,7 +272,7 @@ end
     @test sprint(show, ProjectedOrthonormalBasis(:gram_schmidt, ℂ)) == "ProjectedOrthonormalBasis(:gram_schmidt, ℂ)"
 
     @test sprint(show, "text/plain", DiagonalizingOrthonormalBasis(Float64[1, 2, 3])) == """
-    DiagonalizingOrthonormalBasis with coordinates in ℝ and eigenvalue 0 in direction:
+    DiagonalizingOrthonormalBasis(ℝ) and eigenvalue 0 in direction:
     3-element Array{Float64,1}:
       1.0
       2.0
@@ -282,7 +282,7 @@ end
     x = collect(reshape(1.0:6.0, (2, 3)))
     pb = get_basis(M, x, DefaultOrthonormalBasis())
     @test sprint(show, "text/plain", pb) == """
-    DefaultOrthonormalBasis(ℝ) with coordinates in ℝ and 6 basis vectors:
+    DefaultOrthonormalBasis(ℝ) and 6 basis vectors:
      E1 =
       2×3 Array{Float64,2}:
        1.0  0.0  0.0
@@ -303,7 +303,7 @@ end
     b = DiagonalizingOrthonormalBasis(get_vectors(M, x, pb)[1])
     dpb = CachedBasis(b, Float64[1, 2, 3, 4, 5, 6], get_vectors(M, x, pb))
     @test sprint(show, "text/plain", dpb) == """
-    DiagonalizingOrthonormalBasis with coordinates in ℝ and eigenvalue 0 in direction:
+    DiagonalizingOrthonormalBasis(ℝ) and eigenvalue 0 in direction:
      2×3 Array{Float64,2}:
        1.0  0.0  0.0
        0.0  0.0  0.0
@@ -339,15 +339,15 @@ end
     x = reshape(Float64[1], (1, 1, 1))
     pb = get_basis(M, x, DefaultOrthonormalBasis())
     @test sprint(show, "text/plain", pb) == """
-    DefaultOrthonormalBasis(ℝ) with coordinates in ℝ and 1 basis vector:
+    DefaultOrthonormalBasis(ℝ) and 1 basis vector:
      E1 =
       1×1×1 Array{Float64,3}:
       [:, :, 1] =
        1.0"""
 
     dpb = CachedBasis(DiagonalizingOrthonormalBasis(get_vectors(M, x, pb)), Float64[1], get_vectors(M, x, pb))
     @test sprint(show, "text/plain", dpb) == """
-    DiagonalizingOrthonormalBasis with coordinates in ℝ and eigenvalue 0 in direction:
+    DiagonalizingOrthonormalBasis(ℝ) and eigenvalue 0 in direction:
      1-element Array{Array{Float64,3},1}:
        [1.0]
     and 1 basis vector.

test/decorator_manifold.jl

@@ -145,6 +145,9 @@ decorator_transparent_dispatch(::typeof(test18), M::ChildDecorator, args...) = V
     @test (@inferred ManifoldsBase.decorated_manifold(A)) == M
     @test ManifoldsBase._extract_val(Val(:transparent)) === :transparent
 
+    @test number_system(M) == ℝ
+    @test number_system(ManifoldsBase.DefaultManifold(3; field=ℂ)) == ℂ
+
     @test (@inferred base_manifold(M, Val(1))) == M
     @test (@inferred base_manifold(M, Val(0))) == M
     @test (@inferred base_manifold(A, Val(1))) == M

test/default_manifold.jl

@@ -32,6 +32,7 @@ ManifoldsBase.injectivity_radius(
     @test isa(manifold_dimension(M), Integer)
     @test manifold_dimension(M) ≥ 0
     @test base_manifold(M) == M
+    @test number_system(M) == ℝ
     @test ManifoldsBase.representation_size(M) == (3,)
 
     @test injectivity_radius(M) == Inf