Package: pyschoof
Python3 Implementation of Schoof's Algorithm============================================This is an implementation of Schoof's algorithm for counting thepoints on elliptic curves over finite fields (Schoof, René. Ellipticcurves over finite fields and the computation of square roots modp. *Mathematics of Computation*, 44(170):483–494, 1985).Elliptic curve cryptographic algorithms base their security guaranteeson the number of points on the used elliptic curve.  Because naivepoint counting is infeasible, having a fast counting algorithm isimportant to swiftly decide whether a curve is safe to use incryptography or not.  René Schoof's algorithm for counting the pointson an elliptic curve over a finite field is the foundation for the(asymptotically) fastest [Schoof–Elkies–Atkin][sea-algorithm] countingalgorithm.**Implementation.**The implementation is written in [Python 3][python] and is kept assimple as possible.  Its goal is to give insight into the mathematicsof the algorithm without the use of (too) high-level concepts.  For a(pretty) gentle introduction into why and how Schoof's algorithmworks, please read my diploma thesis titled[*An Elementary Derivation and Implementation of Schoof's Algorithm for Counting Points on Elliptic Curves*][thesis].In the thesis, I try to explain *how one might get the idea for thealgorithm*.  This understanding of *why* things look the way they dois often neglected in mathematics.Schoof's algorithm uses arithmetic on elliptic curves, finite fields,rings of polynomials, and quotient rings.  This repository thereforecontains Python modules for all these concepts that can be used ontheir own.System Requirements-------------------The algorithm is implemented in version 3.1 of [Python][python], anopen licensed dynamic programming language available on all commonplatforms.  To find out whether a compatible version of Python isalready installed on your system, execute `python --version` in aterminal.  The command will return the version number if Python isavailable.  Note that the version 3 interpreter could also be named`python3`.  Please see the *Using Python* part of Python's[documentation][python-using] for system installation instructions;follow the steps below to set up Python locally in your account.### Local Installation from Source CodeInstalling Python from source code requires a C compiler; on Linux andUnix systems, one is almost always available.  The following stepsinstall Python on a Linux system:* **Download.** Download the source tar ball of version 3.1 or laterfrom the Python website at<http://www.python.org/download/releases/>.* **Compile.** Open a terminal and create a temporary directory, say`${HOME}/tmp/`, by executing `mkdir ${HOME}/tmp/`.  Change into thetemporary directory and extract the source tar ball: `cd${HOME}/tmp/` and then `tar xzvf Python-3.1.2.tgz`; adjust the pathand file name accordingly.  If you downloaded the bzipped source tarball, use `tar xjvf Python-3.1.2.tar.bz2` instead.Next, change into the directory that contains the extracted sourcecode, for instance `${HOME}/tmp/Python-3.1.2/`.  Configure the buildsystem by executing `./configure --prefix=${HOME}/python3`.  Theprefix is the path that will be the root of the Python installation,so adjust it to taste.  In case required components are missing, thecommand will exit with an error message.  In this case, pleaseinstall the components and re-execute `configure`.If everything worked, then the last line of output by `configure`will be `creating Makefile`.  To start the compilation, execute`make`.* **Install.** Use `make install` to install Python after thecompilation finished.* **Set Up Environment.** To enable the local Python installation, addits interpreter and modules to the respective search paths: execute`export PATH=${HOME}/python3/bin:${PATH}` to tell the shell where tofind the `python3` interpreter; adjust the path to your prefix for`configure`.  Likewise, execute `exportPYTHONPATH=${HOME}/python3/lib/python3.1` to tell Python where tofind its modules.Note that the scope of `export` is the current shell.  Thus you haveto issue both commands in every freshly opened terminal you wish touse for Python 3.1 programs.Program Execution-----------------The implementations work without any installation; they may beexecuted directly from the checked out repository.  However, theyexpect a set up Python 3.1 run-time environment as explained above.The root directory contains the point counting programs: the file`naive_schoof.py` is the implementation discussed in\autoref{sec:implementation}; the file `reduced_computation_schoof.py`is the version with better constants using a smarter computation orderand Hasse's theorem.  Curves for counting are specified asspace-separated triples *p*, *A*, and *B*: *p* is the prime size ofthe galois field *GF[p]*, and *A* and *B* are the curve parameters.### ExampleSuppose you want to count the number of points on the elliptic curveover *GF[23]* with parameters *A=4* and *B=2*.  If the currentdirectory in the terminal is the repository root, thenexecuting `python3 naive_schoof.py 23 4 2` yields the output~~~~~Counting points on y^2 = x^3 + 4x + 2 over GF<23>: 21~~~~~### Command Line ParametersThe program supports the command line options described below, whichfor instance allow to read the curves from a file, or to createexecution profiles for performance analysis.* `--version`: Show program's version number and exit.* `-h`, `--help`: Show a help message and exit.* `-i` *f*, `--input-file=`*f*: Read the curve parameters from file*f*.  Lines in *f* must contain either a comment, or aspace-separated triple of curve parameters *p*, *A*, and *B*.Comment lines start with a hash (`#`); these and empty lines areskipped.* `-o` *f*, `--output-file=`*f*: Write the results to file *f* insteadof showing them on the terminal.  Each line of input generates onecorresponding line of output.* `-t` *s*, `--timelimit=`*s*: Terminate the program if processing aninput triple takes longer than *s* seconds.  The program ends if thetime limit expires; no subsequent lines will be read from an inputfile.  Thus, sort the parameters in input files ascending in lengthof the prime *p* to avoid triggering the time limit too early.* `-p`, `--create-profile`: Create an execution profile for eachprocessed input triple.  The profile consists of a call profilegenerated with the `cProfile` Python module, and a file with dataabout elapsed time and used memory.* `-d` *d*, `--profile-directory=`*d*: If profiling is enabled withthe `-p` flag, then the collected data is written to the directory*d*.  The default value is the current directory.Profiling Tools---------------The `tools/` directory contains several programs to post-processprofiles resulting from a set `-p` flag.  For example, it includes acall profile converter that outputs [Callgrind][callgrind] files.  Use[KCacheGrind][kcachegrind] to interactively inspect Callgrind files.Further Documentation---------------------The implementation comes with extensive [API documentation][api] thatexplains the purpose and usage of all classes.Furthermore, the directory `_test` contains unit tests to verifycorrect arithmetic.  The unit tests are designed to be easily extendedto further implementations of the same objects.  Thus, mistakes in newdesigns should be simpler to locate.  To run the unit tests, execute`python3 -m _test` in the repository root directory.License-------Copyright (c) 2010--2012 Peter Dinges <pdinges@acm.org>.The software in this repository is free software: you can redistributeit and/or modify it under the terms of the GNU General Public Licenseas published by the Free Software Foundation, either version 3 of theLicense, or (at your option) any later version.The software is distributed in the hope that it will be useful, butWITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNUGeneral Public License for more details.You should have received a copy of the [GNU General Public License][gpl3]along with this program.  If not, see <http://www.gnu.org/licenses/>.[api]: http://pdinges.github.com/python-schoof[callgrind]: http://valgrind.org/info/tools.html "Callgrind is part of the Valgrind tool suite"[gpl3]: http://opensource.org/licenses/GPL-3.0 "GNU General Public License, version 3"[kcachegrind]: http://kcachegrind.sourceforge.net/html/Home.html "Interactive viewer for Callgrind files."[python]: http://python.org "Python Programming Language"[python-using]: http://docs.python.org/py3k/using/index.html "Python Setup and Usage"[sea-algorithm]: http://en.wikipedia.org/wiki/Schoof%E2%80%93Elkies%E2%80%93Atkin_algorithm "Schoof-Elkies-Atkin algorithm for counting points on elliptic curves over finite fields."[thesis]: http://www.elwedgo.de/fileadmin/elwedgo.de/portfolio/diploma_thesis_math/dinges-elementary_schoof_derivation-thesis.pdf