The inconsistent code implementation and the document description of the `\^( S, conj )` method.

[hongyi-zhao]

I noticed the following description here:

\^( S, conj )

If S is an AffineCrystGroupOnRight, the group conj S conj^-1 is returned. conj must be an affine matrix acting on the right. If S is an AffineCrystGroupOnLeft, the group conj^-1 S conj is returned. conj must be an affine matrix acting on the left.

The code implementation of the above method can be checked as follows:

gap> PageSource(ApplicableMethod(\^, [ SpaceGroupOnLeftIT(3,227), IdentityMat(4) ]));

The corresponding code snippet on GitHub is located here:

https://github.com/gap-packages/cryst/blob/f1a0f4fa54abe116d9ce3f08c76dda75e950fe3e/gap/cryst.gi#L251-L345

As you can see, the conjugating operations applied on the generators are just contrary to the description in the document, a.k.a., for AffineCrystGroupOnRight, the following operation is used:

gens[i] := Ci * gens[i] * C;

While for AffineCrystGroupOnLeft, the following operation is used:

gens[i] := C * gens[i] * Ci;

The same logic is used in the following code snippet in this package:

https://github.com/gap-packages/cryst/blob/f1a0f4fa54abe116d9ce3f08c76dda75e950fe3e/gap/cryst2.gi#L167-L232

I am very confused by this situation, and any hints and explanations on this issue will be appreciated.

See here for the related discussion.

Regards, Zhao

[hongyi-zhao]

I finally figured out the cause of this confusion, as described below:

By default, GAP adopts the right action convention and defined the following operation for ConjugateGroup command:

gap> ?^;
[...]
 ^  denotes  powering  of a multiplicative element if the right operand is an integer, and is also used to denote the action of a group element on a point of a set if the
  right operand is a group element. In the special case that both operands are group elements, ^ denotes conjugation, that is, g^h = h^{-1} g h.

Therefore, in order to be consistent with the above convention, the corresponding operations of matrices acting on column vectors from the left must be defined as follows:

g^h = h g h^{-1}

[hongyi-zhao]

I've further conducted the following tests:

gap> CrystGroupDefaultAction;
"RightAction"

gap> SGGenSet229me3:=[ 
>   [ [ 0, -1, 0, 1/2 ], 
>   [ 0, 0, -1, 1/2 ], 
>   [ -1, 0, 0, 1/2 ], 
>   [ 0, 0, 0, 1 ] ], 
>   [ [ -15/4, 29/4, -15/4, -15/16 ], 
>   [ -33/8, 55/8, -25/8, -25/32 ], 
>   [ -25/8, 55/8, -33/8, -41/32 ], [ 0, 0, 0, 1 ] ] 
>   ];;
gap> S1gen:=SGGenSet229me3;
[ [ [ 0, -1, 0, 1/2 ], [ 0, 0, -1, 1/2 ], [ -1, 0, 0, 1/2 ], [ 0, 0, 0, 1 ] ], [ [ -15/4, 29/4, -15/4, -15/16 ], [ -33/8, 55/8, -25/8, -25/32 ], 
      [ -25/8, 55/8, -33/8, -41/32 ], [ 0, 0, 0, 1 ] ] ]
gap> S1:=AffineCrystGroupOnLeft(S1gen);
<matrix group with 2 generators>
gap> S2:=SpaceGroupOnLeftIT(3,227);
SpaceGroupOnLeftIT(3,227,'2')
gap> S2gen:=GeneratorsOfGroup(S2);
[ [ [ -1, 0, 0, 3/4 ], [ 0, -1, 0, 1/4 ], [ 0, 0, 1, 1/2 ], [ 0, 0, 0, 1 ] ], [ [ -1, 0, 0, 1/4 ], [ 0, 1, 0, 1/2 ], [ 0, 0, -1, 3/4 ], [ 0, 0, 0, 1 ] ], 
  [ [ 0, 0, 1, 0 ], [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 0, 1 ] ], [ [ 0, 1, 0, 3/4 ], [ 1, 0, 0, 1/4 ], [ 0, 0, -1, 1/2 ], [ 0, 0, 0, 1 ] ], 
  [ [ -1, 0, 0, 0 ], [ 0, -1, 0, 0 ], [ 0, 0, -1, 0 ], [ 0, 0, 0, 1 ] ], [ [ 1, 0, 0, 1/2 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 1/2 ], [ 0, 0, 0, 1 ] ], 
  [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 1/2 ], [ 0, 0, 1, 1/2 ], [ 0, 0, 0, 1 ] ], [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 1 ], [ 0, 0, 0, 1 ] ] ]
