README for ell.g

2000/9/13, Nils Bruin

DESCRIPTION AND LICENSE

This package implements elliptic curves over several ring types in KASH. The
main feature is the 2-(isogeny-)descent routines for curves over arbitrary
number fields. This package is distributed as a scientific publication.
You are free to use it. If you obtain publishable results with it, please make
an appropriate reference. It's hard work writing such a package.

Due to the preliminary nature of this release (beta or something like
that), please do NOT give copies to other people. Instead, refer them to
http://www.msri.org/people/members/bruin/ell.shar

DISCLAIMER

The author does not claim any correctness or purpose of the package. You are
free to use it, but in no way shall the author be held responsible for any
damages caused by the use of this package. If you find bugs, I'd like to hear
them, but I do not guarantee any support.

INSTALLATION

This package is developed for KASH 2.2 on a UNIX system with LaTeX and Perl,
but it is probably useful on any platform supporting KASH 2.2. 

There is some extra functionality if Cremona's mwrank is present. In this case,
it is expected that the program mwrank can be found in the normal paths. Edit
the Perl-script mwkash if this is not the case. The program "mwrank" can be
obtained from:

http://www.maths.nott.ac.uk/personal/jec/ftp/progs/

Proceed in the following way to install the package (I presume you have
ell.shar)

1. Make sure you have a proper installation of KASH 2.2 on your system. The
 package may work with other versions as well. The package can be obtained from
 
 http://www.math.tu-berlin.de/~kant/kash.html

 Remember kash needs the environment variable $KASH to point to the library
 directory of the KASH installation. You don't need the "galois" part of KASH.
 
2. Create a directory you want "ell.g" to reside in and copy ell.shar to that
 directory. Make it your current directory and make sure that the environment
 variable $ELLDIR points to the directory.

3. Type "sh ell.shar" to unpack the archive. You don't need ell.shar after this
 anymore (but you might want to keep it for backup)
 
4. Type "make". This compiles the C-program "filter", makes the documentation
and makes the script "mwkash" executable. This step may cause some trouble on
some systems. This need not be a real problem. The following should help to
figure out problems.

* the makefile assumes gcc is present. filter.c is plain ANSI-C, so any decent
C-compiler should be succesfull in creating filter, which should reside in the
same directory as the rest of the ell.g package. This routine is only used by
HypEllFindX.

* the documentation preparation routines are written in Perl. The documentation
is contained in the *.g files on the lines starting with #. The documentation is
readable without preparation as well.

* ell.g is normally automatically generated by a Perl script. A plain ell.g is
packaged, however, so this step is not really necessary. 

5. Each time you want to use the package, make sure that the current directory
is the directory of installation of ell.g or set the environment variable
ELLDIR. Start KASH and type

Read("ell.g");

If necessary, supply a path for ell. Now you are ready to use the package.

If you install this package on a system other than a UNIX system then you
probably cannot extract shell archives. You'll have to do that manually then.
The format of ell.shar is self-explanatory. Additionally, you probably won't
have "make" either, so you'll have to compile filter.c yourself (or refrain from
using HypEllFindX). You'd probably better forget EllMWRank as well, since this
depends on a Perl-script and the external program mwrank by Cremona.

DESIGN PHILOSOPHY

The three design criteria have been

1) obvious correctness of the algorithms
2) ease of implementation
3) ease of use
4) efficiency

in that order of importance, most of the time. Routines should return correct
output for correct input. Some routines try to check the validity of their
arguments to protect the user from easy to make mistakes, but others don't. See 
examples.g forsome examples for how to use the package.