add isomorphic_subgroups (#4401)

and add missing `is_isomorphic` method for `FinGenAbGroup`

docs/src/Groups/grouphom.md

@@ -161,6 +161,7 @@ and the codomain is some new group constructed by the function.
 is_isomorphic(G::GAPGroup, H::GAPGroup)
 is_isomorphic_with_map(G::GAPGroup, H::GAPGroup)
 isomorphism(G::GAPGroup, H::GAPGroup)
+isomorphic_subgroups(H::GAPGroup, G::GAPGroup)
 ```
 
 ```@docs

docs/src/Groups/subgroups.md

@@ -45,15 +45,15 @@ normal_subgroups
 maximal_normal_subgroups
 minimal_normal_subgroups
 characteristic_subgroups
-derived_series
+derived_series(G::GAPGroup)
 sylow_system
 hall_system
 complement_system
 chief_series
 composition_series
 jennings_series
 p_central_series
-lower_central_series
+lower_central_series(G::GAPGroup)
 upper_central_series
 ```
 

src/GAP/wrappers.jl

@@ -222,6 +222,7 @@ GAP.@wrap IsNilpotentGroup(x::Any)::Bool
 GAP.@wrap IsNormal(x::Any, y::Any)::Bool
 GAP.@wrap IsNumberField(x::Any)::Bool
 GAP.@wrap IsNumberFieldByMatrices(x::Any)::Bool
+GAP.@wrap IsomorphicSubgroups(x::GapObj, y::GapObj)::GapObj
 GAP.@wrap IsomorphismFpGroup(x::GapObj)::GapObj
 GAP.@wrap IsomorphismFpGroupByGenerators(x::GapObj, y::GapObj)::GapObj
 GAP.@wrap IsomorphismFpGroupByPcgs(x::GapObj, y::GapObj)::GapObj

src/Groups/homomorphisms.jl

@@ -436,6 +436,16 @@ function is_isomorphic(G::MultTableGroup, H::GAPGroup)
   return is_isomorphic(P, H)
 end
 
+function is_isomorphic(G::GAPGroup, H::FinGenAbGroup)
+  is_abelian(G) || return false
+  return abelian_invariants(G) == abelian_invariants(H)
+end
+
+function is_isomorphic(G::FinGenAbGroup, H::GAPGroup)
+  is_abelian(H) || return false
+  return abelian_invariants(G) == abelian_invariants(H)
+end
+
 """
     isomorphism(G::Group, H::Group)
 
@@ -472,6 +482,48 @@ function isomorphism(G::MultTableGroup, H::GAPGroup)
   return GtoP * PtoH
 end
 
+"""
+    isomorphic_subgroups(H::Group, G::Group)
+
+Return a vector of injective group homomorphism from `H` to `G`,
+where the images are representatives of those conjugacy classes
+of subgroups of `G` that are isomorphic with `H`.
+
+# Examples
+```jldoctest
+julia> isomorphic_subgroups(alternating_group(5), alternating_group(6))
+2-element Vector{GAPGroupHomomorphism{PermGroup, PermGroup}}:
+ Hom: Alt(5) -> Alt(6)
+ Hom: Alt(5) -> Alt(6)
+
+julia> isomorphic_subgroups(symmetric_group(4), alternating_group(5))
+GAPGroupHomomorphism{PermGroup, PermGroup}[]
+```
+"""
+function isomorphic_subgroups(H::GAPGroup, G::GAPGroup)
+  res = GAPWrap.IsomorphicSubgroups(GapObj(G), GapObj(H))
+  return [GAPGroupHomomorphism(H, G, x) for x in res]
+end
+
+function isomorphic_subgroups(H::FinGenAbGroup, G::GAPGroup)
+  isoH = isomorphism(PcGroup, H)
+  res = isomorphic_subgroups(codomain(isoH), G)
+  return [isoH*x for x in res]
+end
+
+function isomorphic_subgroups(H::GAPGroup, G::FinGenAbGroup)
+  isoG = inv(isomorphism(PcGroup, G))
+  res = isomorphic_subgroups(H, domain(isoG))
+  return [x*isoG for x in res]
+end
+
+function isomorphic_subgroups(H::FinGenAbGroup, G::FinGenAbGroup)
+  isoH = isomorphism(PcGroup, H)
+  isoG = inv(isomorphism(PcGroup, G))
+  res = isomorphic_subgroups(codomain(isoH), domain(isoG))
+  return [isoH*x*isoG for x in res]
+end
+
 ################################################################################
 #
 #  Conversions between types

src/exports.jl

@@ -951,6 +951,7 @@ export is_zm_graded
 export isfinite
 export isometry_group
 export isomorphic_matroid
+export isomorphic_subgroups
 export isomorphism
 export isone
 export isqrtrem

test/Groups/homomorphisms.jl

@@ -482,6 +482,29 @@ end
        @test FPGroup(G) isa FPGroup
        @test_throws ArgumentError FinGenAbGroup(G)
    end
+
+   # isomorphic subgroups
+   types = [PermGroup, PcGroup, FPGroup]
+   for T in types, S in types
+     G = codomain(isomorphism(T, symmetric_group(4)))
+     H = codomain(isomorphism(S, symmetric_group(3)))
+     res = @inferred isomorphic_subgroups(H, G)
+     @test length(res) == 1
+     @test domain(res[1]) === H
+     @test codomain(res[1]) === G
+     @test is_isomorphic(H, image(res[1])[1])
+   end
+   types = [PermGroup, SubPcGroup, FPGroup, FinGenAbGroup]
+   for T in types, S in types
+     G = abelian_group(T, [2, 4])
+     H = abelian_group(S, [2, 2])
+     res = @inferred isomorphic_subgroups(H, G)
+     @test length(res) == 1
+     @test domain(res[1]) === H
+     @test codomain(res[1]) === G
+     @test (T === FinGenAbGroup) || is_isomorphic(H, image(res[1])[1])
+#TODO make image work for embedding into FinGenAbGroup?
+   end
 end
 
 @testset "Homomorphism GAPGroup to FinGenAbGroup" begin