# $p$-Groups of Tame Genus

The `TameGenus` package contains polynomial-time algorithms to decide isomorphism, construct automorphism groups, and build canonical labels of a class of $p$-groups of nilpotency class $2$ and exponent $p$. We say such groups have *tame genus*, and we provide a function called `IsTameGenusGroup` to check whether the functions in `TameGenus` can be applied to the given group. This class includes $d$-generated groups of order $p^{d + 2}$, exponent $p$, and class $2$.For definitions, theorems, and descriptions of algorithms, see [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)]. When appropriate, intrinsics for groups also work for bilinear maps (`TenSpcElt`).

## Verbose Printing

We have included intrinsics to allow for verbose printing. The string `"TameGenus"` is now accepted by `SetVerbose` with print levels between $0$ and $2$. Level 0 turns off all printing. Level 1 will print out the steps in the algorithms, and level 2 will print timings and extra structural information along the way.

### `Example: Verbose Printing (ex-e49bb4)`

We demonstrate the verbose printing by constructing a random genus 2 group of order $3^{20 + 2}$.

```magma
> G := RandomGenus2Group(3, [4, 6, 10]);
> #G eq 3^(4 + 6 + 10 + 2);
true
> Genus(G);
2

```

With the verbose printing, we can see steps of the algorithm.

```magma
> SetVerbose("TameGenus", 1);
> A := TGAutomorphismGroup(G);
Extracting the p-central tensor and computing pseudo-isometries.
Checking the radicals.
        dim(Rad_V) = 0
        dim(Rad_W) = 0
Writing tensor over its centroid.
Tensor has genus 2.
Computing the adjoint algebra.
        dim(Adj) = 40
Decomposing tensor into flat and sloped subtensors.
        Block dims = [ 4, 6, 10 ]
Number of sloped blocks to lift: 3.
Field is small enough, applying Pfaffian method.
Number of flat blocks to lift: 0.
Constructing the isometry group.
   G
   |   Sp ( 2 , 3 ^ 2 )
   *
   |   Sp ( 2 , 3 ^ 3 )
   *
   |   Sp ( 2 , 3 ^ 5 )
   *
   |   3 ^ 0    (unipotent radical)
   1
Constructing automorphism group from pseudo-isometries.

```

## Constructors

We introduce functions to construct groups of genus $\leq 2$.

### `TGRandomGroup(q, n, g : parameters): RngIntElt, RngIntElt, RngIntElt -> GrpPC`

```magma
Exponentp: BoolElt                    Default: true
```

