Mise à jour terminée. Pour connaître les apports de la version 13.8.4 par rapport à notre ancienne version vous pouvez lire les "Release Notes" suivantes :
https://about.gitlab.com/releases/2021/02/11/security-release-gitlab-13-8-4-released/
https://about.gitlab.com/releases/2021/02/05/gitlab-13-8-3-released/

Commit c41ae7fe authored by Emmanuel Thomé's avatar Emmanuel Thomé

move README to markdown format, prepare for transition to gitlab

parent 5be470f4
cmh: computation of genus 2 class polynomials.
==============================================
This software package computes Igusa (genus 2) class polynomials, which
parameterize the CM points in the moduli space of 2-dimensional abelian
......@@ -10,18 +11,39 @@ precision (but the interface for this is still to be documented more
clearly).
This documentation consists of several chapters.
- license;
- prerequisites;
- compiling;
- using;
- output;
- caveats;
- internal documentation: format of the output and input files;
- advanced usage, including (but not limited to) MPI.
- [Introduction](#introduction)
- [License](#license)
- [Prerequisites](#prerequisites)
- [Compiling](#compiling)
- [Using](#using)
- [Output](#output)
- [Caveats](#caveats)
- [Internal documentation](#internal-documentation)
- [Advanced usage, including (but not limited to) MPI](#advanced-usage-including-but-not-limited-to-mpi)
Introduction
------------
CMH computes Igusa class polynomials.
The main authors are:
- [Andreas Enge](http://www.math.u-bordeaux1.fr/~enge/)
- [Emmanuel Thomé](http://www.loria.fr/~thome/)
A code base by [Régis
Dupont](http://www.lix.polytechnique.fr/Labo/Regis.Dupont/) is at the
origin of this work.
In March, 2014, we announced the computation of class polynomials for
Shimura class number 20,016. See the separate [announcement
text](announcement-record-computation-cm2.txt) for this computation.
License
-------
```
cmh -- computation of genus 2 class polynomials and theta constants.
Copyright (C) 2006, 2010, 2011, 2012, 2013, 2014, 2015 Régis Dupont, Andreas
Enge, Emmanuel Thomé
......@@ -38,7 +60,7 @@ License
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
```
Prerequisites
-------------
......@@ -46,24 +68,12 @@ Prerequisites
The following software libraries are required to compile and use cmh;
we usually recommend to use the latest version and not the absolutely
minimally required one:
- GNU MP
http://gmplib.org/
version 4.3.2 or above
- GNU MPFR
http://mpfr.org/
version 2.4.2 or above
- GNU MPC
http://mpc.multiprecision.org/
version 1.0 or above
- MPFRCX
http://mpfrcx.multiprecision.org/
version 0.4.2 or above
- FPLLL
http://perso.ens-lyon.fr/damien.stehle/fplll/
version 4.0.4 or above
- PARI/GP
http://pari.math.u-bordeaux.fr/
version 2.7.0 or above
- [GNU MP](http://gmplib.org/) version 4.3.2 or above
- [GNU MPFR](http://mpfr.org/) version 2.4.2 or above
- [GNU MPC](http://mpc.multiprecision.org/) version 1.0 or above
- [MPFRCX](http://mpfrcx.multiprecision.org/) version 0.4.2 or above
- [FPLLL](http://perso.ens-lyon.fr/damien.stehle/fplll/) version 4.0.4 or above
- [PARI/GP](http://pari.math.u-bordeaux.fr/) version 2.7.0 or above
The following libraries are optional
- MPI implementation: any implementation can be used, e.g. openmpi,
......@@ -75,32 +85,32 @@ out, a reasonable explanation could be subtle distribution differences,
which are not that hard to fix, but terribly annoying indeed.
A convenience script for fetching and building all the software
prerequisites is in ./config/build-dependencies.sh ; this builds all the
needed packages in $topdir/cmh-deps, but can also be tuned to build
prerequisites is in `./config/build-dependencies.sh` ; this builds all the
needed packages in `$topdir/cmh-deps`, but can also be tuned to build
elsewhere (see the script for more information).
Compiling
---------
Distributed tarballs should ship with a ./configure shell script.
Development checkouts do not. For generating ./configure, please run the
./config/autogen.sh script, which requires the usual autotools
dependencies (autoconf, automake, libtool)
Distributed tarballs should ship with a `./configure` shell script.
Development checkouts do not. For generating `./configure`, please run the
`./config/autogen.sh` script, which requires the usual autotools
dependencies (`autoconf`, `automake`, `libtool`)
To compile and install, type:
```
./configure [[all relevant flags]]
make
make install
It might be very relevant to pass an appropriate --prefix option to the
```
It might be very relevant to pass an appropriate `--prefix` option to the
configure script, so that installation is done to a directory writable by
the user.
out-of-source build is supported.
The recognized flags are
```
--enable-mpi use mpi to compile a parallel version [default=no]
--with-gmp=DIR GMP installation directory
--with-mpfr=DIR MPFR installation directory
......@@ -108,134 +118,125 @@ The recognized flags are
--with-mpfrcx=DIR MPFRCX installation directory
--with-fplll=DIR FPLLL installation directory
--with-pari=DIR PARI installation directory
```
For MPI, see the section later in this document.
Note that "make install" is *not* optional, since making the program run
without doing "make install" first is difficult.
Note that `make install` is *not* optional, since making the program run
without doing `make install` first is difficult.
Using
-----
The input to this program is a defining equation for a (for the moment,
only dihedral) quartic CM field, in the form of two nonnegative integers
A,B for a corresponding defining equation X^4+A*X^2+B. The pair (A,B)
must be so that A^2-4*B is a positive integer which is not a perfect
square, and (A,B) minimal in the sense that no smaller pair defines the
same field (the script complains if this is the case). The special case
where the Galois group of X^4+A*X^2+B is Z/2 * Z/2 is also forbidden.
$`A`$,$`B`$ for a corresponding defining equation $`X^4+A X^2+B`$. The
pair $`(A,B)`$ must be so that $`A^2-4B`$ is a positive integer which is
not a perfect square, and $`(A,B)`$ minimal in the sense that no smaller
pair defines the same field (the script complains if this is the case).
The special case where the Galois group of $`X^4+A X^2+B`$ is $`Z/2
\times Z/2`$ is also forbidden.
The main entry point is the script placed in the following location by
"make install":
`make install`:
```
$prefix/bin/cmh-classpol.sh
```
Its syntax is:
```
$prefix/bin/cmh-classpol.sh -p -f A B
```
where A and B are the integers defining the CM field as discussed above.
This, in effects, does the two out of three possible steps.
- The -p option does the "preparation", which consists in computing a
where $`A`$ and $`B`$ are the integers defining the CM field as discussed
above. This, in effects, does the two out of three possible steps.
- The `-p` option does the "preparation", which consists in computing a
list of period matrices corresponding to one orbit under complex
multiplication. This list ends up in the .in file (see next section
multiplication. This list ends up in the `.in` file (see next section
for location and naming).
- The -f option does the big part of the computation, which is the
- The `-f` option does the big part of the computation, which is the
computation of class polynomials from the config files. This is
programmed in C (here and there, when we refer to "the C code", this
designates the code which gets run for this step). An optional feature
is provided for doing this step in parallel over several processors or
nodes. The output ends up in the .pol file (again see below).
nodes. The output ends up in the `.pol` file (again see below).
Additionally, adding the -c flag does a third step, which checks the
computed class polynomial for correctness as follows (see also BUGS).
- find a Weil number p
Additionally, adding the `-c` flag does a third step, which checks the
computed class polynomial for correctness as follows (see also
[`BUGS`](BUGS)).
- find a Weil number $`p`$
- find a triple of Igusa invariants corresponding to roots of the class
polynomials mod p
polynomials mod $`p`$
- use Mestre's algorithm to reconstruct a hyperelliptic curve from its
invariants
- check that the Jacobian of the curve above has cardinal Norm(1\pm pi).
- check that the Jacobian of the curve above has cardinal `$\operatorname{Norm}(1\pm pi)$`.
Some other flags are mostly for interal use. Noteworthy ones are -N,
which disables the temporary checkpoint data creation, and -b xxxx, which
Some other flags are mostly for interal use. Noteworthy ones are `-N`,
which disables the temporary checkpoint data creation, and `-b xxxx`, which
modifies the starting precision.
Output
------
All output of the program goes to the data/ directory (which may be a
All output of the program goes to the `data/` directory (which may be a
symbolic link to auxiliary storage).
All files are created with a common prefix D_A_B, where D,A,B are three
integers. A and B are the integers discussed above, while D is the
All files are created with a common prefix `D_A_B`, where $`D`$,$`A`$,$`B`$ are three
integers. $`A`$ and $`B`$ are the integers discussed above, while $`D`$ is the
discriminant of the real quadratic subfield (this is the fundamental
discriminant of Q(sqrt(A^2-4B)).
The files are:
- D_A_B.in description of the set of period matrices describing
the different irreducible factors of the class
polynomials. The format of this file is used
internally, but its details are discussed in the
"internal details" section.
- D_A_B.pol the different irreducible factors of the class
polynomials (more precisely of the CM variety in the
moduli space). This is given in triangular form
(H1,H2hat,H3hat), and discussed in the "internal
details" section. These polynomials are defined over
the real quadratic subfield of the reflex field.
- D_A_B.gp.log output (terse) of the pari/gp program which computes
the .in file from (A,B)
- D_A_B.out output of the C code for computing .pol from .in
- D_A_B.check.log output of the pari/gp program which computes a
hyperelliptic curve whose Jacobian has CM by the
desired field, and checks its cardinality for
consistency with the expected value.
[ only if -c was provided on the command line of
cmh-classpol.sh ]
- D_A_B/ temporary checkpointing and restart data. The
precise meaning and format of these files is not
documented, and subject to incompatible change
without notice.
discriminant of $`\mathbb{Q}(\sqrt{A^2-4B})`$.
| file name | description |
| ----------------- | ----------------------------------------------------------
| `D_A_B.in` | description of the set of period matrices describing the different irreducible factors of the class polynomials. The format of this file is used internally, but its details are discussed in the "internal details" section. |
| `D_A_B.pol` | the different irreducible factors of the class polynomials (more precisely of the CM variety in the moduli space). This is given in triangular form `(H1,H2hat,H3hat)`, and discussed in the "internal details" section. These polynomials are defined over the real quadratic subfield of the reflex field. |
| `D_A_B.gp.log` | output (terse) of the pari/gp program which computes the `.in` file from (A,B) |
| `D_A_B.out` | output of the C code for computing `.pol` from `.in` |
| `D_A_B.check.log` | output of the pari/gp program which computes a hyperelliptic curve whose Jacobian has CM by the desired field, and checks its cardinality for consistency with the expected value. [ only if `-c` was provided on the command line of cmh-classpol.sh ] |
| `D_A_B/` | temporary checkpointing and restart data. The precise meaning and format of these files is not documented, and subject to incompatible change without notice. |
Caveats
-------
See BUGS
See [`BUGS`](BUGS)
Internal documentation
----------------------
The .in and .pol file formats are discussed in README.format.
The `.in` and `.pol` file formats are discussed in
[`README.format`](README.format)
Advanced usage, including (but not limited to) MPI
--------------------------------------------------
The main C binary which is used to compute class polynomials (the .pol
file) from orbits of period matrices (the .in file) has an MPI version.
This version can be compiled by passing --enable-mpi to configure.
The main C binary which is used to compute class polynomials (the `.pol`
file) from orbits of period matrices (the `.in` file) has an MPI version.
This version can be compiled by passing `--enable-mpi` to configure.
The non-parallel binary is called cm2, and the binary is created in the
$builddir/src. "make install" installs cm2 in $prefix/bin/cm2
The non-parallel binary is called `cm2`, and the binary is created in the
`$builddir/src`. `make install` installs `cm2` in `$prefix/bin/cm2`
The parallel binary is called cm2-mpi, and the binary is created in the
$builddir/src. Obviously, cm2-mpi is created only if --enable-mpi is
passed to configure. "make install" installs cm2-mpi in
$prefix/bin/cm2-mpi
The parallel binary is called `cm2-mpi`, and the binary is created in the
`$builddir/src`. Obviously, `cm2-mpi` is created only if `--enable-mpi` is
passed to configure. `make install` installs `cm2-mpi` in
`$prefix/bin/cm2-mpi`
If you intend to use MPI for computing the class polynomials, this very
likely means that you are well beyond the intended scope for the
cmh-classpol.sh script. For this reason, cmh-classpol.sh has no provision
for calling cm2-mpi directly, and this binary must be called manually.
We assume that you have successfully created a .in file (using
cmh-classpol.sh -p). Then, the syntax for cm2, or cm2-mpi, is:
`cmh-classpol.sh` script. For this reason, `cmh-classpol.sh` has no provision
for calling `cm2-mpi` directly, and this binary must be called manually.
We assume that you have successfully created a `.in` file (using
`cmh-classpol.sh -p`). Then, the syntax for `cm2`, or `cm2-mpi`, is:
```
cm2 -i D_A_B.in -o D_A_B.pol [other flags]
mpirun -n #jobs [other mpi options] cm2-mpi -i D_A_B.in -o D_A_B.pol [other flags]
```
This will eventually write the result in D_A_B.pol ; the code has
This will eventually write the result in `D_A_B.pol` ; the code has
provision for resuming interrupted computations, as intermediate
computation checkpoints are saved in a subdirectory called D_A_B/ ;
computation checkpoints are saved in a subdirectory called `D_A_B/` ;
checkpoints are enabled by default, but they may be disabled using the
--no-checkpoints command-line option.
`--no-checkpoints` command-line option.
Subject: Genus 2 CM construction for class number 20,016
Dear number theorists,
We are pleased to announce the successful construction of a genus 2
hyperelliptic Jacobian over a 128-bit prime field, using the complex
multiplication method, for an input CM field of class number 20,016.
The computation was performed using the complex analytic method, using
the implementation [3], which is described in [2]. Important
characteristics of this implementation is the ability to compute
theta-constants in quasi-linear complexity in the input size. Earlier
work by Dupont was used as a starting point for this project [1].
We are aware of previous existing computation using this method. To our
knowledge, the largest of these is for a CM field of class number 530 [4].
The input of the computation is the CM field K given by the defining
equation x^4+1357*x^2+3299s. The class group of K has structure
Z/2*Z/4*Z/5004. The real quadratic subfield K0 is Q(sqrt(1828253)), whose
class number is 2. The Shimura class group C(K) is isomorphic to
Z/2*Z/2*Z/5004, and thus has size 20,016. The size of the Shimura class
group corresponds to the degree of the irreducible factors (over K0r, the
real quadratic subfield of the reflex field Kr of K) of the Igusa class
polynomials.
The most important part of the computation was the computation of the
Igusa class polynomials (H1, \hat H2, \hat H3). These were computed
relative to the choice of invariants proposed in [5].
Computing (H1, \hat H2, \hat H3) required computing complex
approximations of 10,008 pairs of complex conjugate triples of Igusa
invariants, associated to a set of period matrices.
The breakdown of the computation times goes as follows.
- Computation of the period matrices defined over the reflex field of K:
388 s
- First steps of Newton lifting up to precision roughly 2,000,000 bits:
610 s per period matrix (1,700 hours total).
- Last two steps of Newton lifting up to precision roughly 8,000,000 bits:
3,040 s per period matrix. 8,451 hours total. 2 days wall-clock time.
- Computation of floating point polynomials H1, \hat H2, \hat H3:
3 days wall-clock time.
- Recognition of polynomial coefficients as elements of K0r:
980 s per coefficient. 16,350 hours total. 2 days wall-clock time.
All computation steps have been performed in parallel over up to several
hundreds of CPU cores, to the extent allowed by the constraints of the
various steps of the computation. A variety of hardware platforms have
been used, the most common being Intel Nehalem-based and Sandy
Bridge-based processors with 2 GHz clock frequency (see [3] for details).
The uncompressed storage size of the three resulting polynomials in base
10 is about 95 GB. The common denominator of the coefficients of H1 has
8884 distinct prime factors, the largest one being 1506803839.
In order to validate the computation, the construction of a genus 2 curve
was done. We picked the prime number p=2^128+5399685, and the following
Weil number:
pi:=2587584949432298*y^3 + 598749326588980*y^2 + 3489110163205995872*y - 17626367557116479015;
where y is a root of t^4+1357*t^2+3299;
The evaluation of the Igusa class polynomials at a single root of H1 gave
a triple of Igusa invariants, to which we applied Mestre's algorithm for
reconstructing a curve from its invariants. The hyperelliptic curve
obtained has the following equation over GF(p):
y^2 = 329105434147215182703081697774190891717*x^5 + 219357712933218699650940059644263138156*x^4 + 94773520721686083389380651745963315116*x^3 + 13612280714446818104030347122109215819*x^2 + 224591198286067822213326173663420732292*x + 62350272396394045327709463978232206155;
The complex multiplication theory predicts the cardinal of the Jacobian,
which we have been able to validate as being equal to:
Norm(1-pi) = 115792089237316195448115714075359184294817543055097597784192266245863261539824
This validation of the computation took roughly 20 minutes, mostly
dominated by the input-output time required to reduce the class
polynomial modulo p (part of the computation was offloaded to a nearby
cluster).
All computations have been performed by cmh-1.0, which is programmed in C
and pari/gp, and can be freely downloaded.
Questions regarding characteristics of the data computed (prime numbers
appearing in the denominator, etc) may be directed to the authors.
Andreas Enge,
Emmanuel Thomé.
[1] R. Dupont. Moyenne arithmético-géométrique, suites de Borchardt et
applications. Thèse, École Polytechnique, 2006.
http://www.lix.polytechnique.fr/Labo/Regis.Dupont/these_soutenance.pdf
[2] A. Enge, E. Thomé, Computing class polynomials for abelian surfaces.
To appear in Experimental Mathematics, 2014.
http://hal.inria.fr/hal-00823745/
[3] A. Enge, E. Thomé, cmh: Computation of Igusa Class Polynomials,
version 1.0, 2014.
http://cmh.gforge.inria.fr/
[4] T. Houtmann, Complex multiplication in genus 2, 2007.
http://tiresias.dyndns-at-home.com/cm/
[5] M. Streng, Complex multiplication of abelian surfaces. PhD thesis,
Universiteit Leiden, 2010.
http://hdl.handle.net/1887/15572
Verification script in magma:
p:=340282366920938463463374607431773611141;
A:=1357;
B:=3299;
K:=GF(p);
KP<x>:=PolynomialRing(GF(p));
C:=HyperellipticCurve(329105434147215182703081697774190891717*x^5 +
219357712933218699650940059644263138156*x^4 +
94773520721686083389380651745963315116*x^3 +
13612280714446818104030347122109215819*x^2 +
224591198286067822213326173663420732292*x +
62350272396394045327709463978232206155);
J:=Jacobian(C);
ZP<t>:=PolynomialRing(Integers());
K<y>:=NumberField(t^4+A*t^2+B);
pi:=2587584949432298*y^3 + 598749326588980*y^2 + 3489110163205995872*y
- 17626367557116479015;
assert Norm(pi) eq p^2;
assert IsZero(Integers()!Norm(1-pi)*Random(J));
chi:=CharacteristicPolynomial(pi);
s1:=-Coefficient(chi,3);
s2:=Coefficient(chi,2);
assert Coefficient(chi,1) eq -p*s1;
assert Coefficient(chi,0) eq p^2;
/* The curve C has p+1-s1 points over GF(p) */
assert IsZero(Discriminant(ZP!chi) mod Discriminant(MaximalOrder(K)));
J`EulerFactor:=ReciprocalPolynomial(chi);
J`Order:=Norm(1-pi);
/* base-extend to GF(p^3), for a check */
n:=3;
Jn:=BaseChange(J,n);
ZP1:=PolynomialRing(Integers());
ZP2:=PolynomialRing(ZP1);
E1:=ZP1!J`EulerFactor;
E:=Evaluate(E1,ZP2.1);
P:=ZP2.1^n-ZP1.1;
En:=Resultant(E,P);
assert(IsZero(Evaluate(En,1)*Random(Jn)));
Jn`EulerFactor:=En;
Jn`Order:=Evaluate(En,1);
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment