!! Computing with Maass waveforms
!! Program name: maasswf
!!
!! Author: Fredrik Stroemberg
!!
!! Programname: maasswf
!!
!! Version: 0.99v2
!! 
!! Date: 23 August 2008
!! 
!! Licence: The GNU General Public License (GPL v 3.0) 
!!	    (for details see the file gpl-3.0.txt)
!!
------------------------------
DESCRIPTION

1. Maass waveforms for the Fuchsian group $\Gamma$ are functions on the hyperbolic upper half-plane which are
   a) eigenfunctions of the hyperbolic Laplacian $\Delta=y^2 (d^2/dx^2 + d^2/dy^2)$
   b) invariant under $\Gamma$ (possibly with character) 
   c) some growth condition at the cusp or L^2-integrability.
   The functions you can compute with this package is (currently) cusp-forms,
   i.e. for congruence subgroups this is equivalent to being L^2 but in
   general this simply means that we have a Fourier expansion without constant term.

2. The functions in this package allows you locate Maass waveforms and to compute the Fourier
   coefficients of Maass waveforms on Hecke congruence groups with real
   characters.
   One *important* restriction of this version of the "maasswf" program is that we only use the normalization c(1)=1 and
   then set eigenvalues of Atkin-Lehner involutions. This means that we will
   be able to work with real Fourier expansions but in the case of non-trivial
   character we will not get Hecke eigenforms. 
   Further functionality includes making files for plotting or to use with
   lcalc (http://pmmac03.math.uwaterloo.ca/~mrubinst/L_function_public/L.html) 





-----------------------------
DEPENDENCIES

1. You need a Fortran 90/95 compiler. Currently supported compilers are 
    a.  g95 (recommended, see http://www.g95.org)
    b.  gfortran (http://gcc.gnu.org/fortran/)

2. You also need a c++ compiler for linking (this can be replaced by linking
   with the fortran compiler but then you have to rewrite the makefile)
   
3. If you have LAPACK3E (http://elib.zib.de/netlib/lapack3e/index.html)
   my program can use this to make a few things a bit faster when it comes to
   searching for eigenvalues. Since the LAPACK solver in general has worse precision than
   my solver I only use this in the coarse search for eigenvalues. 

-----------------------------
INSTALLATION

1. Extract the tarball:
 tar xzvf maasswf*.tar.gz
 
2. cd into the maasswf directory and edit the makefile.
   In particular check the following settings: 
   a) Set your basic installation directory:
      BASEDIR
   a) Change to your fortran 95 resp. c++ compilator:
      F90 and CC
      Only g95 and gfortran is currently supported.
      If you have another compilator you need to change the 
      variable FORTOPTS to reflect this.
   b) Set the variables FLDLIB, FORTLIB and FORTML too the correct directories
   c) If you have lapack3E installed and want to use it you should set 
      LAPACK=-Duse_lapack=true
      and set the variables LAPACKLIB and LAPACKDIRS to correct values
      otherwise comment out LAPACK, LLAPACK, LAPACKLIB and LAPACKDIRS
      (Lapack does speed some things up a little bit but is not necessary)   
   d) For debugging and profiling purposes use the variable FDEB

   Type make
   Now you have the program maasswf

------------------------------------
USAGE
1.	To see all options type
	    maasswf -h
EXAMPLES

1.	Find eigenvalues in the interval [0,5] for 
	Gamma_0(7) with trivial character.
	    ./maasswf -find 1 -Rs 0 -Rf 5 -lvl 7
	This produces the file
	     tmplist-7-0.000-0-0.00000-5.000000.txt
	consisting of the located eigenvalues and other information.
	The format of this file is:
	N k ch R mu0 [mu_1,...,mu_k] ep
	where 
	N  = Level
	k  = Weight
	ch = The number of the character (=0 for trivial character)
	R  = The spectral parameter
	mu0= 0/1 is the function is even/odd with respect to the reflection
	     in the imaginary axis
	[mu_1,...,mu_k] = Eigenvalues of Atkin-Lehner involutions
	corresponding to the cusps not equal to infinity
	ep = Error estimate

