Installing, configuring and running SymPy

The easiest way to get SymPy is to type sudo pip install sympy, which will download the latest version of the package from PyPI and install it. If you want to get the source and install it manually, visit this page and download the latest tarball from Featured Downloads section, or use the following direct link:

$ wget http://sympy.googlecode.com/files/sympy-0.7.1.tar.gz
$ tar -xz -C sympy –strip-components 1 -f sympy-0.7.1.tar.gz

You will also find an installer for Windows there. An alternative way is to clone SymPy’s git repository from GitHub:

$ git clone git://github.com/sympy/sympy.git

To use it, issue:

$ cd sympy
$ python
Python 2.7.2+ (default, Oct  4 2011, 20:06:09)
[GCC 4.6.1] on linux2
Type “help”, “copyright”, “credits” or “license” for more information.
>>> from sympy import *
>>> var(‘x’)
x
>>> diff(sin(x), x)
cos(x)

If you want SymPy to be available globally, you can install it using ./setup.py install. SymPy is available in major Linux distributions, so you can install it also using package manager of your distribution (for example in Ubuntu install python-sympy and in Gentoo install dev-python/sympy). Note that distributions often contain very outdated versions of packages, so make sure you don’t install some ancient version of SymPy on your system.

By default, SymPy doesn’t have any dependencies besides Python. The following version of Python are supported: 2.5, 2.6, 2.7. Version 2.4 was originally supported but was dropped in SymPy 0.7.1. Support for Python 3.2+ will be added in version 0.7.2 (use git version for now). Version 0.7.2 will also support PyPy 1.6+. If you use Jython, IronPython or other interpreter, you may find out SymPy not working properly (Jython) or not importing at all (IronPython).

Certain SymPy’s modules may require additional dependencies to provide more features or improve speed of computations. For example, sympy.polys and sympy.mpmath can take advantage of gmpy library to radically improve speed of otherwise pure Python library. If gmpy is not available, those modules fall back automatically to pure Python implementation of arithmetic routines. Other optional dependencies are IPython, Matplotlib, NumPy, SciPy, Cython, Pyglet, LaTeX distribution and more.

Translating SymPy to Python 3

Support for Python 3.2+ was added to master branch of SymPy’s repository and will be a part of 0.7.2 release. If you use SymPy from git, then you can switch to Python 3 now. However, SymPy’s source is not compatible with Python 3 by default and you have to translate it:

$ cd sympy
$ python3.2 bin/use2to3
$ cd py3k-sympy
$ python3.2
Python 3.2.2 (default, Sep  5 2011, 21:17:14)
[GCC 4.6.1] on linux2
Type “help”, “copyright”, “credits” or “license” for more information.
>>> import sympy
>>> sympy.__version__
‘0.7.1-git’
>>>

Make sure you run use2to3 under Python 3.2, because Python 3.0 and 3.1 will fail translating SymPy. Although you can’t translate SymPy using Python 3.1 and this version isn’t officially supported, SymPy works very well in it, just if you run python3.1 bin/test, you will get a few harmless failures

SymPy in Python/IPython

Sessions in standard Python’s interpreter and IPython look very similar, just the banner and prompt look differently, for example:

$ python
Python 2.7.2+ (default, Oct  4 2011, 20:06:09)
[GCC 4.6.1] on linux2
Type “help”, “copyright”, “credits” or “license” for more information.
>>> import sympy
>>> x = sympy.Symbol(‘x’)
>>> sympy.integrate(3*x**2)
x**3
>>> sympy.init_printing()
>>> sympy.integrate(3*x**2)
 3
x

Interactive SymPy (isympy)

For users’ convenience, SymPy’s distribution includes a simple script called isympy (see bin/isympy). isympy uses either IPython (if available) or standard Python’s interpreter with readline support. On startup isympy sets up the environment to make interaction with SymPy more pleasant. It enables new division, imports everything from sympy, injects a few commonly used symbols into the global namespace, and initializes the pretty printer.

Here is an example session with isympy:

$ bin/isympy
IPython console for SymPy 0.7.1 (Python 2.7.1-64-bit) (ground types: gmpy)

These commands were executed:
>>> from __future__ import division
>>> from sympy import *
>>> x, y, z, t = symbols(‘x y z t’)
>>> k, m, n = symbols(‘k m n’, integer=True)
>>> f, g, h = symbols(‘f g h’, cls=Function)

Documentation can be found at http://www.sympy.org

In [1]: integrate(3*x**2, x)
Out[1]:
 3
x

In [2]: %quit
Do you really want to exit ([y]/n)? y
Exiting ...

Command-line arguments

There are a variety of command-line options supported by isympy:

-h, --help

show help

-c CONSOLE, --console=CONSOLE

select type of interactive session: ipython, python. Default is ipython if IPython is installed, otherwise, python.

-p PRETTY, --pretty=PRETTY

setup pretty printing: unicode, ascii or no. Default is unicode if the terminal supports it, otherwise, ascii.

-t TYPES, --types=TYPES

