renamed gap_perm to perm and removed all gap_perm references (#1458)

* renamed gap_perm to perm and removed all gap_perm references

* moved documentation

* deprecate gap_perm

* reformat

docs/src/Groups/permgroup.md

@@ -36,70 +36,14 @@ degree(x::PermGroup)
 
 ## Permutations
 
-Permutations in Oscar are displayed as products of disjoint cycles, as in GAP. An explicit permutation can be built using the functions `perm`, `gap_perm`, `cperm`, or `@perm`.
+Permutations in Oscar are displayed as products of disjoint cycles, as in GAP. An explicit permutation can be built using the functions `perm`, `cperm`, or `@perm`.
 
 ```@docs
 perm
-gap_perm
 cperm
 @perm
 ```
 
-Every permutation has always a permutation group as a parent. Two permutations coincide if, and only if, they move the same points and their parent groups have the same degree.
-```jldoctest
-julia> G=symmetric_group(5);
-
-julia> A=alternating_group(5);
-
-julia> x=cperm(G,[1,2,3]);
-
-julia> y=cperm(A,[1,2,3]);
-
-julia> z=cperm([1,2,3]); parent(z)
-Sym( [ 1 .. 3 ] )
-
-julia> x==y
-true
-
-julia> x==z
-false
-```
-In the example above, `x` and `y` are equal because both act on a set of cardinality `5`, while `x` and `z` are different because `x` belongs to `Sym(5)` and `z` belongs to `Sym(3)`.
-
-One can also create permutation group elements with the following syntax
-```jldoctest
-julia> G=symmetric_group(6)
-Sym( [ 1 .. 6 ] )
-
-julia> G([2,4,6,1,3,5])
-(1,2,4)(3,6,5)
-```
-
-Here `G` is the parent group. 
-```jldoctest
-julia> G=symmetric_group(6)
-Sym( [ 1 .. 6 ] )
-
-julia> x=G([2,4,6,1,3,5])
-(1,2,4)(3,6,5)
-
-julia> y=perm(G,[2,4,6,1,3,5])
-(1,2,4)(3,6,5)
-
-julia> x==y
-true
-```
-If `G` is a group and `x` is a permutation,
-`G(x)` returns a permutation `x` with parent `G`;
-an exception is thrown if `x` does not embed into `G`.
-```@repl oscar
-G=symmetric_group(5);
-x=cperm([1,2,3]);
-y=G(x);
-parent(x)
-parent(y)
-```
-
 The function `Vector{T}` works in the opposite way with respect to `perm`:
 ```@docs
 Vector(x::PermGroupElem, n::Int = x.parent.deg)

src/Groups/GAPGroups.jl

@@ -24,7 +24,6 @@ export
     has_exponent, set_exponent,
     fitting_subgroup, has_fitting_subgroup, set_fitting_subgroup,
     frattini_subgroup, has_frattini_subgroup, set_frattini_subgroup,
-    gap_perm, # HACK
     gen,
     gens, has_gens,
     hall_subgroup,
@@ -57,6 +56,7 @@ export
     one!,
     order, has_order, set_order,
     pcore,
+    perm,
     radical_subgroup, has_radical_subgroup, set_radical_subgroup,
     rand_pseudo,
     relators,

src/Groups/libraries/primitivegroups.jl

@@ -145,7 +145,7 @@ true
 julia> primitive_group_identification(symmetric_group(4096))
 ERROR: identification of primitive permutation groups of degree 4096 is not available
 
-julia> S = sub(G, [gap_perm([1,3,4,5,2,7,6])])[1];
+julia> S = sub(G, [perm([1,3,4,5,2,7,6])])[1];
 
 julia> primitive_group_identification(S)
 ERROR: group is not primitive on its moved points

src/Groups/libraries/transitivegroups.jl

@@ -123,7 +123,7 @@ julia> G = symmetric_group(7);  m = transitive_group_identification(G)
 julia> order(transitive_group(m...)) == order(G)
 true
 
-julia> S = sub(G, [gap_perm([1, 3, 4, 5, 2])])[1]
+julia> S = sub(G, [perm([1, 3, 4, 5, 2])])[1]
 Group([ (2,3,4,5) ])
 
 julia> is_transitive(S)
@@ -141,7 +141,7 @@ true
 julia> transitive_group_identification(symmetric_group(64))
 ERROR: identification of transitive groups of degree 64 are not available
 
-julia> S = sub(G, [gap_perm([1,3,4,5,2,7,6])])[1];
+julia> S = sub(G, [perm([1,3,4,5,2,7,6])])[1];
 
 julia> transitive_group_identification(S)
 ERROR: group is not transitive on its moved points

src/Groups/perm.jl

@@ -101,43 +101,41 @@ julia> number_moved_points(gen(s, 1))
 
 number_moved_points(::Type{T}, x::Union{PermGroupElem,PermGroup}) where T <: IntegerUnion = T(GAP.Globals.NrMovedPoints(x.X))::T
 
-# FIXME: clashes with AbstractAlgebra.perm method
-#function perm(L::AbstractVector{<:IntegerUnion})
-#   return PermGroupElem(symmetric_group(length(L)), GAP.Globals.PermList(GAP.GapObj(L;recursive=true)))
-#end
-# FIXME: use name gap_perm for now
 @doc Markdown.doc"""
-    gap_perm(L::AbstractVector{<:IntegerUnion})
+    perm(L::AbstractVector{<:IntegerUnion})
 
 Return the permutation $x$ which maps every $i$ from `1` to $n$` = length(L)`
 to `L`$[i]$.
 The parent of $x$ is set to [`symmetric_group`](@ref)$(n)$.
 An exception is thrown if `L` does not contain every integer from 1 to $n$
 exactly once.
 
+The parent group of $x$ is set to [`symmetric_group`](@ref)$(n)$.
+
 # Examples
 ```jldoctest
-julia> gap_perm([2,4,6,1,3,5])
+julia> x = perm([2,4,6,1,3,5])
 (1,2,4)(3,6,5)
+
+julia> parent(x)
+Sym( [ 1 .. 6 ] )
 ```
 """
-function gap_perm(L::AbstractVector{<:IntegerUnion})
+function perm(L::AbstractVector{<:IntegerUnion})
   return PermGroupElem(symmetric_group(length(L)), GAP.Globals.PermList(GAP.GapObj(L;recursive=true)))
 end
 
+@deprecate gap_perm(L::AbstractVector{<:IntegerUnion}) perm(L::AbstractVector{<:IntegerUnion})
+
 @doc Markdown.doc"""
     perm(G::PermGroup, L::AbstractVector{<:IntegerUnion})
     (G::PermGroup)(L::AbstractVector{<:IntegerUnion})
 
 Return the permutation $x$ which maps every `i` from 1 to $n$` = length(L)`
-to `L`$[i]$.
-The parent of $x$ is `G`.
+to `L`$[i]$. The parent of $x$ is `G`.
 An exception is thrown if $x$ is not contained in `G`
 or `L` does not contain every integer from 1 to $n$ exactly once.
 
-For [`gap_perm`](@ref),
-the parent group of $x$ is set to [`symmetric_group`](@ref)$(n)$.
-
 # Examples
 ```jldoctest
 julia> perm(symmetric_group(6),[2,4,6,1,3,5])
@@ -181,17 +179,6 @@ function (g::PermGroup)(L::AbstractVector{<:IntegerUnion})
    throw(ArgumentError("the element does not embed in the group"))
 end
 
-@doc Markdown.doc"""
-Functor to construct permutations with a given parent group
-
-# Examples
-```jldoctest
-julia> G = symmetric_group(6)
-Sym( [ 1 .. 6 ] )
-julia> x = G([2,4,6,1,3,5])
-(1,2,4)(3,6,5)
-```
-"""
 (g::PermGroup)(L::AbstractVector{<:fmpz}) = g([Int(y) for y in L])
 
 # cperm stands for "cycle permutation", but we can change name if we want
@@ -230,6 +217,27 @@ julia> degree(parent(p))
 7
 ```
 
+Two permutations coincide if, and only if, they move the same points and their parent groups have the same degree.
+```jldoctest
+julia> G=symmetric_group(5);
+
+julia> A=alternating_group(5);
+
+julia> x=cperm(G,[1,2,3]);
+
+julia> y=cperm(A,[1,2,3]);
+
+julia> z=cperm([1,2,3]); parent(z)
+Sym( [ 1 .. 3 ] )
+
+julia> x==y
+true
+
+julia> x==z
+false
+```
+In the example above, `x` and `y` are equal because both act on a set of cardinality `5`, while `x` and `z` are different because `x` belongs to `Sym(5)` and `z` belongs to `Sym(3)`.
+
 cperm can also handle cycles passed in inside of a vector
 ```jldoctest
 julia> x = cperm([[1,2],[3,4]])
@@ -273,14 +281,6 @@ true
 
 At the moment, the input vectors of the function `cperm` need not be disjoint.
 
-!!! warning
-    If the function `perm` is evaluated in a vector of integers
-    without specifying the group `G`,
-    then the returned value is an element of the AbstractAlgebra.jl type
-    `Perm{Int}`.
-    For this reason, if one wants a permutation of type
-    `GAPGroupElem{PermGroup}` without specifying a parent,
-    one has to use the function `gap_perm`.
 """
 function cperm(L::AbstractVector{T}...) where T <: IntegerUnion
    if length(L)==0

src/Groups/types.jl

@@ -83,6 +83,42 @@ Every group of this type is the subgroup of Sym(n) for some n.
 - `dihedral_group(PermGroup, n::Int)`:
   the dihedral group of order `n` as a group of permutations.
   Same holds replacing `dihedral_group` by `quaternion_group`
+
+If `G` is a group and `x` is a permutation,
+`G(x)` returns a permutation `x` with parent `G`;
+an exception is thrown if `x` does not embed into `G`.
+```jldoctest
+julia> G=symmetric_group(5)
+Sym( [ 1 .. 5 ] )
+
+julia> x=cperm([1,2,3])
+(1,2,3)
+
+julia> parent(x)
+Sym( [ 1 .. 3 ] )
+
+julia> y=G(x)
+(1,2,3)
+
+julia> parent(y)
+Sym( [ 1 .. 5 ] )
+```
+
+If `G` is a group and `L` is a vector of integers,
+`G(x)` returns a [`PermGroupElem`](@ref) with parent `G`;
+an exception is thrown if the element does not embed into `G`.
+
+# Examples
+```jldoctest
+julia> G = symmetric_group(6)
+Sym( [ 1 .. 6 ] )
+
+julia> x = G([2,4,6,1,3,5])
+(1,2,4)(3,6,5)
+
+julia> parent(x)
+Sym( [ 1 .. 6 ] )
+```
 """
 @attributes mutable struct PermGroup <: GAPGroup
    X::GapObj

src/imports.jl

@@ -147,7 +147,7 @@ import Nemo:
     ZZ
 
 exclude = [:Nemo, :AbstractAlgebra, :Rational, :change_uniformizer, :genus_symbol, :data,
-    :narrow_class_group]
+    :narrow_class_group, :perm]
 
 for i in names(Hecke)
   i in exclude && continue