2.	Find eigenvalues in the interval [0,5] for 
	Gamma_0(5) with the real Dirichlet character.
	    ./maasswf -find 1 -Rs 0 -Rf 5 -lvl 5 -chr 1
	This produces the file
	     tmplist-5-0.000-1-0.00000-5.000000.txt	     
	in the same format as before.	     

3.	Compute 10000 coefficients for the first eigenvalue 
	in the file list.txt (in the same format as output by the above run)
	and output a header which can be used by the program lcalc (by Mike Rubinstein) 
	    ./maasswf -f list.txt -c 10000 -lcalc 1
	This produces two files: 
	     lcalc.he.5-0.000-1-3.26425130263651-1-c0-10000.txt
	     lcalc.co.5-0.000-1-3.26425130263651-1-c0-10000.txt
	and by concatenating these files you get a valid input file to lcalc

4.      Plot the first waveform on Gamma_0(5) with real Dirichlet character
        (from the file tmplist-5-0.000-1-0.00000-5.000000.txt produced prevoiusly)     
	      ./maasswf -start 1 -stop 1 -plot 1 -f   tmplist-5-0.000-1-0.00000-5.000000.txt
	This produces the file 
	     graph5-0.000-1-6.96387424068007-200x200_-0.50-0.50x0.01-1.01.txt
	containing data for the waveform in the rectangle
        [-0.5,0.5]x[0.01-1.01] with 200x200 points. The format of the file is
        as a large matrix and this file can then be plotted be for example
        SAGE and pylab with the following code: 
	     from pylab import * 
	     X=MatrixSpace(RR,200)
	     X=load('path-to-file/graph.txt') 
	     q=pcolor(X)
	     a=gca()
	     a.set_xticklabels(['-0.5','-0.25','0','0.25','0.5'])
	     a.set_yticklabels(['0.01','0.25','0.5','0.75','1.0'])
	     savefig('q.png')
	which saves the plot as q.png.


-------------------------
CONTENTS

This package contains the following directories and files:
maasswf-src/
maasswf-src/extras/			: Extra functions
maasswf-src/extras/_find_evs.f			: Locate eigenvalues, Phase 1
maasswf-src/extras/_grafik.f			: Plot eigenvalues
maasswf-src/extras/Makefile
maasswf-src/extras/_interf_to_cpp.f		: Some interface algorithms
						  (start of interface to C/C++)
maasswf-src/specfns/			: Special functions
maasswf-src/specfns/_whittaker.f		: Whittaker function
maasswf-src/specfns/_kbessel.f			: K-Bessel function
maasswf-src/specfns/Makefile
maasswf-src/specfns/_confluent.f		: Some instances of Confluent
						  Hypergeometric function
maasswf-src/commonvariables.f	        : Some variables and routines of
					  common use
maasswf-src/auxiliary/		        : Helper functions
maasswf-src/auxiliary/_interpolation.f		: Interpolation
maasswf-src/auxiliary/_numtheory.f		: Various number-theoretical functions
maasswf-src/auxiliary/Makefile
maasswf-src/auxiliary/_characters.f		: Manipulate character and multipliers
maasswf-src/auxiliary/_groups.f			: Init everything to do with
						  the underlying group 
maasswf-src/auxiliary/_matrix.f			: Functions for matrix manipulation
maasswf-src/README.txt				: This file
maasswf-src/gpl-3.0.txt				: GPL v 3.0 license text
maasswf-src/Makefile
maasswf-src/core/			: Core functions 
maasswf-src/core/_phase2.f			: Phase 2 algorithms
maasswf-src/core/_sys_solve.f			: Solving the system
maasswf-src/core/Makefile			
maasswf-src/core/_coefficients.f		: Computes various things with coefficients
maasswf-src/core/_newton.f			: Use Newton's algorithm to
						  find eigenvalues 
maasswf-src/core/_pullback.f			: Pullback into the
						  fundamental domain
maasswf-src/core/_system.f			: Set up the linear system
maasswf-src/maasswf.f			: Main program file with interface

-------------------------------------------------------

NOTES:
Observe that there is really no guarantee that the program finds all eigenvalues
in the requested interval. The automatic catching of eigenvalues will be
improved in further versions.  
Also, all error estimates are just that, estimates and not rigorously proven
in any way. 