Given $q=p^m$, $n>0$, and $g>0$, returns a $p$-group $G$ with genus $\leq g$ and order $q^{n+g}$. The algorithm is based on the Universal Coefficients Theorem, see [[Leedham-Green and McKay, 2002](../../references.md#cite-lgm-book), Chapter 9] for the statement and proof. There is one optional parameter: `Exponentp`.

**(*)**
`Exponentp`: Set to `false` if the constructor should not force exponent $p$.

### `Example: Random Genus Groups (ex-7e07d7)`

We construct a random group using the `TGRandomGroup` constructor. Specifically, we create a group $G$ with exponent $5$ such that the commutator tensor $[,]$ has centroid containing $K={\bf F}_{5^7}$ with genus at most $2$ and where $\rm{dim}_K (G/\Phi(G)) = 8$. First, we create the group.

```magma
> G := TGRandomGroup(5^7, 8, 2);
> #G eq 5^(7*(8 + 2));
true

```

We check that the genus of our group $G$ is at most 2.

```magma
> Genus(G);
2

```

We verify that the commutator tensor has a centroid containing the field of order $5^7$.

```magma
> t := pCentralTensor(G, 1, 1);
> t;
Tensor of valence 3, U2 x U1 >-> U0
U2 : Full Vector space of degree 56 over GF(5)
U1 : Full Vector space of degree 56 over GF(5)
U0 : Full Vector space of degree 28 over GF(5)
> C := Centroid(t);
> Dimension(C);
7
> IsSimple(C);
true

```

### `RandomGenus2Group(q, d : parameters): RngIntElt, [RngIntElt] -> GrpPC`

```magma
Exponentp: BoolElt                    Default: true
```

Given $q=p^m$ and $d=[d_1, \dots, d_k]$, where $d_i>0$, return a genus 2 group $G$ whose commutator tensor $[,] : V\times V\rightarrowtail W$ which is ${\bf F}_{q}$-bilinear and whose $\perp$-decomposition has blocks of the prescribed dimensions $d_1,\dots,d_k$ over ${\bf F}_{q}$. Each $d_i=1$ increases the dimension of the radical of $[,]$ by 1 over ${\bf F}_{q}$. There is one optional parameter: `Exponentp`.

**(*)**
`Exponentp`: Set to `false` if the constructor should not force exponent $p$.

### `Example: Prescribed Blocks (ex-3b8b51)`

Unlike the `TGRandomGroup` constructor, if we want to construct a genus 2 group with prescribed block dimensions, we can do this with `RandomGenus2Group`. If we want an elementary abelian direct factor, we can append a sequence of $1$s whose sum is the rank of such a factor. We construct a genus 2 group $G$ with an indecomposable blocks of dimensions $10$, $7$, $4$, $4$, and $1$. Therefore, $G\cong H\times {\mathbb{Z}}/(p)$, where $H$ is directly indecomposable and of order $7^{25+2}$.

```magma
> G := RandomGenus2Group(7, [10, 7, 4, 4, 1]);
> #G eq 7^(10 + 7 + 4 + 4 + 1 + 2);
true

```

We can see these blocks with the genus 2 signature of the group. See `TGSignature` for a description of the output.

```magma
> S := TGSignature(G);
> S;
[* <7, 25, 2>, <1, 0>,
    [ 7 ],
    [*
        [ 1, 0, 1 ],
        [ 1, 4, 5 ],
        [ 1, 3, 3, 2, 6, 3 ]
    *]
*]

```

### `RandomGenus1Group(q, d, r : parameters): RngIntElt, RngIntElt, RngIntElt -> GrpPC`

```magma
Exponentp: BoolElt                    Default: true
```

Given $q=p^m$, $d>0$, and $r\geq 0$, return a group $G$ with genus 1 and of order $q^{2d+r+1}$. The center of $G$ has order $q^{r+1}$, and $G$ is $m(2d+r)$-generated. There is one optional parameter: `Exponentp`.

**(*)**
`Exponentp`: Set to `false` if the constructor should not force exponent $p$.

### `Example: Heisenbergs (ex-3634bf)`

The classic Heisenberg group over a field is an example of a genus 1 group, and one can generalize this construction in a number of ways. We will create a matrix group, over ${\bf F}_{81}$, as a polycyclic group.

```magma
> G := RandomGenus1Group(81, 2, 0);
> #G eq 81^(2*2 + 1);
true

```

We verify that $G$ has genus 1 and that the derived subgroup is isomorphic to $({\mathbb{Z}}/(3))^4$.

```magma
> D := DerivedSubgroup(G);
> IsElementaryAbelian(D);
true
> #D eq 3^4;
true

```

Although the underlying field ${\bf F}_{81}$ is hidden within the relations of the polycyclic presentation, we can still construct it and compute the genus over this larger field.

```magma
> Genus(G);
1

```

### `Genus2Group(f): RngUPolElt -> GrpPC`

### `Genus2Group(f): RngMPolElt -> GrpPC`

Given either a univariate or homogeneous multivariate polynomial in two variables over ${\bf F}_{q}$, return a group $G$ whose commutator ${\bf F}_{q}$-tensor has a Pfaffian in the same $\Gamma\rm{L}(2,q)$-orbit as $f$.

### `Example: Pfaffians (ex-ff5bc5)`

We construct the genus 2 group $G$ whose (univariate) Pfaffian is equivalent to $f(x) = x^3(x-1)^2(x-2)$ in ${\bf F}_{9}[x]$. Therefore, we expect $|G|=9^{2\cdot 6 + 2}$.

```magma
> P<x> := PolynomialRing(GF(9));
> f := x^3*(x-1)^2*(x-2);
> G := Genus2Group(f);
> #G eq 9^(2*6 + 2);
true

```

The genus 2 signature reveals the block structure. All six $\perp$-indecomposable subspaces are $2$-dimensional.

```magma
> S := TGSignature(G);
> S;
[* <9, 12, 2>, <0, 0>,
    [],
    [*
        [ 1, 1 ],
        [ 1, 0, 0 ],
        [ 0, 0, 0, 1 ]
    *]
*]

```

The output shows that the homogenization of $f$ is equivalent to the polynomial $g(x,y) = x^2y^3(x+y)$ in ${\bf F}_{q}[x,y]$.

## Direct Indecomposability

Determining the genus of a group $G$ requires knowing the direct indecomposable factors of $G$, so there are functions to decide if $G$ is indecomposable.

### `IsIndecomposable(G): GrpPC -> BoolElt`

Given a group $G$, decide if $G$ is directly indecomposable. This algorithm is based on algorithms by Wilson in [[Wilson, 2012](../../references.md#cite-wilson-decomposable)].

### `IsIndecomposable(t): TenSpcElt -> BoolElt`

Given a tensor $t$, decide if $t$ is directly indecomposable. This algorithm is based on algorithms by Wilson in [[Wilson, 2012](../../references.md#cite-wilson-decomposable)].

### `Example: Decomposable Groups (ex-3b99f7)`

We create a decomposable genus 2 group from the `TameGenus` constructors. For example, the group $G$ with a Pfaffian equivalent to $xy$ is decomposable.

```magma
> P<x, y> := PolynomialRing(GF(7), 2);
> f := x*y;
> G := Genus2Group(f);
> G;
GrpPC : G of order 117649 = 7^6
PC-Relations:
G.3^G.1 = G.3 * G.5,
G.4^G.2 = G.4 * G.6
> IsIndecomposable(G);
false

```

This example also shows that `TGRandomGroup` may return a group that is directly decomposable.

### `Example: Direct Not Central (ex-f8f20b)`

We create a directly indecomposable group $G$ that is a central product of two genus 2 groups.

```magma
> G := RandomGenus2Group(5, [3, 4]);
> #G eq 5^(3 + 4 + 2);
true
> IsIndecomposable(G);
true

```

We observe the central factors from the genus 2 signature of $G$. We see that $G$ is a central product of genus 2 groups of order $5^5$ and $5^6$.

```magma
> TGSignature(G);
[* <5, 7, 2>, <0, 0>,
    [ 3 ],
    [*
        [ 1, 0, 2 ]
    *]
*]

```

## Genus

### `Genus(G): GrpPC -> RngIntElt`

Given a directly indecomposable $p$-group $G$, return the genus of $G$ as defined in [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)].

### `Genus(t): TenSpcElt -> RngIntElt`

Given a directly indecomposable tensor $t: V\times V\rightarrowtail W$, return the rank of $W$ as a $C$-module. Only implemented for algebras $C$ such that $C/J(C)$ is simple, where $J(C)$ is the Jacobson radical.

### `Example: Genus (ex-40dc90)`

We determine the genus of some groups in the Small Group library. Let $G$ be the group of order $3^6$ with ID number 440. Its derived subgroup is isomorphic to $({\mathbb{Z}}/(3))^2$, and $G$ is genus 2.

```magma
> G := SmallGroup(3^6, 440);
> #DerivedSubgroup(G) eq 3^2;
true
> IsElementaryAbelian(DerivedSubgroup(G));
true
> Genus(G);
2

```

Let $H$ be the group of order $3^6$ with ID number 469. Its derived subgroup is isomorphic to $({\mathbb{Z}}/(3))^2$ also, but $H$ is genus 1.

```magma
> H := SmallGroup(3^6, 469);
> #DerivedSubgroup(H) eq 3^2;
true
> IsElementaryAbelian(DerivedSubgroup(H));
true
> Genus(H);
1

```

We can see this difference in genus in multiple ways. If we extract the commutator tensor from both groups, one is bilinear over a quadratic field extension where the other tensor is not. The algebra that records this is the centroid of a tensor, see `Centroid`.

```magma
> s := pCentralTensor(G, 1, 1);
> t := pCentralTensor(H, 1, 1);
> C_G := Centroid(s);
> C_H := Centroid(t);
> C_G;
Matrix Algebra of degree 6 with 2 generators over GF(3)
> C_H;
Matrix Algebra of degree 6 with 2 generators over GF(3)

```

The centroid associated to the tensor $s$ is $2$-dimensional but with a nontrivial Jacobson radical. The centroid associated to the tensor $t$ is $2$-dimensional and a simple ${\bf F}_{3}$-algebra.

```magma
> Dimension(C_G);
2
> Dimension(C_H);
2
> WedderburnDecomposition(C_G);
Matrix Algebra of degree 6 with 1 generator over GF(3)
Matrix Algebra of degree 6 with 1 generator over GF(3)
> IsSimple(C_H);
true

```

### `IsTameGenusGroup(G): Group -> BoolElt`

Decides if the functions in the `TameGenus` package (prefixed with `TG`) can be applied to the given group $G$.

### `IsTameGenusTensor(t): TenSpcElt -> BoolElt`

Decides if the functions in the `TameGenus` package (prefixed with `TG`) can be applied to the given tensor $t$.

### `Example: Non Example (ex-da6133)`

We create a group that is not covered by the `TameGenus` package. The small groups of order $3^6$ with IDs 440 and 469 both have tame genus: 2 and 1 respectively. The direct product of the two groups has genus 2, but because the group is not directly indecomposable, the current implementation of `TameGenus` cannot handle it.

```magma
> H1 := SmallGroup(3^6, 440);
> H2 := SmallGroup(3^6, 469);
> G := DirectProduct(H1, H2);
> G;
GrpPC : G of order 531441 = 3^12
PC-Relations:
    G.2^G.1 = G.2 * G.5,
    G.3^G.1 = G.3 * G.6,
    G.3^G.2 = G.3 * G.5,
    G.4^G.1 = G.4 * G.5,
    G.8^G.7 = G.8 * G.11,
    G.9^G.7 = G.9 * G.12,
    G.9^G.8 = G.9 * G.11^2 * G.12,
    G.10^G.7 = G.10 * G.11 * G.12,
    G.10^G.8 = G.10 * G.11
> IsTameGenusGroup(G);
false

```

### `Example: All The Small Groups (ex-063b44)`

We use the `IsTameGenusGroup` to filter large databases down to the ones covered by `TameGenus`. We do that with the Small Group library for groups of order $3^6$, and we find there are seven such groups. Recall, that these groups must have prime exponent.

```magma
> G2_SG := [*G : G in SmallGroups(3^6) | IsTameGenusGroup(G)*];
> #G2_SG;
7

```

We further filter these groups based on their genus, and we find that there are six groups of positive genus and one abelian group.

```magma
> G1 := [*G : G in G2_SG | Genus(G) eq 1*];
> G2 := [*G : G in G2_SG | Genus(G) eq 2*];
> #G1;
3
> #G2;
3

```

We determine the tame genus signatures to show that all these groups yield different signatures. We first consider the genus 1 groups.

```magma
> for G in G1 do
>     TGSignature(G);
> end for;
[* <9, 2, 1>, <0, 0>, [* *], [* *] *]
[* <3, 2, 1>, <3, 0>, [* *], [* *] *]
[* <3, 4, 1>, <1, 0>, [* *], [* *] *]

```

The genus 2 groups have the following signatures.

```magma
> for G in G2 do
>     TGSignature(G);
> end for;
[* <3, 3, 2>, <1, 0>,
    [ 3 ],
    [* *]
*]
[* <3, 4, 2>, <0, 0>,
    [],
    [*
        [ 0, 0, 1 ]
    *]
*]
[* <3, 4, 2>, <0, 0>,
    [],
    [*
        [ 1, 0 ],
        [ 0, 1 ]
    *]
*]

```

## Isomorphism

### `TGIsIsomorphic(G, H : parameters): GrpPC, GrpPC -> BoolElt`

```magma
Cent        : BoolElt                      Default: true
Constructive: BoolElt                      Default: true
Method      : RngIntElt                    Default: 0
```

Given class $\leq 2$, exponent $p$, directly indecomposable odd-ordered $p$-groups $G$ and $H$ of genus $\leq 2$, decide if $G\cong H$. This will accept groups $G$ of the form $G\cong A\times K$, where $A$ is abelian and $K$ is directly indecomposable. There are three optional parameters: `Cent`, `Constructive`, and `Method`.

**(*)**
`Cent`: If $G$ and $H$ are known to have genus $\leq 2$ over the prime field, then set to `false` to save some time.

**(*)**
`Constructive`: Set to `false` if an explicit isomorphism is not needed.

**(*)**
`Method`: Input from $\{ 0,1,2\}$ is acceptable. This determines the method for handling the sloped part of the tensor. If the adjoint-tensor method should be used, set to $1$. If the Pfaffian method should be used, set to $2$. The default will try to find the optimal method based on the input; see [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)] for details.

### `Example: Isomorphism Testing (ex-13bda5)`

We create an isomorphic pair of groups in two different ways, and then we construct an isomorphism between the two. This example can be seen as verifying Theorem 1.1 of [[Lewis and Maglione, 2018](../../references.md#cite-lm-semi-extraspecial)]. We construct groups $G$ and $H$ from two random irreducible cubic polynomials in ${\bf F}_{67}[x]$.

```magma
> f := RandomIrreduciblePolynomial(GF(67), 3);
> g := RandomIrreduciblePolynomial(GF(67), 3);
> f, g;
$.1^3 + 36*$.1^2 + 26*$.1 + 33
$.1^3 + 57*$.1^2 + 24*$.1 + 65
> G := Genus2Group(f);
> H := Genus2Group(g);

```

In this case, the default method will run the adjoint-tensor method. We can see this if we turn on verbose printing.

```magma
> SetVerbose("TameGenus", 1);
> isomorphic, phi := TGIsIsomorphic(G, H);
Extracting p-central tensors and deciding pseudo-isometry.
Checking the radicals.
        dim(Rad_V) = 0
        dim(Rad_W) = 0
Checking the radicals.
        dim(Rad_V) = 0
        dim(Rad_W) = 0
Writing tensor over its centroid.
Writing tensor over its centroid.
Computing the adjoint algebra.
        dim(Adj_s) = 12
        dim(Adj_t) = 12
Computing the adjoint algebra.
Genus 2 case.
Decomposing tensors into flat and sloped subtensors.
        Block dims = [ 6 ]
PGammaL is larger than symmetric group, applying adjoint-tensor method.

```

We see that the two groups are isomorphic, and $\phi$ is such an isomorphism.

```magma
> isomorphic;
true
> phi;
Homomorphism of GrpPC : G into GrpPC : H induced by
    G.1 |--> H.1 * H.2^41 * H.3^30 * H.4^58 * H.5^43 * H.6^30
    G.2 |--> H.1^53 * H.2^4 * H.3^34 * H.4^54 * H.5^6 * H.6^25
    G.3 |--> H.1^5 * H.2^7 * H.3^49 * H.4^52 * H.5^21 * H.6^7
    G.4 |--> H.1^30 * H.2^4 * H.3^17 * H.4^53 * H.5^40 * H.6^9
    G.5 |--> H.1^14 * H.2^21 * H.3^30 * H.4^24 * H.5^38 * H.6^34
    G.6 |--> H.1^47 * H.2^46 * H.3^66 * H.4^65 * H.5^30 * H.6^30
    G.7 |--> H.7^10 * H.8^18
    G.8 |--> H.7^54 * H.8^12

```

To run the Pfaffian test, set the `Method` to 2. This method is noticeably slower for these groups and should not be used for very large primes.

```magma
> isomorphic, phi2 := TGIsIsomorphic(G, H : Method := 2);
Extracting p-central tensors and deciding pseudo-isometry.
Checking the radicals.
        dim(Rad_V) = 0
        dim(Rad_W) = 0
Checking the radicals.
        dim(Rad_V) = 0
        dim(Rad_W) = 0
Writing tensor over its centroid.
Writing tensor over its centroid.
Computing the adjoint algebra.
        dim(Adj_s) = 12
        dim(Adj_t) = 12
Computing the adjoint algebra.
Genus 2 case.
Decomposing tensors into flat and sloped subtensors.
        Block dims = [ 6 ]
Method set to Pfaffian.
> phi2;
Homomorphism of GrpPC : G into GrpPC : H induced by
    G.1 |--> H.1^47 * H.2^54 * H.3^54
    G.2 |--> H.1^63 * H.2^33 * H.3^15
    G.3 |--> H.1^26 * H.2^3 * H.3^60
    G.4 |--> H.4^44 * H.5^61 * H.6^16
    G.5 |--> H.4^66 * H.5^26 * H.6^36
    G.6 |--> H.4^57 * H.5^6 * H.6^30
    G.7 |--> H.7^62 * H.8^42
    G.8 |--> H.7^18 * H.8^58

```

### `TGIsPseudoIsometric(s, t : parameters): TenSpcElt, TenSpcElt -> BoolElt, Hmtp`

```magma
Cent        : BoolElt                      Default: true
Constructive: BoolElt                      Default: true
Method      : RngIntElt                    Default: 0
```

Given directly indecomposable, alternating tensors $s, t : V\times V \rightarrowtail W$, where $V$ and $W$ are ${\bf F}_{q}$-vector spaces of odd order, decide if $s$ is pseudo-isometric to $t$. This will accept tensors with nontrivial radicals and coradicals. There are three optional parameters: `Cent`, `Constructive`, and `Method`.

**(*)**
`Cent`: If $G$ and $H$ are known to have genus $\leq 2$ over the prime field, then set to `false` to save some time.

**(*)**
`Constructive`: Set to `false` if an explicit isomorphism is not needed.

**(*)**
`Method`: Input from $\{ 0,1,2\}$ is acceptable. This determines the method for handling the sloped part of the tensor. If the adjoint-tensor method should be used, set to $1$. If the Pfaffian method should be used, set to $2$. The default will try to find the optimal method based on the input; see [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)] for details.

### `Example: Pseudo Isometries (ex-e03ee8)`

A pair of alternating matrices determines a tensor of tame genus. We construct a pair of pseudo-isometric tensors by applying a change of bases map. This is essentially how Experiment A from [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)] was conducted. Generating random $50\times 50$ matrices over ${\bf F}_{3}$, we construct two tensors $s,t : {\bf F}_{3}^{50} \times {\bf F}_{3}^{50}\rightarrowtail{\bf F}_{3}^2$.

```magma
> M := RandomMatrix(GF(3), 50, 50);
> N := RandomMatrix(GF(3), 50, 50);
> Forms1 := [M - Transpose(M), N - Transpose(N)];
> s := Tensor(Forms1, 2, 1);
> s;
Tensor of valence 3, U2 x U1 >-> U0
U2 : Full Vector space of degree 50 over GF(3)
U1 : Full Vector space of degree 50 over GF(3)
U0 : Full Vector space of degree 2 over GF(3)
> IsAlternating(s);
true

```

We construct a random invertible co-homotopism $\varphi = (\varphi_1, \varphi_0)$ such that $\varphi_1\in {\operatorname{GL}}(50, 3)$ and $\varphi_0\in{\operatorname{GL}}(2, 3)$. We define a new and pseudo-isometric tensor $t=s^{\varphi}$ in this way.

```magma
> X := Random(GL(50, 3));
> Y := Random(GL(2, 3));
> Maps := [*X, X, Y*];
> H := Homotopism(Maps, CohomotopismCategory(3));
> t := s @ H;
> t;
Tensor of valence 3, U2 x U1 >-> U0
U2 : Full Vector space of degree 50 over GF(3)
U1 : Full Vector space of degree 50 over GF(3)
U0 : Full Vector space of degree 2 over GF(3)
> s eq t;
false

```

We verify that both $s$ and $t$ are pseudo-isometric, and since we do not need to write these tensors over their centroid, we avoid that step by setting `Cent` to `false`.

```magma
> pisometric, Phi := TGIsPseudoIsometric(s, t : Cent :=false);
> pisometric;
true
> Phi.0;
[0 1]
[2 2]

```

## Automorphism Groups

### `TGAutomorphismGroup(G : parameters): GrpPC -> GrpAuto`

```magma
Cent  : BoolElt                      Default: true
Method: RngIntElt                    Default: 0
Mat   : BoolElt                      Default: false
```

Given a directly indecomposable odd-ordered $p$-group $G$, of class $\leq 2$, exponent $p$, and genus $\leq 2$, return ${\operatorname{Aut}}(G)$. This will accept groups $G$ of the form $G\cong A\times K$, where $A$ is abelian and $K$ is directly indecomposable. This intrinsic provides three optional parameters: `Cent`, `Method`, and `Mat`.

**(*)**
`Cent`: If $G$ and $H$ are known to have genus $\leq 2$ over the prime field, then set to `false` to save some time.

**(*)**
`Method`: Input from $\{ 0,1,2\}$ is acceptable. This determines the method for handling the sloped part of the tensor. If the adjoint-tensor method should be used, set to $1$. If the Pfaffian method should be used, set to $2$. The default will try to find the optimal method based on the input; see [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)] for details.

**(*)**
`Mat`: Set to `true` for a linear representation of the automorphism group. The row vectors of the matrix correspond to the given polycyclic vectors from the polycyclic presentation.

### `Example: Flat Indecomposable (ex-36d32b)`

We build a flat indecomposable genus 2, $p$-group $G$ and construct its automorphism group. We know that ${\operatorname{Aut}}(G)$ maps surjectivity onto ${\operatorname{GL}}(2, p)$, so we verify that $|{\operatorname{Aut}}(G)|$ is divisible by $|{\operatorname{GL}}(2, p)| = (p^2-1)(p^2-p)$. This corresponds to the quotient of the pseudo-isometry group by the isometry group.

```magma
> p := 541;
> G := RandomGenus2Group(p, [29]);
> #G eq p^(29 + 2);
true
> A := TGAutomorphismGroup(G);
> IsDivisibleBy(#A, #GL(2, p));
true

```

The isometry group of the corresponding commutator tensor has an elementary abelian unipotent radical of rank $28$, and so is isomorphic to an extension of ${\operatorname{GL}}(1, p)$ by $({\mathbb{Z}}/(p))^{28}$, as seen in [[Brooksbank and Wilson, 2012](../../references.md#cite-bw-isometry)]. Therefore, we verify that we have constructed all automorphisms as

$$
|{\operatorname{Aut}}(G)| = (p - 1)p^{28} \cdot (p^2-1)(p^2-p) \cdot p^{29\cdot 2}.
$$

```magma
> #A eq (p - 1)*p^28 * (p^2 - 1)*(p^2 - p) * p^(29*2);
true

```

### `TGPseudoIsometryGroup(t : parameters): TenSpcElt -> GrpMat`

```magma
Cent  : BoolElt                      Default: true
Method: RngIntElt                    Default: 0
```

Given a directly indecomposable, alternating tensor $t : V \times V \rightarrowtail W$, where $V$ and $W$ are ${\bf F}_{q}$-vector spaces for odd $q$, return the pseudo-isometry group of $t$ as a subgroup of ${\operatorname{GL}}(V)\times {\operatorname{GL}}(W)$. This accepts tensors with nontrivial radicals and coradicals. This intrinsic provides two optional parameters: `Cent` and `Method`.

**(*)**
`Cent`: If $G$ and $H$ are known to have genus $\leq 2$ over the prime field, then set to `false` to save some time.

**(*)**
`Method`: Input from $\{ 0,1,2\}$ is acceptable. This determines the method for handling the sloped part of the tensor. If the adjoint-tensor method should be used, set to $1$. If the Pfaffian method should be used, set to $2$. The default will try to find the optimal method based on the input; see [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)] for details.

### `Example: Extensions (ex-35a1af)`

For $K$-vector spaces $V$ and $W$, we create a genus 2 alternating tensor $t: V \times V\rightarrowtail W$ such that $t$ is bilinear over an extension field $E/K$ and $\rm{dim}_E(W)=2$. One way to do this is with the constructors `RandomGenus2Group` and `pCentralTensor`.

```magma
> G := RandomGenus2Group(3^2, [6]);
> t := pCentralTensor(G, 1, 1);
> t;
Tensor of valence 3, U2 x U1 >-> U0
U2 : Full Vector space of degree 12 over GF(3)
U1 : Full Vector space of degree 12 over GF(3)
U0 : Full Vector space of degree 4 over GF(3)
> Genus(t);
2

```

The Pfaffian of $t$ is an irreducible cubic over ${\bf F}_{9}$, so computing its pseudo-isometry group may contain elements of $\rm{Gal}({\bf F}_{9})$.

```magma
> PI := TGPseudoIsometryGroup(t);
> Random(PI);
[0 1 0 0 0 2 1 1 0 2 1 0 0 0 0 0]
[2 0 0 0 1 0 0 2 1 0 1 2 0 0 0 0]
[1 1 0 0 0 1 1 1 0 0 2 1 0 0 0 0]
[0 2 0 0 2 0 0 2 0 0 1 1 0 0 0 0]
[1 2 2 0 0 2 2 2 1 0 0 0 0 0 0 0]
[2 2 2 1 1 0 0 1 1 2 0 0 0 0 0 0]
[2 2 2 0 1 0 1 0 2 2 1 2 0 0 0 0]
[0 1 2 1 1 2 1 2 0 1 2 2 0 0 0 0]
[2 0 1 0 2 2 2 1 1 1 0 0 0 0 0 0]
[2 1 1 2 0 1 1 1 0 2 0 0 0 0 0 0]
[0 2 0 1 2 2 1 1 0 1 1 0 0 0 0 0]
[1 0 2 0 0 1 0 2 2 0 1 2 0 0 0 0]
[0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0]
[0 0 0 0 0 0 0 0 0 0 0 0 2 0 1 2]
[0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0]
[0 0 0 0 0 0 0 0 0 0 0 0 0 2 0 0]
> Factorization(#PI);
[ <2, 8>, <3, 7>, <5, 1>, <7, 1>, <13, 1>, <73, 1> ]

```

Indeed, the pseudo-isometry group may not be linear over the centroid but semi-linear. To see the discrepancy, we rewrite $t$ over its centroid and determine its pseudo-isometry group as a subgroup of ${\operatorname{GL}}_E(V)\times {\operatorname{GL}}_E(W)$. Note that this group is smaller by a factor of $2$. We see that the pseudo-isometry group of $t$ is strictly semi-linear over ${\bf F}_{9}$, as there exists a Galois involution.

```magma
> s := TensorOverCentroid(t);
> s;
Tensor of valence 3, U2 x U1 >-> U0
U2 : Full Vector space of degree 6 over GF(3^2)
U1 : Full Vector space of degree 6 over GF(3^2)
U0 : Full Vector space of degree 2 over GF(3^2)
> PI_C := TGPseudoIsometryGroup(s);
> Random(PI_C);
[    1 $.1^7     1 $.1^2 $.1^2 $.1^5     0     0]
[  $.1     2 $.1^7 $.1^3 $.1^6 $.1^5     0     0]
[$.1^7 $.1^2 $.1^7     1 $.1^6 $.1^2     0     0]
[$.1^7 $.1^7 $.1^7 $.1^3 $.1^7     1     0     0]
[    2 $.1^6 $.1^3 $.1^2 $.1^3     0     0     0]
[$.1^7   $.1 $.1^7 $.1^6 $.1^6 $.1^7     0     0]
[    0     0     0     0     0     0     2 $.1^7]
[    0     0     0     0     0     0 $.1^3 $.1^5]
> Factorization(#PI_C);
[ <2, 7>, <3, 7>, <5, 1>, <7, 1>, <13, 1>, <73, 1> ]

```

## Canonical Labelling

### `TGSignature(G): GrpPC -> List`

Given an odd-ordered $p$-group $G\cong A \times H$ of genus $\leq 2$, class $\leq 2$, and exponent $p$, return the canonical tame genus signature as a list with four entries. For groups with genus $\leq 1$, the last two entries will be empty. We describe the entries.

**(1)**
The first is a triple of three integers $(q, d, e)$ such that associated fully nondegenerate commutator tensor of $H$ has the form ${\bf F}_{q}^d\times {\bf F}_{q}^d\rightarrowtail {\bf F}_{q}^e$. Here, ${\bf F}_{q}$ is the largest field $F$ which the commutator tensor is $F$-bilinear.

**(2)**
The second entry is a pair of integers $(r, c)$, where $A \cong ({\mathbb{Z}}/(p))^r$ and $c=0$.

**(3)**
The third entry is a sequence of odd integers corresponding to the dimensions of the flat indecomposable spaces.

**(4)**
The fourth and last entry is a list sequences in ${\bf F}_{q}$ of possibly different lengths. A sequence $[c_1,\dots, c_{d+1}]$ in the second entry corresponds to the coefficients of the homogeneous polynomial in $x$ and $y$ in degree $d$:

$$
c_1x^d + c_2 x^{d-1}y + c_3 x^{d-2}y^2 + \cdots + c_{d+1}y^d.
$$

Because this is a canonical label, two groups are isomorphic if, and only if, their tame genus signatures are equal. See [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)] for details on how the last two entries describe a genus 2 group.

### `TGSignature(t): TenSpcElt -> List`

Given an alternating, directly indecomposable tensor $t:V\times V\rightarrowtail W$ of genus $\leq 2$, where $V$ and $W$ are ${\bf F}_{q}$-vector spaces for odd $q$, return the canonical tame genus signature as a list with four entries. For tensors with genus $\leq 1$, the last two entries will be empty. We describe the entries.

**(1)**
The first is a triple of three integers $(q^f, d, e)$ such that associated fully nondegenerate tensor of $t$ has the form ${\bf F}_{q^f}^d\times {\bf F}_{q^f}^d\rightarrowtail {\bf F}_{q^f}^e$. Here, ${\bf F}_{q^f}$ is the largest field $F$ which the associated fully nondegenerate tensor is $F$-bilinear.

**(2)**
The second entry is a pair of integers $(r, c)$, where the radical of $t$ is $r$-dimensional and the codimension of the image of $t$ in $W$ is $c$, both are determined over ${\bf F}_{q}$.

**(3)**
The third entry is a sequence of odd integers corresponding to the dimensions of the flat indecomposable spaces.

**(4)**
The fourth and last entry is a list sequences in ${\bf F}_{q}$ of possibly different lengths. A sequence $[c_1,\dots, c_{d+1}]$ in the second entry corresponds to the coefficients of the homogeneous polynomial in $x$ and $y$ in degree $d$:

$$
c_1x^d + c_2 x^{d-1}y + c_3 x^{d-2}y^2 + \cdots + c_{d+1}y^d.
$$

Because this is a canonical label, two tensors are pseudo-isometric if, and only if, their tame genus signatures are equal. See [[Brooksbank *et al.*, 2017](../../references.md#cite-bmw-genus2)] for details on how the last two entries describe a genus 2 tensor.

### `Example: Many Blocks (ex-bbc04e)`

We construct a genus 2 group $G\cong A \times H$, where $A$ is abelian and $H$ is directly indecomposable but is the central product of many smaller genus 2 groups.

```magma
> blocks := [1, 1, 1, 2, 2, 3, 3, 5, 6];
> G := RandomGenus2Group(9, blocks);
> #G eq 9^(&+blocks + 2);
true

```

Because $G$ was created with the field ${\bf F}_{9}$ and since there are three $1$-dimensional blocks, we expect $|A| = 9^3 = 3^6$.

```magma
> TGSignature(G);
[* <9, 21, 2>, <6, 0>,
    [ 3, 3, 5 ],
    [*
        [ 0, 1 ],
        [ 1, 1 ],
        [ 1, 2, 2, 2 ]
    *]
*]

```

The first entry of this list tells us that the group $H$ has order $9^{21 + 2}$ and that the commutator tensor of $H$ is ${\bf F}_{9}$-bilinear. The second entry reports that $A\cong ({\mathbb{Z}}/(3))^6$. The third and fourth entries show that $H$ is a central product of six indecomposable groups: three flats of orders $9^{3+2}$, $9^{3+2}$, and $9^{5+2}$, and three sloped with Pfaffians in ${\bf F}_{9}[x,y]$ equivalent to

$$
y, x + y, x^3 + 2x^2y + 2xy^2 + 2y^3.
$$

### `Example: More Small Groups (ex-15bce1)`

We run through all the small groups of order $3^7$ and determine their tame genus signatures. There are $9310$ such groups, and $10$ of them are covered by `TameGenus`.

```magma
> TG_SG := SmallGroupProcess(3^7, IsTameGenusGroup);
>
> repeat
>     G := Current(TG_SG);
>     _, ID := CurrentLabel(TG_SG);
>     print "Small group ID:", ID;
>     TGSignature(G);
>     Advance(~TG_SG);
> until IsEmpty(TG_SG);

```

The loop yields the following output.

```magma
Small group ID: 9106
[* <3, 3, 2>, <2, 0>,
    [ 3 ],
    [* *]
*]
Small group ID: 9107
[* <3, 4, 2>, <1, 0>,
    [],
    [*
        [ 1, 0 ],
        [ 0, 1 ]
    *]
*]
Small group ID: 9108
[* <3, 4, 2>, <1, 0>,
    [],
    [*
        [ 0, 0, 1 ]
    *]
*]
Small group ID: 9109
[* <9, 2, 1>, <1, 0>, [* *], [* *] *]
Small group ID: 9110
[* <3, 5, 2>, <0, 0>,
    [ 3 ],
    [*
        [ 0, 1 ]
    *]
*]
Small group ID: 9111
[* <3, 5, 2>, <0, 0>,
    [ 5 ],
    [* *]
*]
Small group ID: 9302
[* <3, 2, 1>, <4, 0>, [* *], [* *] *]
Small group ID: 9305
[* <3, 4, 1>, <2, 0>, [* *], [* *] *]
Small group ID: 9308
[* <3, 6, 1>, <0, 0>, [* *], [* *] *]
Small group ID: 9310
[* <3, 7, 0>, <7, 0>, [* *], [* *] *]

```