From 417fceaef8bdaa92a718aa207c6847270f84c8a6 Mon Sep 17 00:00:00 2001
From: ThomasBreuer <sam@math.rwth-aachen.de>
Date: Wed, 31 Jan 2024 11:12:03 +0100
Subject: [PATCH] add `is_conjugate_subgroup_with_data`

and changed `is_conjugate_subgroup` to return only `true` or `false`
---
 src/Groups/GAPGroups.jl    | 46 +++++++++++++++++++++++++++++++++-----
 src/Groups/GrpAb.jl        |  2 +-
 src/exports.jl             |  1 +
 test/Groups/GrpAb.jl       |  3 ++-
 test/Groups/conjugation.jl |  4 ++++
 5 files changed, 49 insertions(+), 7 deletions(-)

diff --git a/src/Groups/GAPGroups.jl b/src/Groups/GAPGroups.jl
index 81e7baad77ee..54f1e793ef42 100644
--- a/src/Groups/GAPGroups.jl
+++ b/src/Groups/GAPGroups.jl
@@ -907,7 +907,14 @@ end
 """
     is_conjugate_subgroup(G::T, U::T, V::T) where T <: GAPGroup
 
-Return whether a conjugate of `V` by some element in `G` is a subgroup of `U`.
+Return `true` if a conjugate of `V` by some element in `G` is a subgroup of `U`,
+and `false` otherwise.
+
+If one needs a conjugating element then one can use
+ [`is_conjugate_subgroup_with_data`](@ref).
+
+In order to check whether `U` and `V` are conjugate in `G`.
+use [`is_conjugate`](@ref) or [`is_conjugate_with_data`](@ref).
 
 # Examples
 ```jldoctest
@@ -920,17 +927,46 @@ julia> V = sub(G, [G([2,1,3,4])])[1]
 Permutation group of degree 4
 
 julia> is_conjugate_subgroup(G, U, V)
-(false, ())
+false
 
 julia> V = sub(G, [G([2, 1, 4, 3])])[1]
 Permutation group of degree 4
 
 julia> is_conjugate_subgroup(G, U, V)
-(true, ())
+true
+```
+"""
+is_conjugate_subgroup(G::T, U::T, V::T) where T <: GAPGroup = is_conjugate_subgroup_with_data(G, U, V)[1]
+
+
+"""
+    is_conjugate_subgroup_with_data(G::T, U::T, V::T) where T <: GAPGroup
+
+If a conjugate of `V` by some element in `G` is a subgroup of `U`,
+return `true, z` where `V^z` is a subgroup of `U`;
+otherwise, return `false, one(G)`.
+
+# Examples
+```jldoctest
+julia> G = symmetric_group(4);
+
+julia> U = derived_subgroup(G)[1]
+Alt(4)
+
+julia> V = sub(G, [G([2,1,3,4])])[1]
+Permutation group of degree 4
+
+julia> is_conjugate_subgroup_with_data(G, U, V)
+(false, ())
 
+julia> V = sub(G, [G([2, 1, 4, 3])])[1]
+Permutation group of degree 4
+
+julia> is_conjugate_subgroup_with_data(G, U, V)
+(true, ())
 ```
 """
-function is_conjugate_subgroup(G::T, U::T, V::T) where T <: GAPGroup
+function is_conjugate_subgroup_with_data(G::T, U::T, V::T) where T <: GAPGroup
   if order(V) == 1
     return true, one(U)
   end
@@ -947,7 +983,7 @@ function is_conjugate_subgroup(G::T, U::T, V::T) where T <: GAPGroup
       return true, inv(t)
     end
   end
-  return false, one(U)
+  return false, one(G)
 end
 
 @doc raw"""
diff --git a/src/Groups/GrpAb.jl b/src/Groups/GrpAb.jl
index 91db7748455d..ec6e7dad364d 100644
--- a/src/Groups/GrpAb.jl
+++ b/src/Groups/GrpAb.jl
@@ -182,7 +182,7 @@ function is_conjugate_with_data(G::GrpAbFinGen, H::GrpAbFinGen, K::GrpAbFinGen)
 end
 
 is_conjugate_subgroup(G::T, U::T, V::T) where T <: GrpAbFinGen = is_subgroup(V, U)[1]
-
+is_conjugate_subgroup_with_data(G::T, U::T, V::T) where T <: GrpAbFinGen = is_subgroup(V, U)[1], zero(G)
 
 Base.IteratorSize(::Type{<:GrpAbFinGenConjClass}) = Base.HasLength()
 
diff --git a/src/exports.jl b/src/exports.jl
index 59edbc96145f..f8c32f87a510 100644
--- a/src/exports.jl
+++ b/src/exports.jl
@@ -735,6 +735,7 @@ export is_complete
 export is_congruent
 export is_conjugate
 export is_conjugate_subgroup
+export is_conjugate_subgroup_with_data
 export is_conjugate_with_data
 export is_connected
 export is_cyclic, has_is_cyclic, set_is_cyclic
diff --git a/test/Groups/GrpAb.jl b/test/Groups/GrpAb.jl
index 92da7cc94e02..64282559aadd 100644
--- a/test/Groups/GrpAb.jl
+++ b/test/Groups/GrpAb.jl
@@ -98,7 +98,8 @@ end
       K = representative(C2)
       @test is_conjugate(G1, H, K) == (H == K)
       @test is_conjugate_with_data(G1, H, K)[1] == (H == K)
-      @test is_conjugate_subgroup(G1, H, K) == is_subgroup(K, H)[1]
+      @test is_conjugate_subgroup(G1, H, K) == is_subset(K, H)
+      @test is_conjugate_subgroup_with_data(G1, H, K) == (is_subset(K, H), zero(G1))
     end
     C = CC[1]
     for H in C
diff --git a/test/Groups/conjugation.jl b/test/Groups/conjugation.jl
index e0a86780726d..c44d0ed0dd60 100644
--- a/test/Groups/conjugation.jl
+++ b/test/Groups/conjugation.jl
@@ -89,6 +89,10 @@
      @test is_conjugate_with_data(G,x,y)[1]
      z = is_conjugate_with_data(G,x,y)[2]
      @test x^z == y
+     @test is_conjugate_subgroup(G, x, y)
+     @test is_conjugate_subgroup_with_data(G, x, y)[1]
+     z = is_conjugate_subgroup_with_data(G,x,y)[2]
+     @test y^z == x
      y = rand(CC[(i % length(CC))+1])
      @test !is_conjugate(G,x,y)
      @test !is_conjugate_with_data(G,x,y)[1]