       HECKE
    Version 0.4
    Maintainer: William A. Stein (mailto:was@math.harvard.edu)
    With help from:
      Alexander F. Brown (No address known)
        Windows port
      Justin C. Walker (mailto:justin@mac.com)
        Update to more recent C++
        Update to recent version of LiDIA, NTL, gmp
        Wrestling Mac OS X into submission

This package is more or less as it was in 1999, when WAS last worked
on it.  Other than the porting effort, there is some additional code
by AFB that utilzes the classes provided by Hecke.

I have compiled and run this, with LiDIA2.1-pre7, NTL-5.3, and
GMP-4.1, on Mac OS X (10.2.5 and later), and Linux (Redhat 9.0).  On
Mac OS X, I have successfully used gcc 3.1 and gcc 3.3.  On Redhat
9.0, I used gcc 3.2.2.  I have had varying lack of success on both
platforms with earlier versions of the compilers.  I worked
successfully with LiDIA2.1-pre5 (except for the pesky 'power()'
problem mentioned below) on Mac OS X (10.2).  JCW: 9/03.

Included are 'hecke' executables for Redhat 9.0 and Mac OS X.  They
have been compiled statically against LiDIA and NTL, and assume the
presence of shared versions of GMP and other (more or less normal)
system libraries.

The following files were contributed by AFB:
    DoHeckeDisc.cc, Endo.cc, FindNonOrd.cc, Tau.cc

Contact:
   Stein: for mathematics (cc: Walker since he has an
          interest in this stuff).
   Walker: for compilation problems, language issues
   Someone Else for Windows issues.

Contents:
Readme by WAS, 1999
Readme by AFB for Windows

README.1999 (updated 2003)
       HECKE
    Version 0.4


Readme file for "HECKE: Modular Forms Calculator" project.
Last updated: September 24, 2003
Maintener: William Stein.

INSTALLING HECKE:
1. Obtain the executable file "hecke" and make sure it is executable:
        chmod +x hecke
2. Set the HECKE_HOME environment variable to the directory
   containing HECKE.  For example, by adding a line like
        export HECKE_HOME="/home/was/hecke"
   to your profile.
3. Also put the LiDIA_PRIMES files in HECKE_HOME.
4. Run HECKE by typing "hecke".  HECKE needs no additional
   files.  It will create two subdirectories, "data" and "userdata"
   where it stores the results of modular symbols computations
   for future use. 

BUILDING HECKE:
In case you want to try, here are some hints.   

The first thing to do is obtain and decompress the file
                    hecke-src_<date>.tgz
which can be found at
         http://modular.fas.harvard.edu/Tables/hecke-cpp.html
If you're reading this, then you probably already did that.

Hecke has been compiled on the following systems:
  - RedHat Linux 9.0 system, using gcc 3.2
  - Mac OS X 10.2.* and 10.3 using gcc 3.1 or gcc 3.3.1
  - Windows (see README.AFB)
The following freely available number theory class libraries are
assumed:

      (1) NTL 5.3           http://www.cs.wisc.edu/~shoup/ntl/

      (2) LiDIA 2.1pre7     ftp.informatik.tu-darmstadt.de in the directory
                            /pub/TI/systems/LiDIA/

      (3) gmp 4.1          http://www.swox.com/gmp

Note that hecke does *not* use PARI.

I may port hecke to other platforms (e.g., Solaris 2) as both NTL and
LiDIA are supported on many UNIX systems, but this has not been done yet.  
The main problem in porting is that HECKE uses templates extensively
to allow working over various ground fields.


              *********** FILES ***********

Hopefully this breakdown will make it possible to begin to understand
how it is put together.  This information is currently unchanged since
version 0.2, 1999.

Table of Contents
-----------------
1. ORGANIZATION
2. HECKE SOURCE FILES
3. CALCULATOR INTERFACES
4. CLIENT CODE
5. ARITHMETIC
6. LINEAR ALGEBRA
7. FIELDS
8. DISK MEMORY SYSTEM
9. SYSTEM INTERFACES
10. MISCELLANEOUS

1. ORGANIZATION
README          - this file.
back		- copies important source files to the Backup subdirectory
		  specified as an argument to back.
archive         - create the distribution hecke-src-date.tgz file
todo		- a list of suggestions and problems to solve, along with
		  a history of solutions to previous problems. 
makefile	- defines how to build hecke under g++.
		  type "make hecke" to build hecke.
doc		- one day this may contain a nice manual for hecke.


2. HECKE CORE SOURCE FILES
MODULAR SYMBOLS	- the following four files are the core modular symbols code.
character.cc,.h - defines "characters", i.e. a homomorphism 
                         (Z/NZ)^* -- C^*.
cusps.cc, .h    - used in computing the subspace of cuspidal symbols

h1nchi.cc, .h	- central object for working with modular symbols. 
		  impliments a _large_ amount of the functionality.
                   **** This is the core of Hecke. *****

h1nchiz.cc, .h  - extends h1nchi giving functions which only make sense / Z.

msymbols.cc, .h	- creates the Manin symbols for a given character,
		  and impliments the necessary hashing function,
		  searching and sorting. 
inst.cc		- Instantiates all of the templates. 


3. CALCULATOR INTERFACES
modularcalc.cc 
hecke.cc	- impliments one possible interactive user interface 
                  to all of the classes in the project.   the source code
                  also contains many examples and tests of the C++ 
                  class library. 

