Quadratic forms and isometries - an Oscar (experimental) project (#2563)

docs/oscar_references.bib

@@ -133,6 +133,17 @@ @Book{BH09
   year          = {2009}
 }
 
+@Article{BH23,
+  author        = {Brandhorst, Simon and Hofmann, Tommy},
+  title         = {Finite subgroups of automorphisms of K3 surfaces},
+  journal       = {Forum of Mathematics, Sigma},
+  volume        = {11},
+  publisher     = {Cambridge University Press, Cambridge},
+  pages         = {e54 1--57},
+  year          = {2023},
+  doi           = {10.1017/fms.2023.50}
+}
+
 @Misc{BHMPW20,
   author        = {Braden, Tom and Huh, June and Matherne, Jacob P. and Proudfoot, Nicholas and Wang, Botong},
   title         = {A semi-small decomposition of the Chow ring of a matroid},

experimental/QuadFormAndIsom/README.md

@@ -0,0 +1,75 @@
+# Quadratic forms and isometries
+
+This project is a complement to the code about *hermitian lattices* available
+in Hecke. We aim here to connect Hecke and GAP to handle some algorithmic
+methods regarding quadratic forms with their isometries. In particular,
+the integration of this code within Oscar is necessary to benefit from all the
+performance of GAP with respect to computations with groups and automorphisms in
+general.
+
+For now, the project covers methods regarding rational and integral quadratic
+forms.
+
+## Content
+
+We introduce two new structures
+* `QuadSpaceWithIsom`
+* `ZZLatWithIsom`
+The former parametrizes pairs $(V, f)$ where $V$ is a rational quadratic form
+and $f$ is an isometry of $V$. The latter parametrizes pairs $(L, f)$ where
+$L$ is an integral quadratic form, also known as $\mathbb Z$-lattice and $f$
+is an isometry of $L$. One of the main features of this project is the
+enumeration of isomorphism classes of pairs $(L, f)$, where $f$ is an isometry
+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 two
+functions `primitive_embeddings_in_primary_lattice` and
+`primitive_embeddings_of_primary_lattice` offer, 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.
+
+Among the possible improvements and extensions:
+* Implement extra methods for lattices with isometries of infinite order;
+* Extend the methods for classification of primitive embeddings to the more
+  general case (knowing that we lose efficiency for large discriminant groups);
+* Extend existing methods for equivariant primitive embeddings/extensions.
+
+## Currently application of this project
+
+The project was initiated by S. Brandhorst and T. Hofmann for classifying
+finite subgroups of automorphisms of K3 surfaces. Our current goal is to use
+this code, and further extensions of it, to classify finite subgroups of
+bimeromorphic self-maps of *hyperkaehler manifolds*, which are a higher
+dimensional analogues of K3 surface.
+
+## Notice to the user
+
+Since this project is still under development, feel free to try any feature and
+report all the bugs you may have found. Any suggestions for improvements or
+extensions are more than welcome. Refer to the next section to know who you
+should contact and how. Do not hesitate either to ask for new features - we
+will be glad to add anything you may need for your research.
+
+One may expect many things to vary within the next months: name of the
+functions, available features, performance. This is due to the fact that the
+current version of the code is still at an experimental stage.
+
+## Contact
+
+Please direct questions about this part of OSCAR to the following people:
+* [Simon Brandhorst](https://www.math.uni-sb.de/ag/brandhorst/index.php?lang=en),
+* [Tommy Hofmann](https://www.thofma.com/)
+* [Stevell Muller](https://www.math.uni-sb.de/ag/brandhorst/index.php?option=com_content&view=article&id=26:muller-en-1&catid=18&lang=en&Itemid=114).
+
+You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
+
+Alternatively, you can [raise an issue on GitHub](https://github.com/oscar-system/Oscar.jl).

experimental/QuadFormAndIsom/docs/doc.main

@@ -0,0 +1,9 @@
+[
+  "Quadratic forms and isometries" => [
+      "introduction.md",
+      "spacewithisom.md",
+      "latwithisom.md",
+      "enumeration.md",
+      "primembed.md"
+  ]
+]

experimental/QuadFormAndIsom/docs/src/enumeration.md

@@ -0,0 +1,89 @@
+```@meta
+CurrentModule = Oscar
+```
+
+# Enumeration of isometries
+
+One of the main features of this project is the enumeration of 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
+reference.
+
+## Admissible triples
+
+Roughly speaking, for a prime number $p$, a *$p$-admissible triple* `(A, B, C)`
+is a triple of integer lattices such that, in certain cases, `C` can be obtained
+as a primitive extension $A \perp B \to C$ where one can glue along
+$p$-elementary subgroups of the respective discriminant groups of `A` and `B`.
+Note that not all admissible triples satisfy this extension property.
+
+For instance, if $f$ is an isometry of an integer lattice `C` of prime order
+`p`, then for $A := \ker \Phi_1(f)$ and $B := \ker \Phi_p(f)$, one has that
+`(A, B, C)` is $p$-admissible (see Lemma 4.15. in [BH23](@cite)).
+
+We say that a triple `(AA, BB, CC)` of genus symbols for integer lattices is
+*$p$-admissible* if there are some lattices $A \in AA$, $B \in BB$ and
+$C \in CC$ such that $(A, B, C)$ is $p$-admissible.
+
+We use Definition 4.13. and Algorithm 1 of [BH23](@cite) to implement the necessary
+tools for working with admissible triples. Most of the computations consists of
+local genus symbol manipulations and combinatorics. The code also relies on
+enumeration of integer genera with given signatures, determinant and bounded
+scale valuations for the Jordan components at all the relevant primes (see
+[`integer_genera`](@ref)).
+
+```@docs
+admissible_triples(::ZZGenus, p::Integer)
+is_admissible_triple(::ZZGenus, ::ZZGenus, ::ZZGenus, ::Integer)
+```
+
+Note that admissible triples are mainly used for enumerating lattices with
+isometry of a given order and in a given genus.
+
+## Enumeration functions
+
+We give an overview of the functions implemented for the enumeration of the
+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
+
+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
+the functions available. We therefore provide a general function which
+allows one to enumerate lattices with isometry of a given order and in a given
+genus. The only requirements are to provide a genus symbol, or a lattice from
+this genus, and the order wanted (as long as the number of distinct prime
+divisors is at most 2).
+
+```@docs
+enumerate_classes_of_lattices_with_isometry(::ZZLat, ::IntegerUnion)
+```
+
+As a remark: if $n = p^dq^e$ is the chosen order, with $p < q$ prime numbers,
+the previous function computes first iteratively representatives for all classes
+with isometry in the given genus of order $q^e$. Then, the function increases
+iteratively the order up to $p^dq^e$.
+
+### Underlying machinery
+
+Here is a list of the algorithmic machinery provided by [BH23](@cite) used
+previously to enumerate lattices with isometry:
+
+```@docs
+representatives_of_hermitian_type(::ZZLatWithIsom, ::Int)
+splitting_of_hermitian_prime_power(::ZZLatWithIsom, ::Int)
+splitting_of_prime_power(::ZZLatWithIsom, ::Int, ::Int)
+splitting_of_pure_mixed_prime_power(::ZZLatWithIsom, ::Int)
+splitting_of_mixed_prime_power(::ZZLatWithIsom, ::Int, ::Int)
+```
+
+Note that an important feature from the theory in [BH23](@cite) is the notion of
+*admissible gluings* and equivariant primitive embeddings for admissible triples.
+In the next chapter, we present the methods regarding Nikulins's theory on primitive
+embeddings and their equivariant version. We use this basis to introduce the
+method `admissible_equivariant_primitive_extension` (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

@@ -0,0 +1,116 @@
+# Quadratic forms and isometries
+
+This project is a complement to the code about *hermitian lattices* available
+in Hecke. We aim here to connect Hecke and GAP to handle some algorithmic
+methods regarding quadratic forms with their isometries. In particular,
+the integration of this code within Oscar is necessary to benefit from all the
+performance of GAP with respect to computations with groups and automorphisms in
+general.
+
+For now, the project covers methods regarding rational and integral quadratic
+forms.
+
+## Content
+
+We introduce two new structures
+* [`QuadSpaceWithIsom`](@ref)
+* [`ZZLatWithIsom`](@ref)
+The former parametrizes pairs $(V, f)$ where $V$ is a rational quadratic form
+and $f$ is an isometry of $V$. The latter parametrizes pairs $(L, f)$ where
+$L$ is an integral quadratic form, also known as $\mathbb Z$-lattice and $f$
+is an isometry of $L$. One of the main features of this project is the
+enumeration of isomorphism classes of pairs $(L, f)$, where $f$ is an isometry
+of finite order with at most two prime divisors. The methods we resort to
+for this purpose are developed in the paper [BH23].
+
+We also provide some algorithms computing isomorphism classes of primitive
+embeddings of even lattices following Nikulin's theory. More precisely, the two
+functions `primitive_embeddings_in_primary_lattice` and
+`primitive_embeddings_of_primary_lattice` offer, 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.
+
+Among the possible improvements and extensions:
+* Implement extra methods for lattices with isometries of infinite order;
+* Extend the methods for classification of primitive embeddings to the more
+  general case (knowing that we lose efficiency for large discriminant groups);
+* Extend existing methods for equivariant primitive embeddings/extensions.
+
+## Currently application of this project
+
+The project was initiated by S. Brandhorst and T. Hofmann for classifying
+finite subgroups of automorphisms of K3 surfaces. Our current goal is to use
+this code, and further extensions of it, to classify finite subgroups of
+bimeromorphic self-maps of *hyperkaehler manifolds*, which are a higher
+dimensional analogues of K3 surface.
+
+## Tutorials
+
+No tutorials available at the moment.
+
+## Examples
+
+No examples available at the moment.
+
+## Notice to the user
+
+### Disclaimer
+
+Since this project is still under development, feel free to try any feature and
+report all the bugs you may have found. Any suggestions for improvements or
+extensions are more than welcome. Refer to the next section to know who you
+should contact and how. Do not hesitate either to ask for new features - we
+will be glad to add anything you may need for your research.
+
+One may expect many things to vary within the next months: name of the
+functions, available features, performance. This is due to the fact that the
+current version of the code is still at an experimental stage.
+
+### Report an issue
+
+If you are working with some objects of type `QuadSpaceWithIsom` or `ZZLatWithIsom`
+and you need to report an issue, you can produce directly some lines of codes
+helping to reconstruct your example. This can help the reviewers to understand
+your issue and assist you. We have implemented a method `to_oscar` which
+prints few lines of codes for reconstructing your example.
+
+```@repl 2
+using Oscar # hide
+V = quadratic_space(QQ, 2);
+Vf = quadratic_space_with_isometry(V, neg = true)
+Oscar.to_oscar(Vf)
+
+Lf = lattice(Vf)
+Oscar.to_oscar(Lf)
+```
+
+## Make the code more talkative
+
+Within the code, there are more hidden messages and testing which are disabled
+by default. If you plan to experiment with the codes with your favourite
+examples, you may want to be able to detect some issues to be reported, as well
+as knowing what the code is doing. Indeed, some functions might take time in
+term of compilation but also computations. For this, you can enable these extra
+tests and printings by setting:
+
+```julia
+Oscar.set_lwi_level(2)
+```
+
+## Contact
+
+Please direct questions about this part of OSCAR to the following people:
+* [Simon Brandhorst](https://www.math.uni-sb.de/ag/brandhorst/index.php?lang=en),
+* [Tommy Hofmann](https://www.thofma.com/)
+* [Stevell Muller](https://www.math.uni-sb.de/ag/brandhorst/index.php?option=com_content&view=article&id=26:muller-en-1&catid=18&lang=en&Itemid=114).
+
+You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
+
+Alternatively, you can [raise an issue on GitHub](https://github.com/oscar-system/Oscar.jl).