QuadFormAndIsom: fixes and a new feature (#3394)

(cherry picked from commit 376b3f0)

experimental/QuadFormAndIsom/README.md

@@ -25,20 +25,21 @@ of finite order with at most two prime divisors. The methods we resort to
 for this purpose are developed in the paper [BH23](@cite).
 
 We also provide some algorithms computing isomorphism classes of primitive
-embeddings of even lattices following Nikulin's theory. More precisely, the
+embeddings of integral lattices following Nikulin's theory. More precisely, the
 function `primitive_embeddings` offers, under certain conditions,
 the possibility to compute representatives of primitive embeddings and classify
 them in different ways. Note nonetheless that these functions are not efficient
 in the case were the discriminant groups have a large number of subgroups.
 
 ## Status
 
-This project has been slightly tested on simple and known examples. It is
-currently being tested on a larger scale to test its reliability. Moreover,
-there are still computational bottlenecks due to non-optimized algorithms.
+Currently, the project features the following:
 
-Among the possible improvements and extensions:
-* Implement extra methods for lattices with isometries of infinite order;
+- enumeration of conjugacy classes of isometries of finite order for even lattices (in the case of at most 2 prime divisors);
+- enumeration of conjugacy classes of isometries with irreducible and reciprocal minimal polynomial for integral lattices (with maximal equation order);
+- primitive embeddings/extensions for integral lattices;
+- equivariant primitive extensions for integral lattices;
+- miscellaneous operations on integral/rational quadratic form endowed with an isometry.
 
 ## Current applications of this project
 

experimental/QuadFormAndIsom/docs/src/enumeration.md

@@ -4,7 +4,7 @@ CurrentModule = Oscar
 
 # Enumeration of isometries
 
-One of the main features of this project is the enumeration of lattices with
+One of the main features of this project is the enumeration of even lattices with
 isometry of finite order with at most two prime divisors. This is the content
 of [BH23](@cite) which has been implemented. We guide the user here to the global
 aspects of the available theory, and we refer to the paper [BH23](@cite) for further
@@ -48,7 +48,25 @@ isometries of integral integer lattices. For more details such as the proof of
 the algorithms and the theory behind them, we refer to the reference paper
 [BH23](@cite).
 
-### Global function
+### The hermitian case
+
+For an irreducible reciprocal polynomial $\chi$ and a genus symbol $G$
+of integral integer lattices, if the equation order $\mathbb{Z}[\chi]$ is maximal,
+one can compute representatives of isomorphism classes of lattices with isometry
+$(L, f)$ such that $L\in G$ and $\chi(f) = 0$.
+
+```@docs
+representatives_of_hermitian_type(::Union{ZZLat, ZZGenus}, ::Union{ZZPolyRingElem, QQPolyRingElem}, ::Bool)
+```
+
+In the case of finite order isometries, when $\chi$ is cyclotomic, one can use
+as a shortcut the following function instead:
+
+```@docs
+representatives_of_hermitian_type(::Union{ZZGenus, ZZLat}, ::Int, ::Bool)
+```
+
+### Orders with two prime divisors
 
 As we will see later, the algorithms from [BH23](@cite) are specialized on the
 requirement for the input and regular users might not be able to choose between
@@ -88,3 +106,4 @@ embeddings and their equivariant version. We use this basis to introduce the
 method [`admissible_equivariant_primitive_extensions`](@ref) (Algorithm 2 in
 [BH23](@cite)) which is the major tool making the previous enumeration
 possible and fast, from an algorithmic point of view.
+

experimental/QuadFormAndIsom/docs/src/introduction.md

@@ -25,20 +25,21 @@ of finite order with at most two prime divisors. The methods we resort to
 for this purpose are developed in the paper [BH23](@cite).
 
 We also provide some algorithms computing isomorphism classes of primitive
-embeddings of even lattices following Nikulin's theory. More precisely, the
+embeddings of integral lattices following Nikulin's theory. More precisely, the
 function [`primitive_embeddings`](@ref) offers, under certain conditions,
 the possibility to compute representatives of primitive embeddings and classify
 them in different ways. Note nonetheless that these functions are not efficient
 in the case were the discriminant groups have a large number of subgroups.
 
 ## Status
 
-This project has been slightly tested on simple and known examples. It is
-currently being tested on a larger scale to test its reliability. Moreover,
-there are still computational bottlenecks due to non-optimized algorithms.
+Currently, the project features the following:
 
-Among the possible improvements and extensions:
-* Implement extra methods for lattices with isometries of infinite order;
+- enumeration of conjugacy classes of isometries of finite order for even lattices (in the case of at most 2 prime divisors);
+- enumeration of conjugacy classes of isometries with irreducible and reciprocal minimal polynomial for integral lattices (with maximal equation order);
+- primitive embeddings/extensions for integral lattices;
+- equivariant primitive extensions for integral lattices;
+- miscellaneous operations on integral/rational quadratic form endowed with an isometry.
 
 ## Current applications of this project
 

experimental/QuadFormAndIsom/docs/src/latwithisom.md

@@ -15,7 +15,7 @@ ZZLatWithIsom
 ```
 
 It is seen as a quadruple $(Vf, L, f, n)$ where $Vf = (V, f_a)$ consists of
-the ambient rational quadratic space $V$ of $L$ and an isometry $f_a$ of $V$
+the ambient rational quadratic space $V$ of $L$, and an isometry $f_a$ of $V$
 preserving $L$ and inducing $f$ on $L$. The integer $n$ is the order of $f$,
 which is a divisor of the order of the isometry $f_a\in O(V)$.
 
@@ -115,8 +115,7 @@ rescale(::ZZLatWithIsom, ::RationalUnion)
 ## Type for finite order isometries
 
 Given a lattice with isometry $Lf := (L, f)$ where $f$ is of finite order $n$,
-one can compute the *type* of $Lf$, which can be seen as an equivalent of the
-*genus* used to classified single lattices.
+one can compute the *type* of $Lf$.
 
 ```@docs
 type(::ZZLatWithIsom)
@@ -183,6 +182,8 @@ project and it can be indirectly used through the general following method:
 image_centralizer_in_Oq(::ZZLatWithIsom)
 ```
 
+Note: hermitian Miranda-Morrison is only available for even lattices.
+
 For an implementation of the regular Miranda-Morrison theory, we refer to the
 function `image_in_Oq` which actually computes the image of
 $\pi$ in both the definite and the indefinite case.

experimental/QuadFormAndIsom/docs/src/primembed.md

@@ -25,11 +25,13 @@ given invariants (see Theorem 1.12.2 in [Nik79](@cite)). More generally, the
 author also provides methods to compute primitive embeddings of any even lattice
 into an even lattice of a given genus (see Proposition 1.15.1 in [Nik79](@cite)).
 In the latter proposition, it is explained how to classify such embeddings as
-isomorphic embeddings or as isomorphic sublattices.
+isomorphic embeddings or as isomorphic sublattices. Moreover, with enough care,
+one can generalize the previous results for embeddings in odd lattices.
 
-Such a method can be algorithmically implemented, however it tends to be slow
-and inefficient in general for large rank or determinant. But, in the case
-where the discriminant groups are (elementary) $p$-groups, the method can be
+A general method to compute primitive embeddings between integral lattices
+can be algorithmically implemented, however it tends to be slow and inefficient
+in general for large rank or determinant. But, in the case where the
+discriminant groups are (elementary) $p$-groups, the method can be made
 more efficient.
 
 We provide 4 kinds of output:
@@ -48,16 +50,15 @@ first input:
 
 ```@docs
 primitive_embeddings(::ZZGenus, ::ZZLat)
-primitive_embeddings(::TorQuadModule, ::Tuple{Int, Int},
-::ZZLat)
+primitive_embeddings(::TorQuadModule, ::Tuple{Int, Int}, ::ZZLat)
 ```
 
 In order to compute such primitive embeddings of a lattice $M$ into a lattice
 $L$, we follow the proof of Proposition 1.15.1 of [Nik79](@cite).
 
-Note: for the implementation of the algorithm, we construct an even lattice
-$T := M(-1)\oplus U$ where $U$ is a hyperbolic plane - $T$ is unique in its
-genus and $O(T)\to O(D_T)$ is surjective. We then classify all primitive
+Note: for the implementation of the algorithm, we construct a lattice $T$ which
+is unique in its genus, such that $D_T$ and $D_M(-1)$ are isometric and
+$O(T)\to O(D_T)$ is surjective. We then classify all primitive
 extensions of $M\oplus T$ modulo $O(D_T)$ (and modulo $O(M)$ for a
 classification of primitive sublattices). To classify such primitive
 extensions, we use Proposition 1.5.1 of [Nik79](@cite):
@@ -91,13 +92,12 @@ equivariant_primitive_extensions(::Union{ZZLatWithIsom, ZZLat}, ::Union{ZZLatWit
 ## Admissible equivariant primitive extensions
 
 The following function is a major tool provided by [BH23](@cite). Given
-a triple of integer lattices with isometry $((A, a), (B, b), (C, c))$ and two prime
-numbers $p$ and $q$ (possibly equal), if $(A, B, C)$ is $p$-admissible, this
-function returns representatives of isomorphism classes of equivariant primitive
+a triple of even integer lattices with isometry $((A, a), (B, b), (C, c))$
+and two prime numbers $p$ and $q$ (possibly equal), if $(A, B, C)$ is $p$-admissible,
+this function returns representatives of isomorphism classes of equivariant primitive
 extensions $(A, a)\oplus (B, b)\to (D, d)$ such that the type of $(D, d^q)$ is
 equal to the type of $(C, c)$ (see [`type(::ZZLatWithIsom)`](@ref)).
 
 ```@docs
 admissible_equivariant_primitive_extensions(::ZZLatWithIsom, ::ZZLatWithIsom, ::ZZLatWithIsom, ::IntegerUnion, ::IntegerUnion)
 ```
-