       HECKE
    Version 0.2


Readme file for "HECKE: Modular Forms Calculator" project.
Last updated: May 1, 1999. 
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://shimura.math.berkeley.edu/~was/Tables/hecke.html
If you're reading this, then you probably already did that.

Hecke can be compiled on a RedHat Linux 5.2 system on which the following
freely available number theory class libraries are installed:

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

      (2) LiDIA 1.3.2       ftp.informatik.tu-darmstadt.de in the directory
                            /pub/TI/systems/LiDIA/LiDIA-1.3.x/LiDIA-1.3.2/

Note that hecke does *not* use PARI.
I compile hecke on gcc version 2.7.2.3.

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.  

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.