hecke		- the hecke calculator executable. 

methodofgraphs.cc, .h - a very simple minded implimentation of the mestre
                  "method of graphs" in the case of prime level. 


4. CLIENT CODE
tables.cc, .h	- routines for making tables

modformulas.cc,.h - C++ implimentation of Bruce Kaskel's PARI programs
		  for computing dimensions and numbers of cusps.
		  Also includes Hijikata's trace formula for computing
                  dimensions of spaces S_k(Gamma_0(N),chi) for chi
                  an arbitrary character. 



5. ARITHMETIC
arith.cc, .h	- many simple arithmetic functions like "gcd", and an 
		  interface to other libraries.   arithmetic of Z-modules.
charpoly.cc, .h - code for computing characteristic polynomials.
display.cc, .h	- code for displaying various objects. (This class
		  shouldn't exist.)


6. LINEAR ALGEBRA
array.cc, .h	- impliments arrays.
matrix.cc, .h   - matrix arithmetic, file i/o. 
sparsematrix.cc, .h - basis sparse matrices
sparse.cc, .h   - sparse matrix algorithms
vector.cc,. h	- vector arithmetic (also "polymods 
                  as vectors" arithmetic, which was probably a bad idea.)

7. RINGS and FIELDS
charmod.cc, .h  - Z/pZ for p stored in a byte
intmod.cc, .h	- Z/pZ for p an int
fields.cc, .h   - Wrappers for all of the other fields classes.
		  These mostly wrap LiDIA code, and add enough
		  functionality so that they will work with the
		  linear algebra template classes. 

8. DISK MEMORY SYSTEM
data		- This is hecke's "memory".  Most computations are 
		  stored here so that they won't have to be recomputed
		  next time hecke is run.  Each subdirectory is named
		  with a number which represents the level.  The files
		  in that subdirectory might look as follows:

37_0_Chi      			- trivial character
37_0_H1NChi_2_bigrational_Eigen - basis of cuspidal newforms *in terms*
37_0_H1NChi_2_bigrational_Mk	- table expressing each Manin symbol
				  in terms of the freely generating symbols.

37_0_H1NChi_2_bigrational_Sk
37_0_H1NChi_2_bigrational_Sknew
37_0_H1NChi_2_bigrational_Tn2
37_0_MSymbols_2              

*Important Note*: most of the saved tables are computed WITH RESPECT to the 
basis defined by the _Mk file.  If this file is changed, the other
data may become meaningless if a nondeterministic  method is used
at some step in the computation of _Mk.  I can't guarantee that this 
isn't the case when using some of the libraries like NTL
or LiDIA.  Thus, for safety, if _Mk is somehow accidentely deleted, 
you should delete the other files as well.  Also, for the same reason,
it is *NOT* safe to mix data directories computed on two different 
machines.  

One alternative (for me) would be to rewrite hecke so that it computes 
the basis _Mk in a well-defined manner.  This would be serious constraints on
the algorithms and be mathematically unpleasant.  Another alternative
would be to store _Mk as a header to each of the other data files,
but this is far too inefficient to be useable. 
		  
userdata	- this is where hecke stores the results of table
		  making routines


9. SYSTEM INTERFACES
system.cc, .h	- system i/o routines, error reporting 
                  routines, status messages

10. MISC.
LIDIA_PRIMES	- a list of primes, sometimes needed for the LiDIA functions.
                  (This is not included in the distribution, but comes
                  with LiDIA.)

 -- William Stein
    was@math.berkeley.edu
    University of California, Berkeley, California.
    May, 1999.


README.AFB

Since AFB hasn't surfaced recently, and I don't have interest in or
access to the appropriate systems, the Windows support is more or less
as AFB left it, after I got through getting it to build and run again
on Unix systems.  I tried to follow the Physician's Creed (First, do
no harm), but in matters software, one never knows.  JCW: 9/03

To build gmp:

cd /c/builds/gmp-4.1.2
./configure CFLAGS=-O2
make


To build LiDIA with MINGW:

. apply patch 3 to LiDIA-2.1pre7.  This is very important because the "power"
routine, which Hecke uses, is broken otherwise.
. remove the three elliptic curves packages -- elliptic curves,
elliptic curve order, elliptic curve generation.  They are not needed 
for Hecke, and the elliptic curve generation package (gec) does not compile
in MINGW just now.  (just remove the corresponding directories under 'src')
. remove all identifiers called "small" (rename them to "Small_number" or something)
Because the MINGW environment defines "small" to be a type.
. #ifndef WIN32 around the getppid line of base/system/random_generator.cc.
This function is apparently not provided by Win32.

cd /c/builds/LiDIA-2.1pre7
./configure --with-arithmetic=gmp --with-extra-includes=/c/builds/gmp-4.1.2   --with-extra-libs=/c/builds/gmp-4.1.2/.libs
make


To build NTL:

cd /c/builds/NTL-5.3.1
cd src
./configure NTL_STD_CXX=on NTL_GMP_LIP=on GMP_INCDIR=-I/c/builds/gmp-4.1.2   GMP_LIBDIR=-L/c/builds/gmp-4.1.2/.libs WIZARD=off
make
mv ntl.a libntl.a


To build Hecke:

. If compiling under UNIX, remove ".exe" in the makefile.

cd /c/builds/hecke
make hecke
