Add CanonicalMatrix and CanonicalRees(Zero)MatrixSemigroup

[ChristopherRussell]

This adds a few attributes for Rees (zero) matrix semigroups. Given a Rees (zero) matrix semigroup S the function CanonicalMatrix returns a matrix over UnderlyingSemigroup(S) which defines a Rees (zero) matrix semigroup isomorphic to S. This matrix is canonical in the sense that given any two isomorphic Rees (zero) matrix semigroups the function CanonicalMatrix will return the same matrix. CanonicalRees(Zero)MatrixSemigroup(S) simply returns Rees(Zero)MatrixSemigroup(CanonicalMatrix(S), UnderlyingSemigroup(S)).

The idea behind the method is that two Rees zero matrix semigroups M_0[G;{1 .. m}, {1 .. n};P] and M_0[G;{1 .. m}, {1 .. n};Q] are isomorphic if and only if they lie in the same orbit of the set of all m x n matrices over G_0 with respect to the group action of permuting rows and columns, multiplying rows and columns by group elements and applying automorphisms of G_0 to all entries simultaneously. By constructing this action we can take a matrix and use SmallestImageSet to find a canonical representative of its orbit in the space of all these matrices.

[james-d-mitchell]

full stop -> comma, looks like you forgot to actually include the documentation.

[james-d-mitchell]

In conversation just now, @ChristopherRussell and I, decided that he would revise this PR to include:

• ReesMatrixSemigroupCanonicalLabelling: returns the permutation or whatever
  that takes the RZMS to its canonical version.
• OnReesMatrixSemigroup: action
• CanonicalReesMatrixSemigroup: OnReesMatrixSemigroup(RZMS,
  ReesMatrixSemigroupCanonicalLabelling);

2. Remove CanonicalMatrix

3. Make the function currently installed in SEMIGROUPS local to the only method using them.

[ChristopherRussell]

I have very belatedly updated this PR. In summary, I have acted on the points you mentioned except the one regarding OnReesMatrixSemigroup - which is no longer included. I also had to rebase and fix some tests, and fix some manual examples, because this was quite an old PR. I'm including the message I sent you on Slack below incase my reasoning for this needs to be known in the future.

I think I acted on points 2 & 3 in your review. I seem to have started on 1 but didn’t like the result. It works but isn’t at all user friendly and I didn’t see how to make it so. The issue is that it would be very difficult for a user to define a permutation which acts on one of these matrices unless they understand my work and code very well.

For the case of a m \times n RZMS over the group G the permutation has to be an element of the group (G^m \times G^n) \rtimes (S_m \times S_n \times \Aut(G)) - already quite a difficult thing for a user to define. Furthermore I represent matrices as integers (e.g. the 2^(mn) many m x n binary matrices can be represented by the set [1 .. 2^(mn)] in a sensible way) so that I can use faster perm group methods in GAP. So the group (G^m \times G^n) \rtimes (S_m \times S_n \times \Aut(G)). is actually represented as permutations of the set {1, …, 2^(mn)} and theres no way the user could define one of those permutations. My best idea to make it more user friendly is to have a function that maps a quintuple from the set G^m \times G^n \times S_m \times S_n \times \Aut(G) to the perm it represents on {1, …, 2^(mn)}. I believe I thought of this before but I guess I must have decided it was either difficult/awkward, or else seemed inefficient (calculates too much stuff about the whole of this huge group action) in the case a user just wants to use ‘OnReesMatrixSemigroup’ a few times.

[james-d-mitchell]

Does this work for Rees matrix semigroups too?

[ChristopherRussell]

Yes. I accidentally removed that functionality but I added it back. There's no special method it just uses the rees 0-matrix semigroup method and converted back and forth from non 0 rees matrix semigroups.

[james-d-mitchell]

Remove this as a user facing function?

[ChristopherRussell]

Yes

[james-d-mitchell]

zero matrix -> 0-matrix

[james-d-mitchell]

also group -> semigroup

[ChristopherRussell]

Done

[james-d-mitchell]

Changes requested as discussed.

[james-d-mitchell]

I made a couple of minor changes to the documentation, but I'm happy to (squash and) merge this, when/if the CI completes again.