Add image and preimage to generic Map types (#2095)

* Add image and preimage to Map types
* Add (pre)image for IdentityMap
* Add image for MapCache
* Add tests for (pre)image functions

Author: jamesnohilly

src/generic/Map.jl

@@ -16,7 +16,11 @@ map1(f::CompositeMap) = f.map1
 map2(f::CompositeMap) = f.map2
 
 function (f::CompositeMap{D, C})(a) where {D, C}
-   return f.map2(f.map1(a))::elem_type(C)
+  return image(f, a)::elem_type(C)
+end
+
+function image(f::Generic.CompositeMap{D, C}, a) where {D, C}
+  return f.map2(f.map1(a))::elem_type(C)
 end
 
 function preimage(f::Generic.CompositeMap{D, C}, a) where {D, C}
@@ -50,7 +54,10 @@ end
 #
 ################################################################################
 
-(f::IdentityMap)(a) = a
+(f::IdentityMap)(a) = image(f, a)
+
+image(f::IdentityMap, a) = a
+preimage(f::IdentityMap, a) = a
 
 domain(f::IdentityMap) = f.domain
 codomain(f::IdentityMap) = f.domain
@@ -106,10 +113,13 @@ codomain(f::FunctionalMap) = f.codomain
 image_fn(f::FunctionalMap) = f.image_fn
 
 function (f::FunctionalMap{D, C})(a) where {D, C}
-   parent(a) != domain(f) && throw(DomainError(f))
-   return image_fn(f)(a)::elem_type(C)
+  return image(f, a)::elem_type(C)
 end
 
+function image(f::FunctionalMap{D, C}, a) where {D, C}
+  parent(a) != domain(f) && throw(DomainError(f))
+  return image_fn(f)(a)::elem_type(C)
+end
 
 function Base.show(io::IO, M::FunctionalMap)
    if is_terse(io)
@@ -164,7 +174,11 @@ map1(f::FunctionalCompositeMap) = f.map1
 map2(f::FunctionalCompositeMap) = f.map2
 
 function (f::FunctionalCompositeMap{D, C})(a) where {D, C}
-   return image_fn(f)(a)::elem_type(C)
+  return image(f, a)::elem_type(C)
+end
+
+function image(f::FunctionalCompositeMap{D, C}, a) where {D, C}
+  return image_fn(f)(a)::elem_type(C)
 end
 
 function show(io::IO, M::FunctionalCompositeMap)

src/generic/MapCache.jl

@@ -26,21 +26,23 @@ function disable_cache!(M::MapCache)
    nothing
 end
 
-function (M::MapCache{D, C, S, T, De, Ce})(a::De) where {D, C, S, T, De, Ce}
-   if M.enabled
-      if haskey(M.image_cache, a)
-         return M.image_cache[a]::Ce
-      else
-         b = M.map(a)
-         if M.limit > 0
-            M.image_cache[a] = b
-            M.limit -= 1
-         end
-         return b::Ce
+(M::MapCache{D, C, S, T, De, Ce})(a::De) where {D, C, S, T, De, Ce} = image(M, a)
+
+function image(M::MapCache{D, C, S, T, De, Ce}, a::De) where {D, C, S, T, De, Ce}
+  if M.enabled
+    if haskey(M.image_cache, a)
+      return M.image_cache[a]::Ce
+    else
+      b = M.map(a)
+      if M.limit > 0
+          M.image_cache[a] = b
+          M.limit -= 1
       end
-   else
+      return b::Ce
+    end
+  else
       return M.map(a)::Ce
-   end
+  end
 end
 
 show(io::IO, M::MapCache) = show(M.map)

src/generic/MapWithInverse.jl

@@ -19,8 +19,15 @@ image_map(f::MapWithSection) = f.map
 preimage_map(f::MapWithSection) = f.section # for convenience only
 section_map(f::MapWithSection) = f.section
 
-(f::MapWithSection{D, C})(a) where {D, C} = (f.map)(a)::elem_type(C)
+(f::MapWithSection{D, C})(a) where {D, C} = image(f, a)::elem_type(C)
 
+function preimage(f::MapWithSection{D, C}, a) where {D, C}
+  return inverse_fn(f)(a)::elem_type(D)
+end
+
+function image(f::MapWithSection{D, C}, a) where {D, C}
+  return image_fn(f)(a)::elem_type(C)
+end
 
 function Base.show(io::IO, M::MapWithSection)
    if is_terse(io)
@@ -64,7 +71,15 @@ retraction_map(f::MapWithRetraction) = f.retraction
 
 retraction_map(f::MapCache) = retraction_map(f.map)
 
-(f::MapWithRetraction{D, C})(a) where {D, C} = (f.map)(a)::elem_type(C)
+(f::MapWithRetraction{D, C})(a) where {D, C} = image(f, a)::elem_type(C)
+
+function preimage(f::MapWithRetraction{D, C}, a) where {D, C}
+  return inverse_fn(f)(a)::elem_type(D)
+end
+
+function image(f::MapWithRetraction{D, C}, a) where {D, C}
+  return image_fn(f)(a)::elem_type(C)
+end
 
 function Base.show(io::IO, M::MapWithRetraction)
    if is_terse(io)

src/generic/imports.jl

@@ -139,6 +139,7 @@ import ..AbstractAlgebra: gens
 import ..AbstractAlgebra: get_cached!
 import ..AbstractAlgebra: hom
 import ..AbstractAlgebra: identity_matrix
+import ..AbstractAlgebra: image
 import ..AbstractAlgebra: image_fn
 import ..AbstractAlgebra: inflate
 import ..AbstractAlgebra: integral

test/generic/Map-test.jl

@@ -26,6 +26,9 @@ end
    @test domain(g) == AbstractAlgebra.JuliaZZ
    @test codomain(g) == AbstractAlgebra.JuliaQQ
 
+   @test image(f, ZZ(1)) == 2
+   @test image(g, ZZ(2)) == QQ(2)
+
    @test image_fn(f)(ZZ(1)) == 2
    @test image_fn(g)(ZZ(2)) == QQ(2)
 end
@@ -43,11 +46,13 @@ end
 
    for i in 1:10
       @test h(ZZ(i)) == k(ZZ(i))
+      @test image(h, ZZ(i)) == image(k, ZZ(i))
    end
 
    @test domain(h) == AbstractAlgebra.JuliaZZ
    @test codomain(h) == AbstractAlgebra.JuliaQQ
 
+   @test image(h, ZZ(1)) == QQ(2)
    @test image_fn(h)(ZZ(1)) == QQ(2)
 
    @test map1(h) === f
@@ -65,6 +70,7 @@ end
 
    for i in 1:10
       @test t(ZZ(i)) == 2*(i + 2)
+      @test image(t, ZZ(i)) == 2*(i + 2)
    end
 
    @test domain(t) == AbstractAlgebra.JuliaZZ
@@ -100,6 +106,8 @@ end
    for i = 1:10
       @test g(ZZ(i)) == ZZ(i)
       @test h(ZZ(i)//(i + 1)) == ZZ(i)//(i + 1)
+      @test image(g, ZZ(i)) == ZZ(i)
+      @test image(h, ZZ(i)//(i + 1)) == ZZ(i)//(i + 1)
    end
 
    @test compose(g, g) === g

test/generic/MapCache-test.jl

@@ -8,48 +8,62 @@
    @test isa(h, Map(Generic.MapCache))
 
    @test f(ZZ(1)) == 2
+   @test image(f, ZZ(1)) == 2
 
    for i = 1:10
       @test g(ZZ(i)) == QQ(i)
+      @test image(g, ZZ(i)) == QQ(i)
    end
 
    @test h(ZZ(1)) == 3
+   @test image(h, ZZ(1)) == 3
 
    @test domain(f) == AbstractAlgebra.JuliaZZ
    @test codomain(g) == AbstractAlgebra.JuliaQQ
    @test domain(h) == AbstractAlgebra.JuliaZZ
 
+   @test image(f, ZZ(1)) == 2
    @test image_fn(f)(ZZ(1)) == 2
 end
 
 @testset "Generic.MapCache.enable_disable" begin
    f = cached(map_from_func(x -> x + 1, ZZ, ZZ))
 
    @test f(ZZ(1)) == 2
+   @test image(f, ZZ(1)) == 2
 
    disable_cache!(f)
 
    @test f(ZZ(1)) == 2
    @test f(ZZ(2)) == 3
+   @test image(f, ZZ(1)) == 2
+   @test image(f, ZZ(2)) == 3
 
    enable_cache!(f)
 
    @test f(ZZ(1)) == 2
    @test f(ZZ(3)) == 4
+   @test image(f, ZZ(1)) == 2
+   @test image(f, ZZ(3)) == 4
 
    g = cached(map_from_func(x -> x + 1, ZZ, ZZ), enabled=false)
 
    @test g(ZZ(1)) == 2
+   @test image(g, ZZ(1)) == 2
 
    enable_cache!(g)
 
    @test g(ZZ(1)) == 2
    @test g(ZZ(2)) == 3
+   @test image(g, ZZ(1)) == 2
+   @test image(g, ZZ(2)) == 3
 
    disable_cache!(g)
 
    @test g(ZZ(1)) == 2
    @test g(ZZ(3)) == 4
+   @test image(g, ZZ(1)) == 2
+   @test image(g, ZZ(3)) == 4
 end
 
 @testset "Generic.MapCache.limit" begin
@@ -59,5 +73,6 @@ end
 
    for i = 1:10
       @test g(ZZ(i)) == QQ(i)
+      @test image(g, ZZ(i)) == QQ(i)
    end
 end

test/generic/MapWithInverse-test.jl

@@ -9,6 +9,9 @@ import AbstractAlgebra.PrettyPrinting
    @test domain(s) == AbstractAlgebra.JuliaZZ
    @test codomain(s) == AbstractAlgebra.JuliaZZ
 
+   @test image(s, ZZ(1)) == 2
+   @test preimage(s, ZZ(1)) == 0
+
    @test image_fn(s)(ZZ(1)) == 2
    @test inverse_fn(s)(ZZ(1)) == 0
 
@@ -22,6 +25,9 @@ import AbstractAlgebra.PrettyPrinting
    @test domain(t) == AbstractAlgebra.JuliaZZ
    @test codomain(t) == AbstractAlgebra.JuliaZZ
 
+   @test image(t, ZZ(1)) == 2
+   @test preimage(t, ZZ(1)) == 0
+
    @test image_fn(t)(ZZ(1)) == 2
    @test inverse_fn(t)(ZZ(1)) == 0
 
@@ -34,9 +40,15 @@ import AbstractAlgebra.PrettyPrinting
 
    @test u(ZZ(1)) == 2
 
+   @test image(u, ZZ(1)) == 2
+   @test preimage(u, ZZ(1)) == 0
+
    v = map_with_section_from_func(x -> x + 1, x -> x - 1, ZZ, ZZ)
 
    @test u(ZZ(1)) == 2
+
+   @test image(v, ZZ(1)) == 2
+   @test preimage(v, ZZ(1)) == 0
 end
 
 @testset "Generic.MapWithInverse.composition" begin
@@ -52,12 +64,18 @@ end
 
    @test u(ZZ(1)) == 4
 
+   @test image(u, ZZ(1)) == 4
+   @test preimage(u, ZZ(4)) == 1
+
    s = map_with_retraction(f, g)
    t = map_with_retraction(h, k)
 
    u = compose(s, t)
 
    @test u(ZZ(1)) == 4
+
+   @test image(u, ZZ(1)) == 4
+   @test preimage(u, ZZ(4)) == 1
 end
 
 @testset "Generic.MapWithInverse.inv" begin
@@ -77,6 +95,11 @@ end
    @test v(ZZ(1)) == -2
    @test w(ZZ(1)) == 0
 
+   @test image(v, ZZ(1)) == -2
+   @test image(w, ZZ(1)) == 0
+   @test preimage(v, ZZ(-2)) == 1
+   @test preimage(w, ZZ(0)) == 1
+
    s = map_with_retraction(f, g)
    t = map_with_retraction(h, k)
 
@@ -87,6 +110,11 @@ end
 
    @test v(ZZ(1)) == -2
    @test w(ZZ(1)) == 0
+
+   @test image(v, ZZ(1)) == -2
+   @test image(w, ZZ(1)) == 0
+   @test preimage(v, ZZ(-2)) == 1
+   @test preimage(w, ZZ(0)) == 1
 end
 
 @testset "Generic.MapWithInverse.printing" begin