Add letters function for PcGroupElem

[jamesnohilly]

As a starting point for this PR, I've borrowed the syllable functions for PcGroup from PR #4108 to use as a reference for planned work.

Planned work for this PR:

• New function letters for (Sub)PcGroupElem.
• A check in _exponent_vector for whether the input is really "canonical".
• Test cases in test/Groups/pcgroups.jl for the new functions.
• Add doc strings for new functions.

Suggestions from @fingolfin

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.52%. Comparing base (e8f8ecc) to head (5cfffd0).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4202   +/-   ##
=======================================
  Coverage   84.52%   84.52%           
=======================================
  Files         646      646           
  Lines       85631    85654   +23     
=======================================
+ Hits        72382    72403   +21     
- Misses      13249    13251    +2     

Files with missing lines	Coverage Δ
src/Groups/pcgroup.jl	80.21% <100.00%> (+2.86%)	⬆️

... and 1 file with indirect coverage changes

[fingolfin]

Thanks @jamesnohilly to clarify: what you posted in the description is not (yet) what you did, but a description of the work programme, right? Also, should mention that the code here was taken from PR #4108 by @fieker and is only the starting point.

[jamesnohilly]

Yes, that's correct! I've now updated the description to make it clearer and also included a note that the code originates from PR #4108 as the starting point.

[lgoettgens]

some comments. Maybe more directed towards @fingolfin and @ThomasBreuer instead of @jamesnohilly

[fingolfin]

@jamesnohilly tests are still failing. are on onto that, or do you need assistance?

[fingolfin]

Suggested change

	julia> syllables(gg[1]^5*gg[2]^-4)
	julia> x = gg[1]^5*gg[2]^-4
	f1*f2^2
	julia> syllables(x)

[fingolfin]

Can you also add a similar constructor which takes an exponent vector, i.e., an inverse to letters?

[lgoettgens]

One needs to watch out for the semantic difference to the already existing function for FPGroups in

Oscar.jl/src/Groups/GAPGroups.jl

Line 2348 in 24711ee

function (G::FPGroup)(extrep::AbstractVector{T}) where T <: IntegerUnion

, which expects a flattened list of syllable pairs instead.

[fingolfin]

ugh, OK. perhaps we should kill that (is it documented?) first then. In GAP it made some sense to use such a flat list to avoid memory, as there are no tuples in GAP, only lists. But in Julia there is no real benefit of this over a Vector{Pair{Int64, ZZRingElem}}.

But that is way beyond this PR. So let's leave out the constructor I mentioned.

[lgoettgens]

No, not documented, but used for serialization. I haven't looked into how it is used there, so maybe we can just adapt the deserialization function, in the worst case it needs an upgrade script.

[lgoettgens]

ugh, OK. perhaps we should kill that (is it documented?) first then.

maybe @ThomasBreuer can look into that?

[fingolfin]

Note that we can also produce negative numbers: e.g. -3 means "inverse of 3rd generator". This should be explained, and perhaps an example added showing that. E.g. based on this:

julia> x = (gg[1]*gg[2]*gg[3])^-2
g1*g2^-2*g3^3

Perhaps also add something like this (and then mirror it in the other function)

See also [`syllables`](@ref).

[jamesnohilly]

I have added a small example with some brief explanation to letters for this. However I am unsure if the example is good as I was not able to get elements with negative exponents and test.

[fingolfin]

For that you need an infinite group. E.g.

julia> g = dihedral_group(PosInf())
Pc group of infinite order

julia> g[1]^-3 * g[2]^-3
g1*g2^-3

or

julia> g = abelian_group(PcGroup, [5, 0])
Pc group of infinite order

julia> g[1]^-3 * g[2]^-3
g1^2*g2^-3

[lgoettgens]

This PR now unfortunately has conflicts with #4157.

[fingolfin]

@jamesnohilly please try to resolve the conflicts. If you run into troubles (this is something that causes pain to many people esp. at the beginning) drop by my office and we'll figure it out together (ideally with your laptop if you have one)

[jamesnohilly]

I've now merged the changes from #4157 with the changes made in this PR. From a quick look it seems to have merged without any major issues.

[lgoettgens]

This heading should be above the first code block, not between two code blocks

[lgoettgens]

Suggested change

	See also [`syllables`](@ref).
	See also [`syllables(::Union{PcGroupElem, SubPcGroupElem})`](@ref).

otherwise this may link to any function called syllables, e.g. to syllables(::FPGroupElem) which is not what we want here

[lgoettgens]

Suggested change

	For example, as shown below, an output of -1 refers to the "inverse of the first generator".
	For example, as shown below, an output of ´-1´ refers to the "inverse of the first generator".

[fingolfin]

For infinite groups, GAp uses a completely different internal representation. You'll need something like this:

  if GAP.Globals.IsPcpElement(GapObj(g))
     expvec = GAP.Globals.Exponents(GapObj(g))
     ... do something with it....
  else
    ... current code
  end

[fingolfin]

Here you also need to check for if GAPWrap.IsPcGroup(GapObj(G)) and then do something different.

You'll need the function PcpElementByExponents or PcpElementByExponentsNC, see https://gap-packages.github.io/polycyclic/doc/chap4.html#X7882F0F57ABEB680

Also GAP.Globals.Collector(GapObj(G))