setup ground types: gmpy, python or sympy. Default is gmpy if it’s installed, otherwise python.

-o ORDER, --order=ORDER

setup ordering of terms: [rev-]lex, [rev-]grlex, [rev-]grevlex or old. Default is lex.

-q, --quiet

print only version information at startup

-C, --no-cache

disable caching

Environment variables

SYMPY_USE_CACHE

By default SymPy caches all computations. If this is undesirable, for example due to limited amount of memory, set this variable to no to disable caching. Note that some operations will run much slower with the cache off. Setting this variable to no is equivalent to running isympy with -C option.

SYMPY_GROUND_TYPES

SymPy is a pure Python library, however to improve the speed of computations it can take advantage of gmpy library to speedup coefficient arithmetics (also known as ground domain arithmetics). Ground types are set automatically, so if gmpy is not available, it simply won’t be used. However, if gmpy is available but for some reason it is undesirable to use it, set this variable to python, to disable usage of gmpy. Use -t or --type option to achieve the same in isympy.

Running the test suite

To verify that SymPy works properly on your computer, you can run SymPy’s test suite. This is done either with bin/test command or test() in an interactive session. For example, to test sympy.core issue:

$ bin/test sympy/core
============================= test process starts ==============================
executable:   /usr/bin/python  (2.7.2-final-0)
architecture: 64-bit
ground types: gmpy
random seed:  65858271

sympy/core/tests/test_arit.py[48] ...f..........................................
..                                                                          [OK]
sympy/core/tests/test_assumptions.py[28] ............................       [OK]
sympy/core/tests/test_basic.py[10] ..........                               [OK]
sympy/core/tests/test_cache.py[1] .                                         [OK]
sympy/core/tests/test_complex.py[13] .............                          [OK]
sympy/core/tests/test_containers.py[5] .....                                [OK]
sympy/core/tests/test_count_ops.py[2] ..                                    [OK]
sympy/core/tests/test_diff.py[6] ......                                     [OK]
sympy/core/tests/test_equal.py[6] ......                                    [OK]
sympy/core/tests/test_eval.py[8] .....f..                                   [OK]
sympy/core/tests/test_eval_power.py[13] .............                       [OK]
sympy/core/tests/test_evalf.py[24] ........................                 [OK]
sympy/core/tests/test_expand.py[6] ......                                   [OK]
sympy/core/tests/test_expr.py[59] ..............................................
.............                                                               [OK]
sympy/core/tests/test_exprtools.py[4] ....                                  [OK]
sympy/core/tests/test_facts.py[11] ...........                              [OK]
sympy/core/tests/test_functions.py[27] .....fff...................          [OK]
sympy/core/tests/test_logic.py[11] ...........                              [OK]
sympy/core/tests/test_match.py[26] ...f......................               [OK]
sympy/core/tests/test_numbers.py[46] ...........................................
...                                                                         [OK]
sympy/core/tests/test_operations.py[4] ....                                 [OK]
sympy/core/tests/test_priority.py[5] .....                                  [OK]
sympy/core/tests/test_relational.py[7] .......                              [OK]
sympy/core/tests/test_sets.py[18] ..................                        [OK]
sympy/core/tests/test_subs.py[30] ..............................            [OK]
sympy/core/tests/test_symbol.py[9] ....X....                                [OK]
sympy/core/tests/test_sympify.py[26] ...f......................             [OK]
sympy/core/tests/test_truediv.py[3] ...                                     [OK]
sympy/core/tests/test_var.py[5] .....                                       [OK]

________________________________ xpassed tests _________________________________
sympy/core/tests/test_symbol.py:

tests finished: 453 passed, 7 expected to fail, 1 expected to fail but passed,
in 6.30 seconds

This tells us that all standard tests in sympy.core‘s pass (dots). In case of failure, . would change to F and OK to FAIL (additionally all failures would be colored in red and listed at the end of output from SymPy’s test utility). Non-standard tests are those marked with f and X characters. The former means that the test was supposed to fail and failed (XFAIL), whereas the later means that the test was supposed to fail but passed (XPASS).

To run the whole test suite issue bin/test or test() without any arguments. Running the whole test suite takes more than ten minutes on Pentium-M 1.6 GHz and less than 5 minutes on Xeon 3.0 GHz (one core).

There is another test utility in SymPy, bin/doctest, which verifies examples in docstrings and documentation. If you are going to contribute to SymPy, make sure you run both bin/test and bin/doctest before submitting a pull request.

SymPy in web browsers

SymPy is available in the following web applications:

• SymPy Live (http://live.sympy.org)
• Sage Notebook (http://www.sagenb.org)

SymPy Live was developed specifically for SymPy. It is a simple web shell that looks similar to isympy under standard Python’s interpreter. SymPy Live uses Google App Engine as computational backend.

Upcoming IPython Notebook (IPython 0.12+) will have native support for SymPy. If you use IPython from git, you can test this feature now by starting IPython with ipython notebook and run %load_ext sympy in an input cell. This will setup pretty printing among other things.