Add letters function for PcGroupElem

src/Groups/pcgroup.jl

@@ -415,7 +415,6 @@ function _GAP_collector_from_the_left(c::GAP_Collector)
   return cGAP::GapObj
 end
 
-
 # Create the collector on the GAP side on demand
 function underlying_gap_object(c::GAP_Collector)
   if ! isdefined(c, :X)
@@ -473,6 +472,110 @@ function pc_group(c::GAP_Collector)
   end
 end
 
+"""
+    letters(g::Union{PcGroupElem, SubPcGroupElem})
+
+Return the letters of `g` as a list of integers, each entry corresponding to
+a group generator.
+
+This method can produce letters represented by negative numbers. A negative number 
+indicates the inverse of the generator at the corresponding positive index.
+
+For example, as shown below, an output of -1 refers to the "inverse of the first generator".
+
+See also [`syllables`](@ref).
+
+```jldoctest
+julia> gg = small_group(6, 1)
+Pc group of order 6
+
+julia> x = gg([1 => ZZ(-3)])
+f1^-3
+
+julia> letters(x)
+3-element Vector{Int64}:
+ -1
+ -1
+ -1
+```
+
+# Examples
+
+```jldoctest
+julia> gg = small_group(6, 1)
+Pc group of order 6
+
+julia> x = gg[1]^5*gg[2]^-4
+f1*f2^2
+
+julia> letters(x)
+3-element Vector{Int64}:
+ 1
+ 2
+ 2
+```
+"""
+function letters(g::Union{PcGroupElem, SubPcGroupElem})
+  w = GAPWrap.UnderlyingElement(GapObj(g))
+  return Vector{Int}(GAPWrap.LetterRepAssocWord(w))
+end
+
+"""
+    syllables(g::Union{PcGroupElem, SubPcGroupElem})
+
+Return the syllables of `g` as a list of pairs of integers, each entry corresponding to
+a group generator and its exponent.
+
+# Examples
+```jldoctest
+julia> gg = small_group(6, 1)
+Pc group of order 6
+
+julia> x = gg[1]^5*gg[2]^-4
+f1*f2^2
+
+julia> s = syllables(x)
+2-element Vector{Pair{Int64, ZZRingElem}}:
+ 1 => 1
+ 2 => 2
+
+julia> gg(s)
+f1*f2^2
+
+julia> gg(s) == x
+true
+```
+"""
+function syllables(g::Union{PcGroupElem, SubPcGroupElem})
+  l = GAPWrap.ExtRepOfObj(GapObj(g))
+  @assert iseven(length(l))
+  return Pair{Int, ZZRingElem}[l[i-1] => l[i] for i = 2:2:length(l)]
+end
+
+# Convert syllables in canonical form into exponent vector
+function _exponent_vector(sylls::Vector{Pair{Int64, ZZRingElem}}, n)
+  res = zeros(ZZRingElem, n)
+  for pair in sylls
+    @assert res[pair.first] == 0 #just to make sure 
+    res[pair.first] = pair.second
+  end
+  return res
+end
+
+# Convert syllables in canonical form into group element
+function (G::PcGroup)(sylls::Vector{Pair{Int64, ZZRingElem}}; check::Bool=true)
+  # check if the syllables are in canonical form
+  if check
+    indices = map(p -> p.first, sylls)
+    @req allunique(indices) "given syllables have repeating generators"
+    @req issorted(indices) "given syllables must be in ascending order"
+  end
+
+  e = _exponent_vector(sylls, ngens(G))
+  pcgs = Oscar.GAPWrap.FamilyPcgs(GapObj(G))
+  x = Oscar.GAPWrap.PcElementByExponentsNC(pcgs, GapObj(e, true))
+  return Oscar.group_element(G, x)
+end
 
 # Create an Oscar collector from a GAP collector.
 

test/Groups/pcgroup.jl

@@ -83,6 +83,51 @@ end
   @test cgg !== c.X
 end
 
+@testset "generate letters from polycyclic group element" begin
+
+  # finite polycyclic groups
+  c = collector(2, Int);
+  set_relative_order!(c, 1, 2)
+  set_relative_order!(c, 2, 3)
+  set_power!(c, 1, [2 => 1])
+  gg = pc_group(c)
+  @test letters(gg[1]^5*gg[2]^-4) == [1, 2]
+  @test letters(gg[1]^5*gg[2]^4) == [1] # all positive exp
+  @test letters(gg[1]^-5*gg[2]^-7) == [1, 2, 2] # all negative exp
+  @test letters(gg[1]^2*gg[2]^3) == [2] # both identity elements
+
+  # finite polycyclic subgroup
+  gg = pc_group(symmetric_group(4))
+  G = derived_subgroup(gg)[1]
+  @test letters(G[1]^2) == [2, 2]
+  @test letters(G[1]^2*G[2]^3*G[3]^3) == [2, 2, 3, 4]
+  @test letters(G[1]^-2*G[2]^-3*G[3]^-3) == [2, 3, 4]
+end
+
+@testset "create polycyclic group element from syllables" begin
+
+  # finite polycyclic groups
+  c = collector(2, Int);
+  set_relative_order!(c, 1, 2)
+  set_relative_order!(c, 2, 3)
+  set_power!(c, 1, [2 => 1])
+  gg = pc_group(c)
+
+  element = gg[1]^5*gg[2]^-4
+  sylls = syllables(element)
+  @test sylls == [1 => ZZ(1), 2 => ZZ(1)] # check general usage
+  @test gg(sylls) == element # this will pass the check
+
+  sylls = [1 => ZZ(1), 2 => ZZ(2), 1 => ZZ(3)]
+  @test_throws ArgumentError gg(sylls) # repeating generators
+
+  sylls = [2 => ZZ(1), 1 => ZZ(2)]
+  @test_throws ArgumentError gg(sylls) # not in ascending order
+
+  sylls = [2 => ZZ(1), 1 => ZZ(2), 1 => ZZ(3)] # both conditions
+  @test_throws ArgumentError gg(sylls)
+end
+
 @testset "create collectors from polycyclic groups" begin
   for i in rand(1:number_of_small_groups(96), 10)
     g = small_group(96, i)