===============
NZMATH Tutorial
===============

--------------
1. What is it?
--------------

The purpose of the NZMATH system is to provide mathematical,
especially number-theoretic computational power to you.  It is written
in Python scripting language in order to enhance quickly with users'
experiences.


--------
2. Usage
--------

2.1. Before You Start
=====================

2.1.1. Installation of Python
-----------------------------

NZMATH requires Python version 2.5 or 2.6.  If you do not have
Python installed on your computer, please install it.

The Python language is a very high level language.  It is downloadable
from the website_.  There are also some documents there.

.. _website: http://www.python.org/

2.1.1.1. Note about Python 3
----------------------------

NZMATH is not ready for Python 3 now.
It is planned to port NZMATH for Python 3, in a year or so.


2.1.2. Installation of NZMATH
-----------------------------

2.1.2.1. Download
-----------------

First of all, please download the distribution file.  The file you
need differs depending on your operating system.  For unix or
unix-like systems the file is NZMATH-x.y.z.tar.gz, where x, y, z are
non-negative integers.  For Microsoft Windows,
NZMATH-x.y.z.win32Install.exe.

The places to download are:
 * http://sourceforge.net/projects/nzmath/files/
 * http://tnt.math.se.tmu.ac.jp/nzmath/download/


2.1.2.1. On Unix sytems including Linux, Mac OS X, etc.
-------------------------------------------------------

To install NZMATH you should have privilege which lets you install
some files under the standard python script path,
/usr/lib/python2.3/site-packages or
/usr/local/lib/python2.3/site-packages depending on the Python
installation path.

We denote the privileged user's prompt # and ordinary user's %.

Expand the downloaded file.

    % tar zxf NZMATH-x.y.z.tar.gz

Then, you have a child directory named NZMATH-x.y.z.

    % cd NZMATH-x.y.z
    % su
    # python setup.py install

The last command install NZMATH into the python script path described
above.


2.1.2.2. On Windows
-------------------

Click the downloaded file, and follow the instruction.


2.1.3. Installation of IPython
------------------------------

(Optional, but recommended)

IPython is an enhanced interactive Python shell.  If you do not have
it installed on your system, it is recommended to install it now.

To install it, follow the instruction on its own documentation.
http://ipython.scipy.org/moin/


2.1.4. Installation of mpmath
-----------------------------

(Optional, but recommended)

mpmath is a multiple precision floating point arithmetic package for
Python.  Some modules in NZMATH essentially depend on the availability
of mpmath, and some other modules can be more powerful with mpmath.

To install it, follow the instruction on its own documentation.
http://code.google.com/p/mpmath/


2.2. Quick Start
================

2.2.1. User Interfaces
----------------------

NZMATH does not have own interpreter nor graphical interface.  Users
have to use with the raw Python interpreter (or possibly IPython).
Though the interpreters are designed well, of course, they are not
specialized for mathematical computation.  Please be patient about it.


2.2.2. Sample Session
---------------------

Start your Python interpreter

    % python
    Python 2.6.2 (r262:71600, Sep  3 2009, 19:37:04) 
    [GCC 4.2.1 (Apple Inc. build 5574)] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>> 

(we use '%' for a command prompt.  If you are on Windows, it may be
'C:\>' or something.)

Here, '>>>' is a Python prompt.  You are in the Python interpreter
until you will type EOF (Ctrl-D on unices and Ctrl-Z on Windows).
Then, type:

    >>> from nzmath import *
    >>>

The whole NZMATH stuff is imported.

    >>> r = rational.Rational(113, 355)
    >>> print r
    113/355
    >>> 
    ....

The session continues until you will stop.

2.2.3. Readline
---------------

(Optional)
As you see, class names of NZMATH objects may be boringly long to
type.  You can use completion feature; if you are using ipython it is
presented by default, or if you use default Python you might be able
to configure it to use readline.  Unfortunately, sometimes Python is
built WITHOUT readline module for some license issue.  So, the
following is for those who are lucky to have readline enabled Python.

Save the following content in your file, pythonrc.py, for example:

try:
    import readline
except ImportError:
    print "Module readline not available."
else:
    import rlcompleter
    readline.parse_and_bind("tab: complete")

Then, set environment variable PYTHONSTARTUP pointing to the file.

(Please read Python Library Reference of readline and rlcompleter
modules for more detailed explanation.)


-------------------------
3. How to Write a Program
-------------------------

Writing everything at the interpreter prompt is a dull work.  Instead
of it, you can make a program file.

