mpmath
======

A Python library for arbitrary-precision floating-point arithmetic.

Website: http://code.google.com/p/mpmath
Author: Fredrik Johansson <fredrik.johansson@gmail.com>

mpmath is free software released under the New BSD License (see the
LICENSE file for details)

0. History
----------

* Version 0.6 released on January 13, 2008
* Version 0.5 released on November 24, 2007
* Version 0.4 released on November 3, 2007
* Version 0.3 released on October 5, 2007
* Version 0.2 released on October 2, 2007
* Version 0.1 released on September 27, 2007

For a detailed changelog, see the CHANGES file.


1. Download & installation
--------------------------

mpmath requires a recent version of Python. It has been tested with
Python 2.5 and should work with Python 2.4.

The latest release of mpmath can be downloaded from the mpmath
website. It should also be available in the Python Package Index at
http://pypi.python.org/pypi

To install, unpack the mpmath archive and run

  python setup.py install

The latest development code is available at
http://mpmath.googlecode.com/svn/trunk/


2. Basic usage
--------------

Note: additional documentation is available on the mpmath website.
The main documentation page is:
-- http://code.google.com/p/mpmath/wiki/Documentation

(The unit tests and internal docstrings may also be helpful.)

Import mpmath with

    from mpmath import *

This provides the classes mpf and mpc which work analogously to
Python's float and complex types:

    >>> mpf(2) / mpf(3)
    mpf('0.66666666666666663')

    >>> mpc(0, -1)
    mpc(real='0.0', imag='-1.0')

    >>> mpf(-0.6) ** mpf(-0.2)
    mpc(real='0.89603999408558288', imag='-0.65101116249684809')

For prettier output (that also hides small rounding errors), use
print or str():

    >>> print mpf(2) / mpf(3)
    0.666666666666667

    >>> print mpc(1+2j)**0.5
    (1.27201964951407 + 0.786151377757423j)

The precision is controlled by the properties mpf.prec (number of bits)
and mpf.dps (number of decimals). These properties are linked, so
changing one automatically updates the other to match. Setting prec or
dps changes the precision at which all operations are carried out and
the number of digits to display when printing numbers. The default is
prec=53 and dps=15, the same as Python floats.

    >>> mpf.dps = 30
    >>> mpf(2) / mpf(3)
    mpf('0.66666666666666666666666666666663')
    >>> print _
    0.666666666666666666666666666667
    >>> mpf.dps = 15     # restore to default

You can create mpfs and mpcs from Python numbers, or combine mpfs
and mpcs with Python numbers in arithmetic operations, but be
aware that regular Python floats only have finite precision. To
initialize an mpf with a full-precision value, use a string:

    >>> mpf(0.1)
    mpf('0.10000000000000001')      # same accuracy as float
    >>> mpf.dps = 50
    >>> mpf(0.1)
    mpf('0.1000000000000000055511151231257827021181583404541016')   # junk

    >>> mpf('0.1')
    mpf('0.1000000000000000000000000000000000000000000000000001')   # ok

The following standard functions are available and support both real and
complex arguments:

  sqrt, exp, log, power, cos, sin, tan, cosh, sinh, tanh,
  acos, asin, atan, acosh, asinh, atanh

Example:

    >>> mpf.dps = 15
    >>> print cos(1)
    0.540302305868140
    >>> mpf.dps = 50
    >>> print cos(1)
    0.54030230586813971740093660744297660373231042061792

Some less-common functions are also available: gamma (gamma function),
factorial, erf (error function), lower_gamma/upper_gamma (incomplete
gamma function) and zeta (Riemann zeta function).

Finally, the convenience functions hypot and atan2 are available
(defined for real numbers only).

The constants pi, e, and euler (Euler's constant) are available as
special objects that behave like mpfs but whose values automatically
adjust to the precision.

    >>> mpf.dps = 15
    >>> print pi
    3.14159265358979
    >>> mpf.dps = 50
    >>> print pi
    3.1415926535897932384626433832795028841971693993751

    >>> mpf.dps = 15
    >>> e**(-pi*1j)
    mpc(real='-1', imag='-1.2289836075083701E-16')
    >>> mpf.dps = 50
    >>> e**(-pi*1j)
    mpc(real='-1', imag='1.0106 [...] E-51')

There is partial support for directed rounding. Rounding is controlled by
a global mode that affects all arithmetic operations. This mode is set
through methods on the mpf class. For example, this computes
and verifies a 15-digit approximation interval for pi:

    >>> mpf.dps = 15
    >>> mpf.round_down(); pi1 = +pi
    >>> mpf.round_up(); pi2 = +pi
    >>> pi1
    mpf('3.1415926535897931')
    >>> pi2
    mpf('3.1415926535897936')
    >>> mpf.dps = 30
    >>> pi1 < pi < pi2
    True

3. Application code and demos
-----------------------------

In addition to the base arithmetic, mpmath provides various more or less
useful functions and demo scripts. These features are described in more
detail on the mpmath wiki.

* Numerical integration: the quadts() function
  Permits computing integrals with hundreds of digits of precision.

  -- see http://code.google.com/p/mpmath/wiki/NumericalIntegration

* Interval arithmetic: the mpi class
  -- see http://code.google.com/p/mpmath/wiki/IntervalArithmetic

* Educational interval arithmetic demo: mpmath/apps/taylordemo.py

* Pi digits demo: mpmath/apps/pidigits.py
  This script can be run interactively. It can compute 100,000's of digits
  of pi fairly quickly, and prints them in nicely formatted columns.


4. Known problems
-----------------

mpmath is a work in progress. Major issues include:

* mpmath temporarily increases the working precision during function
  evaluations to suppress the effects of intermediate rounding errors.
  In most functions, the precision is currently increased by a fixed amount
  that gives accurate results for "normal" input. Close to zeros and
  singularities, and/or with the precision set to (say) several hundred
  digits, the last few digits in a result may be wrong.

* Directed rounding works for arithmetic operations. It is implemented
  heuristically for other operations, and their results may be off by one
  or two units in the last place (even if otherwise accurate).

* Some IEEE 754 features are not available. Inifinities and NaN are
  partially supported; denormal rounding is currently not available
  at all.

* The interface for switching precision and rounding is not finalized.
  The current method is not threadsafe.


4. Help and bug reports
-----------------------

You can report bugs at the mpmath issue tracker,
http://code.google.com/p/mpmath/issues/list

Please send any comments or questions to Fredrik
<fredrik.johansson@gmail.com>
