Refactor Identity to not allocate memory if not necessary

.github/workflows/documenter.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: 1.5
+          version: 1.6
       - uses: julia-actions/julia-docdeploy@v1
         env:
           PYTHON: ""

Project.toml

@@ -1,7 +1,7 @@
 name = "Manifolds"
 uuid = "1cead3c2-87b3-11e9-0ccd-23c62b72b94e"
 authors = ["Seth Axen <seth.axen@gmail.com>", "Mateusz Baran <mateuszbaran89@gmail.com>", "Ronny Bergmann <manopt@ronnybergmann.net>", "Antoine Levitt <antoine.levitt@gmail.com>"]
-version = "0.5.13"
+version = "0.6.0"
 
 [deps]
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
@@ -32,8 +32,8 @@ FiniteDifferences = "0.12"
 HybridArrays = "0.4"
 Kronecker = "0.4"
 LightGraphs = "1"
-ManifoldsBase = "0.12.1"
-Plots = "~1.6, =1.10.5"
+ManifoldsBase = "0.12.4"
+Plots = "1"
 RecipesBase = "1.1"
 Requires = "0.5, 1"
 SimpleWeightedGraphs = "1"
@@ -62,4 +62,4 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 VisualRegressionTests = "34922c18-7c2a-561c-bac1-01e79b2c4c92"
 
 [targets]
-test = ["Test", "Colors", "DoubleFloats", "FiniteDiff", "ForwardDiff", "Gtk", "ImageIO", "ImageMagick", "OrdinaryDiffEq", "NLsolve", "Plots", "PyPlot", "Quaternions", "QuartzImageIO", "RecipesBase", "ReverseDiff", "VisualRegressionTests"]
+test = ["Test", "Colors", "DoubleFloats", "FiniteDiff", "ForwardDiff", "Gtk", "ImageIO", "ImageMagick", "OrdinaryDiffEq", "NLsolve", "Plots", "PyPlot", "Quaternions", "QuartzImageIO", "RecipesBase", "ReverseDiff"]

docs/Project.toml

@@ -14,9 +14,9 @@ StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
-Documenter = "0.24, 0.25, 0.26"
+Documenter = "0.24, 0.25, 0.26, 0.27"
 HybridArrays = "0.4"
-ManifoldsBase = "0.12"
-Plots = "= 1.10.5"
+ManifoldsBase = "0.12.4"
+Plots = "1"
 PyPlot = "2.9"
 StaticArrays = "1.0"

docs/src/manifolds/group.md

@@ -17,9 +17,10 @@ Depth = 3
 
 The following operations are available for group manifolds:
 
-* [`identity`](@ref): get the identity of the group.
+* [`Identity`](@ref): an allocation-free representation of the identity element of the group.
 * [`inv`](@ref): get the inverse of a given element.
 * [`compose`](@ref): compose two given elements of a group.
+* [`identity_element`](@ref) get the identity element of the group, in the representation used by other points from the group.
 
 ### Group manifold
 

src/Manifolds.jl

@@ -13,13 +13,16 @@ import ManifoldsBase:
     check_point,
     check_point__transparent,
     check_vector,
+    copy,
+    copyto!,
     decorated_manifold,
     decorator_transparent_dispatch,
     default_decorator_dispatch,
     distance,
     dual_basis,
     embed,
     embed!,
+    exp,
     exp!,
     exp!__intransparent,
     get_basis,
@@ -32,6 +35,8 @@ import ManifoldsBase:
     get_vector!,
     get_vectors,
     gram_schmidt,
+    hat,
+    hat!,
     injectivity_radius,
     inner,
     inner__intransparent,
@@ -58,12 +63,25 @@ import ManifoldsBase:
     vector_transport_direction!,
     vector_transport_to,
     vector_transport_to!,
+    vee,
+    vee!,
     zero_vector,
     zero_vector!,
     CotangentSpace,
     TangentSpace
 import Base:
-    copyto!, convert, foreach, in, isapprox, isempty, length, ndims, showerror, size
+    copyto!,
+    convert,
+    foreach,
+    identity,
+    in,
+    isapprox,
+    isempty,
+    length,
+    ndims,
+    showerror,
+    size,
+    transpose
 
 using Base.Iterators: repeated
 using Distributions
@@ -146,8 +164,6 @@ include("riemannian_diff.jl")
 include("manifolds/ConnectionManifold.jl")
 include("manifolds/MetricManifold.jl")
 include("manifolds/VectorBundle.jl")
-
-# It's included early to ensure visibility of `Identity`
 include("groups/group.jl")
 
 # Features I: Which are extended on Meta Manifolds
@@ -228,7 +244,7 @@ include("groups/connections.jl")
 include("groups/metric.jl")
 include("groups/group_action.jl")
 include("groups/group_operation_action.jl")
-include("groups/array_manifold.jl")
+include("groups/validation_group.jl")
 include("groups/product_group.jl")
 include("groups/semidirect_product_group.jl")
 
@@ -468,6 +484,8 @@ export ×,
     get_embedding,
     hat,
     hat!,
+    identity_element,
+    identity_element!,
     induced_basis,
     incident_log,
     injectivity_radius,
@@ -476,10 +494,11 @@ export ×,
     inverse_retract,
     inverse_retract!,
     isapprox,
-    is_group_decorator,
     is_decorator_transparent,
-    is_default_metric,
     is_default_decorator,
+    is_default_metric,
+    is_group_decorator,
+    is_identity,
     is_point,
     is_vector,
     isapprox,
@@ -578,15 +597,17 @@ export adjoint_action,
     compose,
     compose!,
     direction,
+    exp_lie,
+    exp_lie!,
     g_manifold,
-    group_exp,
-    group_exp!,
-    group_log,
-    group_log!,
+    get_coordinates_lie,
+    get_coordinates_lie!,
+    get_vector_lie,
+    get_vector_lie!,
     has_biinvariant_metric,
     has_invariant_metric,
-    identity,
-    identity!,
+    identity_element,
+    identity_element!,
     inv,
     inv!,
     invariant_metric_dispatch,
@@ -600,7 +621,8 @@ export adjoint_action,
     inverse_translate_diff!,
     lie_bracket,
     lie_bracket!,
-    make_identity,
+    log_lie,
+    log_lie!,
     optimal_alignment,
     optimal_alignment!,
     screw_matrix,

src/groups/circle_group.jl

@@ -18,20 +18,17 @@ adjoint_action(::CircleGroup, p, X) = X
 
 adjoint_action!(::CircleGroup, Y, p, X) = copyto!(Y, X)
 
-function compose(G::CircleGroup, p::AbstractVector, q::AbstractVector)
+function _compose(G::CircleGroup, p::AbstractVector, q::AbstractVector)
     return map(compose, repeated(G), p, q)
 end
 
-compose!(G::CircleGroup, x, p, q) = copyto!(x, compose(G, p, q))
+_compose!(G::CircleGroup, x, p, q) = copyto!(x, compose(G, p, q))
 
-Base.identity(::CircleGroup, p::AbstractVector) = map(one, p)
-Base.identity(G::GT, e::Identity{GT}) where {GT<:CircleGroup} = e
-
-identity!(::CircleGroup, q::AbstractVector, p) = copyto!(q, 1)
-identity!(::GT, q::AbstractVector, ::Identity{GT}) where {GT<:CircleGroup} = copyto!(q, 1)
+identity_element(G::CircleGroup) = 1.0
+identity_element(::CircleGroup, p::Number) = one(p)
+identity_element(::CircleGroup, p::AbstractArray) = map(i -> one(eltype(p)), p)
 
 Base.inv(G::CircleGroup, p::AbstractVector) = map(inv, repeated(G), p)
-Base.inv(G::GT, e::Identity{GT}) where {GT<:CircleGroup} = e
 
 function inverse_translate(
     ::CircleGroup,
@@ -56,35 +53,36 @@ lie_bracket!(::CircleGroup, Z, X, Y) = fill!(Z, 0)
 
 translate_diff(::GT, p, q, X, ::ActionDirection) where {GT<:CircleGroup} = map(*, p, X)
 function translate_diff(
-    ::GT,
-    ::Identity{GT},
+    ::CircleGroup,
+    ::Identity{MultiplicationOperation},
     q,
     X,
     ::ActionDirection,
-) where {GT<:CircleGroup}
+)
     return X
 end
 
 function translate_diff!(G::CircleGroup, Y, p, q, X, conv::ActionDirection)
     return copyto!(Y, translate_diff(G, p, q, X, conv))
 end
 
-function group_exp(G::CircleGroup, X)
+function exp_lie(::CircleGroup, X)
     return map(X) do imθ
         θ = imag(imθ)
         sinθ, cosθ = sincos(θ)
         return Complex(cosθ, sinθ)
     end
 end
 
-group_exp!(G::CircleGroup, q, X) = (q .= group_exp(G, X))
+exp_lie!(G::CircleGroup, q, X) = (q .= exp_lie(G, X))
 
-function group_log(G::CircleGroup, q)
+function log_lie(::CircleGroup, q)
     return map(q) do z
         cosθ, sinθ = reim(z)
         θ = atan(sinθ, cosθ)
         return θ * im
     end
 end
+log_lie(::CircleGroup, e::Identity{MultiplicationOperation}) = 0.0 * im
 
-group_log!(G::CircleGroup, X::AbstractVector, q::AbstractVector) = (X .= group_log(G, q))
+_log_lie!(G::CircleGroup, X, q) = (X .= log_lie(G, q))

src/groups/connections.jl