@@ -217,7 +217,6 @@ import Hecke:
     nrows,
     one!,
     order,
-    perm,
     preimage,
     primitive_element,
     quo,

test/Groups/elements.jl

@@ -34,19 +34,19 @@
   end
 
   G=symmetric_group(6)
-  x=gap_perm([2,3,4,5,6,1])
-  @test x==gap_perm(Int8[2,3,4,5,6,1])
-  @test x==gap_perm(fmpz[2,3,4,5,6,1])
+  x=perm([2,3,4,5,6,1])
+  @test x==perm(Int8[2,3,4,5,6,1])
+  @test x==perm(fmpz[2,3,4,5,6,1])
   @test x==perm(G,[2,3,4,5,6,1])
   @test x==perm(G,Int8[2,3,4,5,6,1])
   @test x==perm(G,fmpz[2,3,4,5,6,1])
   @test cperm(G,Int[])==one(G)
   @test x==cperm(G,1:6)
   @test x==cperm(G,[1,2,3,4,5,6])
-  @test one(G)==gap_perm(1:6)
-  @test_throws ArgumentError G(gap_perm([2,3,4,5,6,7,1]))
+  @test one(G)==perm(1:6)
+  @test_throws ArgumentError G(perm([2,3,4,5,6,7,1]))
   @test_throws ArgumentError G([2,3,1,4,6,5,7])
-  @test G(gap_perm([2,3,1,4,6,5,7]))==gap_perm([2,3,1,4,6,5])
+  @test G(perm([2,3,1,4,6,5,7]))==perm([2,3,1,4,6,5])
   @test_throws ArgumentError perm(G,[2,3,4,5,6,7,1])
   @test_throws ArgumentError perm(G, [1,1])
   @test one(G)==cperm(G,Int64[])