The name of file must end with '.py'; for example, 'sample.py'.

The contents of the file must be a valid Python program.  And, you may
want to import some NZMATH modules at the start of the file.

See the Python documents for detailed Python syntax or built-in data
types and functions.  NZMATH data types are explained below.

To invoke your program (sample.py, say), simply:

    % python sample.py

Or, if you are using unices, make it executable as usual.


-------------
4. Data types
-------------

Python is an object-oriented programming language, and user can create
a new data type as class.  The data types provided by NZMATH are also
classes, which have a lot of methods including overloaded operators.


4.1. Numbers
============

4.1.1. Integer
--------------

There are two integer data types already in Python; int (single
precision) and long (arbitrary precision).  NZMATH has Integer
(nzmath.rational.Integer) to give a rational result for division
instead of a float.

    >>> from __future__ import division # new division semantics
    >>> rational.Integer(3) / 4
    Rational(3, 4)
    >>> 3 / 4
    0.75
    >>> 3L / 4L
    0.75

If you do not import division from __future__, then Python's
int/long behave just like C's int type, i.e. floor division.

    >>> 3 / 4
    0
    >>>

In many cases, Python's integer is chosen for the sake of execution
speed.  Even in such cases, doing "from __future__ import division"
is strongly recommended.  With or without future declaration, floor
division is available as double slash operator.

    >>> 3 // 4
    0
    >>> 8L // 5
    1L

The *L* suffix indicating the number is a long integer does not have
any real meaning, so please ignore it.


4.1.2. Rational
---------------

NZMATH provides Rational (nzmath.rational.Rational) class representing
a rational number, as already appeared in the previous example.


4.1.3. Algebraic number
-----------------------

In NZMATH, algfield provides algebraic numbers.


4.1.4. floating point number
----------------------------

Python has float data type for it.  The mpmath also provides it.


4.2. Algebraic types
====================

4.2.1. Polynomials
------------------

There are several polynomial classes.  New users should use poly
sub-package.

    >>> poly.uniutil.polynomial({0:-1,100:1}, rational.theIntegerRing)  
    IntegerPolynomial([(0, -1L), (100, 1L)], IntegerRing())

poly.uniutil.polynomial is the factory function for univariate
polynomials.


4.2.2. Matrices
---------------

There are several matrix classes.  matrix module provides them.


4.3. Algebraic structures
=========================

4.3.1. Rings
------------

Integers are in the integer ring, A polynomial in a certain polynomial
ring, etc..  They are obtained from elements of them by getRing
method.  For example, rational.Integer(1).getRing() returns a
rational.IntegerRing object.

This is a convention in NZMATH and does not apply to the object
provided by Python itself such as int or long.


4.3.2. Fields
-------------

Fields are a part of rings (see Rings).

There are some fields: the field of rational numbers, real numbers,
and complex numbers are defined.  Finite fields are provided through
finitefield module.


4.3.3. Groups
-------------

There are some groups in NZMATH: for example, class group of
imaginary quadratic fields in quad module, or rational point of
elliptic curves over finite fields in elliptic module.

We are not providing general frameworks for them, though.


----------------
5. Other Modules
----------------

There are other modules, such as bigrandom, factor, prime, etc.
Please read the manual for those modules.


--------------
6. Development
--------------

The project is of open source, and your participation is essential.

6.1. sourceforge.net
====================

We have a project site on the sf.net_.  There are bug tracker, source
repository and so on.

.. _sf.net: http://sourceforge.net/projects/nzmath/

6.2. TMU
========

Almost all the former developers are doctor course / master course
students of Tokyo Metropolitan University (TMU).  There is the server
called tnt, which is primalily run for TNT (Tools on Number Theory)
project, hosting `web pages`_ and the mailing list (see below).

.. _web pages: http://tnt.math.se.tmu.ac.jp/nzmath/


6.2.1. Mailing List
-------------------

A mailing list nzmath-user@tnt.math.se.tmu.ac.jp is for discussing
anything about NZMATH.  You can join the list with writing a mail
containing a line of "subscribe" in the body to
nzmath-user-request@tnt.math.se.tmu.ac.jp.  *Be careful* not to send
it to nzmath-user.


----------
7. License
----------

NZMATH is distributed under the BSD license.  Please read LICENSE.txt_
in the distribution tar ball for detail.

.. _LICENSE.txt: LICENSE.txt


Copyright (c) 2004-2011, NZMATH development group, all right reserved.