gap> conj := ConjugatorSpaceGroups( S1, S2 );
[ [ 5/8, -11/8, 5/8, 297/32 ], [ -11/8, 5/8, 5/8, 297/32 ], [ -5/8, -5/8, 11/8, 655/32 ], [ 0, 0, 0, 1 ] ]
gap> # Formally, the following actions are uniform for matrices acting on the left or right:
gap> S1^conj = S2;
true
gap> \^( S1, conj )= S2;
true
gap> # But the actual conjugate relation is as follows in the left action case:
gap> AffineCrystGroupOnLeft(OnTuples( S1gen, conj^-1) )= S2;
true
gap> S1:=TransposedMatrixGroup( AffineCrystGroupOnLeft(SGGenSet229me3) );
<matrix group with 2 generators>
gap> S1gen:=GeneratorsOfGroup(S1);
[ [ [ 0, 0, -1, 0 ], [ -1, 0, 0, 0 ], [ 0, -1, 0, 0 ], [ 1/2, 1/2, 1/2, 1 ] ], [ [ -15/4, -33/8, -25/8, 0 ], [ 29/4, 55/8, 55/8, 0 ], [ -15/4, -25/8, -33/8, 0 ], 
      [ -15/16, -25/32, -41/32, 1 ] ] ]
gap> S2:=SpaceGroupOnRightIT(3,227);
SpaceGroupOnRightIT(3,227,'2')
gap> S2gen:=GeneratorsOfGroup(S2);
[ [ [ -1, 0, 0, 0 ], [ 0, -1, 0, 0 ], [ 0, 0, 1, 0 ], [ 3/4, 1/4, 1/2, 1 ] ], [ [ -1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, -1, 0 ], [ 1/4, 1/2, 3/4, 1 ] ], 
  [ [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 1, 0, 0, 0 ], [ 0, 0, 0, 1 ] ], [ [ 0, 1, 0, 0 ], [ 1, 0, 0, 0 ], [ 0, 0, -1, 0 ], [ 3/4, 1/4, 1/2, 1 ] ], 
  [ [ -1, 0, 0, 0 ], [ 0, -1, 0, 0 ], [ 0, 0, -1, 0 ], [ 0, 0, 0, 1 ] ], [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 1/2, 0, 1/2, 1 ] ], 
  [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 1/2, 1/2, 1 ] ], [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 1, 1 ] ] ]
gap> conj := ConjugatorSpaceGroups( S1, S2 );
[ [ 5/8, -11/8, -5/8, 0 ], [ -11/8, 5/8, -5/8, 0 ], [ 5/8, 5/8, 11/8, 0 ], [ 297/32, 297/32, 655/32, 1 ] ]
gap> S1^conj = S2;
true
gap> \^( S1, conj )= S2;
true
gap> # But the actual conjugate relation is as follows in the right action case:
gap> AffineCrystGroupOnRight(OnTuples( S1gen, conj) )= S2;
true

As you can see from the tests above, the description in documentation is still self-contradictory:

\^( S, conj )

If S is an AffineCrystGroupOnRight, the group conj S conj^-1 is returned. conj must be an affine matrix acting on the right. If S is an AffineCrystGroupOnLeft, the group conj^-1 S conj is returned. conj must be an affine matrix acting on the left.

[gaehler]

You are right, the documentations says something different than what the code does. I would say that the code is right in this case, and will correct the documentation. Presumably, at some point I had changed the convention in the code without adjusting the documentation. The idea is indeed to be consistent with the usual GAP convention for the default action on the right. If c is the linear part of conj, and T is the translation basis (a list of row vectors), then the new translation basis becomes T*c. For the action on the left, we have instead a translation basis of column vectors T', which are transformed into c*T' by the conjugation. Therefore, the different convention for the left action is also a natural one.