@@ -65,7 +65,7 @@ function exp!(
     X,
 ) where {𝔽}
     Y = inverse_translate_diff(M.manifold, q, p, X)
-    return compose!(M.manifold, q, p, group_exp(M.manifold, Y))
+    return compose!(M.manifold, q, p, exp_lie(M.manifold, Y))
 end
 
 """
@@ -87,8 +87,8 @@ function log!(
     q,
 ) where {𝔽}
     pinvq = compose(M.manifold, inv(M.manifold, p), q)
-    group_log!(M.manifold, Y, pinvq)
-    return translate_diff!(M.manifold, Y, p, Identity(M.manifold, p), Y)
+    log_lie!(M.manifold, Y, pinvq)
+    return translate_diff!(M.manifold, Y, p, Identity(M.manifold), Y)
 end
 
 """
@@ -156,7 +156,7 @@ function vector_transport_direction!(
     d,
     ::ParallelTransport,
 )
-    dexp_half = group_exp(M.manifold, d / 2)
+    dexp_half = exp_lie(M.manifold, d / 2)
     translate_diff!(M.manifold, Y, dexp_half, p, X, RightAction())
     return translate_diff!(M.manifold, Y, dexp_half, p, Y, LeftAction())
 end
@@ -177,6 +177,6 @@ function vector_transport_to!(
     q,
     m::ParallelTransport,
 )
-    d = group_log(M.manifold, q)
+    d = log_lie(M.manifold, q)
     return vector_transport_direction!(M, Y, p, X, d, m)
 end

src/groups/general_linear.jl

@@ -37,9 +37,13 @@ function check_point(G::GeneralLinear, p; kwargs...)
     end
     return nothing
 end
-check_point(::GT, ::Identity{GT}; kwargs...) where {GT<:GeneralLinear} = nothing
-function check_point(G::GeneralLinear, e::Identity; kwargs...)
-    return DomainError(e, "The identity element $(e) does not belong to $(G).")
+check_point(::GeneralLinear, ::Identity{MultiplicationOperation}) = nothing
+function check_point(
+    G::GeneralLinear,
+    e::Identity{O};
+    kwargs...,
+) where {O<:AbstractGroupOperation}
+    return invoke(check_point, Tuple{AbstractGroupManifold,typeof(e)}, G, e; kwargs...)
 end
 
 function check_vector(G::GeneralLinear, p, X; kwargs...)
@@ -146,13 +150,13 @@ function get_vector!(
     return copyto!(X, Xⁱ)
 end
 
-function group_exp!(::GeneralLinear{1}, q, X)
+function exp_lie!(::GeneralLinear{1}, q, X)
     q[1] = exp(X[1])
     return q
 end
-group_exp!(::GeneralLinear{2}, q, X) = copyto!(q, exp(SizedMatrix{2,2}(X)))
+exp_lie!(::GeneralLinear{2}, q, X) = copyto!(q, exp(SizedMatrix{2,2}(X)))
 
-function group_log!(::GeneralLinear{1}, X::AbstractMatrix, p::AbstractMatrix)
+function _log_lie!(::GeneralLinear{1}, X, p)
     X[1] = log(p[1])
     return X
 end
@@ -198,7 +202,6 @@ log(::GeneralLinear, p, q)
 function log!(G::GeneralLinear{n,𝔽}, X, p, q) where {n,𝔽}
     pinvq = inverse_translate(G, p, q, LeftAction())
     𝔽 === ℝ && det(pinvq) ≤ 0 && throw(OutOfInjectivityRadiusError())
-    e = Identity(G, pinvq)
     if isnormal(pinvq; atol=sqrt(eps(real(eltype(pinvq)))))
         log_safe!(X, pinvq)
     else
@@ -207,13 +210,12 @@ function log!(G::GeneralLinear{n,𝔽}, X, p, q) where {n,𝔽}
         Gᵣ = GeneralLinear(real_dimension(𝔽) * n, ℝ)
         pinvqᵣ = realify(pinvq, 𝔽)
         Xᵣ = realify(X, 𝔽)
-        eᵣ = Identity(Gᵣ, pinvqᵣ)
         log_safe!(Xᵣ, _project_Un_S⁺(pinvqᵣ))
         inverse_retraction = NLsolveInverseRetraction(ExponentialRetraction(), Xᵣ)
-        inverse_retract!(Gᵣ, Xᵣ, eᵣ, pinvqᵣ, inverse_retraction)
+        inverse_retract!(Gᵣ, Xᵣ, Identity(G), pinvqᵣ, inverse_retraction)
         unrealify!(X, Xᵣ, 𝔽, n)
     end
-    translate_diff!(G, X, p, e, X, LeftAction())
+    translate_diff!(G, X, p, Identity(G), X, LeftAction())
     return X
 end
 function log!(::GeneralLinear{1}, X, p, q)