Commit 9c4a19e3 authored by Emmanuel Thomé's avatar Emmanuel Thomé

some preparatory files for releasing this code at some point.

parent 23d4e4dc
This diff is collapsed.
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
varieties, i.e. Jacobians of hyperelliptic curves.
This program is also able
This documentation consists of several chapters.
- authors;
- license;
- prerequisites;
- compiling;
- using;
- output;
- caveats;
- internal documentation: format of the output and input files.
Authors
-------
The authors of cmh are:
- Régis Dupont, author of original code base in 2006;
- Andreas Enge, co-author of cmh as of now, 2010-present;
- Emmanuel Thomé, co-author of cmh as of now, 2010-present.
All requests regarding the code are to be sent to the last two authors.
License
-------
cmh -- computation of genus 2 class polynomials and theta constants.
Copyright (C) 2006, 2010, 2011, 2012, 2013 Régis Dupont, Andreas
Enge, Emmanuel Thomé
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
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
-------------
The following software libraries are required to compile and use cmh:
- Gnu MP, or alternately MPIR ;
http://gmplib.org/
- Gnu MPFR ;
http://mpfr.org/
- Gnu MPC ;
http://mpc.multiprecision.org/
- MPFRCX ;
http://mpfrcx.multiprecision.org/
- FPLLL ;
http://perso.ens-lyon.fr/damien.stehle/fplll/
- Pari/GP ;
http://pari.math.u-bordeaux.fr/
The following libraries are optional
- MPI implementation ; any implementation can be used, e.g. openmpi,
mpich, mvapich2, ...
Compiling
---------
To compile, type:
make
At this moment there is no "make install" target.
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. This pair (A,B) is
expected to be minimal.
The main entry point is the script:
./scripts/cmh.sh
Its syntax is:
./scripts/cmh.sh -gg -f A B
where A and B are the integers defining the CM field as discussed above.
Additionally, adding the -c flag checks the computed class polynomial for
correctness as follows:
- find a Weil number p
- find a triple of Igusa invariants corresponding to roots of the class
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).
Output
------
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
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.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
-------
For the moment, X^4+A*X^2+B must define a *dihedral* quartic CM field.
This means that Galois quartic CM field are not supported. This will be
fixed, at least for CM fields with Galois groups Z/4, in the near future.
Fields with Galois group Z/2\times Z/2 will probably not be fixed
however, as handling them is rather in the ballpark of the genus 1 CM
method.
In some cases, the curve reconstruction mail fail to check correctness.
These cases correspond to those where the Jacobian has no imaginary
model, i.e. when its equation is of the form y^2 = x^6 + something. In
such cases, while the Jacobian cardinal is probably among the expected
ones, the program fails to check for it, because of lacking functionality
in the code. This will probably be fixed at some point, but no urgency
for this is felt.
Examples with very small class number may trigger abnormal computation
times, due to a shortcoming in the factoring process. While this is an
acknowledged bug and does deserve a fix, it is not clear that it will be
fixed shortly. It will, eventually.
Internal documentation
----------------------
The .in and .pol file formats are discussed in README.format.
TODO:
- autotools ; also update the compilation instruction in the README
- make sure that README.format is accurate (is the precision still
there?)
- fix the Galois case ; also update the caveat section in the README
- clean up the scripts/ directory
- do we keep the magma/ directory ?
- ./scripts/cmh.sh is the main entry point of the program. Do we move it
to the toplevel, and do we improve its command line ? (also update the
"using" section in the README)
- do we provide "make install" functionality ? What do we install ?
- implement a way to disable the temp file creation and reading ;
implement a way to forcibly ignore pre-existing temp files.
- README: document the use beyond cmh.sh, in particular the multithreaded
use.
MAYBE:
- provide a calling interface for the computation of theta constants
- fix the hyperelliptic-curve-does-not-have-an-imaginary-model issue ;
also update the caveat section in the README
- provide an online database ?
DONE:
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