
                              ECPP V3.4.1

                      Copyright (c) 1991, Francois Morain


                            Y) What is ECPP?
                           ------------------

ECPP stands for "Elliptic Curves and Primality Proving". The algorithm
is described in 

    A. O. L. Atkin and F. Morain
    "Elliptic curves and primality proving"
    To appear.

It is a deterministic algorithm that gives a certificate of primality
for numbers that can be as large as 10**1000 (one thousand). For more
informations, read this README and the README.ecpp file.



                              Z) PREAMBLE
                             -------------

The ECPP package contains the BigNum package, and is distributed
according to the following rules:

    This documentation, and the source code of the BigNum package may
    be reproduced and distributed freely to non commercial usage
    provided that the following conditions are respected:

       . Digital PRL or INRIA should be notified of the copy.

       . The original Copyright notice should not be removed from the
         documentation or from the source code under any circumstances.
 
       . Any work using the BigNum package should state explicitly
         the use of such package, and its origin by including the
         following sentence: This work uses the BigNum package developed
         jointly by INRIA and Digital PRL.

       . If any modification is applied to the BigNum package, explicit
         statements should identify the fact that such modifications
         have been made, by whom, and where.  These statements should
         not be removed in any further distribution.
 
       . Any work using extensively the BigNum package should be freely
         distributed under conditions similar to the distribution of
         the BigNum package.

    INRIA and Digital Equipment Corporation make no representations,
    express or implicit, with respect to this documentation or the
    software it describes, including without limitations, any implied
    warranties of merchandability or fitness for a particular purpose,
    all of which are expressly disclaimed.  INRIA and Digital Equipment
    Corporation or subsequent distributors shall in no event be liable
    for any indirect, incidental or consequential damages.

I just add this:

You may copy the ECPP package in whole or in part as long as you don't try to
make money of it, or pretend that you wrote it.

                     
                     A) INSTALLING THE ECPP PROGRAM
                    --------------------------------


In order to install ECPP, you can use either the very short
instructions or the long one. At the end of the process, go to the
Testing section and to the RUNNING section to have some hints on how
to run the program. More informations on the package may be found in
README.ecpp.

                        -----------------------
                        Very short instructions
                        -----------------------

Type 

   % make 

and follow the instructions. At the end of the process, two script
shells: xrunecpp and xcheckcertif are created. They respectively call
runecpp and checkcertif with the load path already initialised.

You can then use

   % make install

to install these two scripts plus the man page. See the Makefile for this.

                           -----------------
                           Long instructions
                           -----------------

0. Packaging: ARCH and TYPE
----------------------------

I have developed my program mainly on a Dec Station 3100, but I
tested it on many other machines with different processors but the
same file system. This explains why I had to use the idea of compiling
things in a separate directory depending on the machine. For this, I
introduced two variables, TYPE and ARCH, the first one used in Bignum,
the second being concerned with different architectures.

The variable TYPE contains the type of processor you have. It is used to tell
the Makefile of Bignum which version of assembler you can use. See the
Makefile of Bignum/distrib for more information on the possible types.

The variable ARCH contains the name of the architecture of your machine. 
Every .o, .a or executable built in any of the directories d = Bignum,
Bigmod and Ecpp/C is put in the directory d/$(ARCH). This enables the
user to differentiate machines with the same type of processor but
with non-compatible machine code. For instance, if your there is no
assembly code for your processor, you have to use the C32 TYPE. If you
have another machine with no assembly, the same TYPE is to be used,
but the code will not be compatible. The variable ARCH is also used in the
form of a -D$(ARCH) directive in all subsequent Makefiles. Among the
-Dxxx defined, the most important is -Dpyramid, because of the
location of the file strings.h.

As an example, on a sun 3 which is a 68000, you can type:

   % make TYPE=68K ARCH=sun3

but if you want to differentiate between systems, you can type:

   % make TYPE=68K ARCH=sun3os3
   % make TYPE=68K ARCH=sun3os4

Note also that the TYPE variable is of use only in the building of the
bignum library.

I. Installing the BigNum package
---------------------------------

Go to the directory Bignum. Type:

   % mkdir YourArchitecture; make TYPE=YourType ARCH=YourArchitecture all

II. Installing the Bigmod library
----------------------------------

Go to the directory Bigmod. Type:

   % mkdir YourArchitecture; make ARCH=YourArchitecture abigmod

In case strchr.c does not exist, add it in Makefile.bm.

III. Installing Ecpp
---------------------

1. Go to Ecpp/C.

2. Type:

   % mkdir YourArchitecture
   % make ARCH=YourArchitecture arunecpp
   % make ARCH=YourArchitecture acheckcertif

This will produce a file $(ARCH)/runecpp that is the main program for
using ecpp. A file $(ARCH)/checkcertif is also produced that aims at checking
certificates produced by $(ARCH)/runecpp.

IV. Hints
----------

pyramid: you ordinarily have to add mystrchr.o in the OBJS of
         Bigmod/Makefile.bm.

V. Advanced installation
-------------------------

When running the program on several platforms at the same time, it is
desirable to have the same xrunecpp script for all machines. In order
to do so, you must have a command that can tell you on which
architecture you are. For example, here at INRIA, every machine has a
/bin/arch command that tells you where you are. Then you can modify
the xrunecpp command as follows

#!/bin/sh -
arch=mips       <- replace mips by `/bin/arch`
path=ECPP/Ecpp
$path/C/$arch/runecpp -l$path/ $*

and everything will work fine.

                            B) Testing
                           ------------

Type

   % xrunecpp -q -f Ecpp/C/Test/test.data

A log file containing a typical execution is in Ecpp/C/Ex/test.log.
Some typical timings are given in the file timings.XVERSION.tex. 

Also, try

   % xrunecpp -Q -f Ecpp/C/Ex/n1-50.input

and compare the resulting string with that of Ecpp/C/Ex/n1-50.res .
This is just running the program on the integers between 1 and 50 and
printing a 1 if the number is prime and 0 otherwise. Alternatively, type:

   % make test

When is done, you can mail back some informations using the 

   % make report

instruction. Do not forget to edit the Makefile to see if the commands
EDITOR and MAILCMD are ok. In case of bug, use

   % make bugreport

to send me a bug report.


                             C) RUNNING ECPP
                             ----------------

In order to use ECPP, you must give an input file to xrunecpp in the form 

   % xrunecpp -f input_file

where input_file is either a plain file containing numbers one at a
time on a single line (no carriage return, ...) or the character "-"
which means that the program takes its input from standard input. In
any case, there is no interpreter that can help you enter such things
as "10^20+39". I have not written one since the program is intended in
part to supplement symbolic manipulation programs such as Maple,
Mathematica, etc. In order to facilitate this I have written a utility
which translates certificates into a format compatible with the above
languages. 

For instance, is the script you obtain when trying to
prove the primality of 1093

% xrunecpp -f - -q
%%%%%%%%%%%%%%%%%%%%%%%%%%
%                        %
%           ECPP         %
%                        %
% by Fran\c{c}ois MORAIN %
%   Version .........    %
%%%%%%%%%%%%%%%%%%%%%%%%%%
Enter number to test:
1093
Working on 1093
% Performing a quick compositeness test
% This number might be prime
This number is prime
% Time for this number is 0.031248s


For more informations, see the files *input* in the directory Ecpp/C/Ex.



                             D) About the versions
                            -----------------------

V3-3beta3:

  The first version to be released outside INRIA. Please be patient with
  it. The documentation is very poor. (The research report is being written
  :-).) There are at least two man files and a directory Ex/ and that should 
  be enough for playing with the program.

V3-3beta4:

V3-3beta5: Lots of bugs have been found and corrected.

V3-3beta6: Modifications and simplifications of the various README files.
The runecpp.c program is now cleaner and nicer.

V3-3beta7: New distribution of BigNum. Also, make bug and make report are
introduced.

V3.4.0beta: - changed "make bug" to "make bugreport"
            - changed data structure for fD
            - changed numbering of versions

V3.4.1beta: - bug corrected in ecpp.c (Pratt executed even when number 
	      composite)
	    - updated Ecpp/C/Test/test.data
	    - added Ecpp/C/Ex/test.log

                             E) Acknowledgments
                            --------------------

Such a package cannot exist without some very kind people who tried
it and made useful comments (i.e., after struggling very hard, they
manage to convince me to modify things). Here is the list, in
alphabetical order: Vale'rie Me'nissier (first alpha tester), Philippe
Robert (for his sharp reports), Ilan Vardi (for his advice and some
part of the documentation), Paul Zimmermann (for the high score in bug
finding).


                              F) Conclusion
                             ---------------

All improvements, remarks, congratulations, etc. are welcome. (Please,
don't forget to give the version number in any mail you should have to
send me.)

Have fun,

Fran\c{c}ois Morain
morain@inria.inria.fr
