.. _`installing`:

==========
Installing
==========

An installation of `Python <http://python.org>`_ >= 2.6, < 3, is assumed on your system (you can test this by typing ``python --version`` at the command prompt).
If you don't have this, you're probably on Windows: see `these instructions <http://docs.python.org/2/using/windows.html#installing-python>`_.

Short instructions for those a recent Ubuntu/Debian-like system, and not afraid of `pip <http://www.pip-installer.org/>`_::

    $ sudo apt-get python-pip python-numpy
    $ pip install --user -f http://mbsd.cs.ru.nl/symfer/installing.html symfer

Alternatively, download the source distribution (see below). In the unpacked directory, do::

    $ sudo apt-get python-numpy python-yaml python-pyparsing
    $ ./setup.py install --user

If this does not work for you, read on.

----------------
Installing NumPy
----------------

|symfer| depends on `NumPy <http://www.numpy.org/>`_ for its built-in factor algebra expression evaluator. It is easiest first to install NumPy yourself (at least if you're on a Linux distribution). For Ubuntu, the package you need is ``python-numpy``, for MacPorts: ``py27-numpy``.

Alternative 1: doing without a NumPy package/installer
------------------------------------------------------
An alternative is to build NumPy yourself, i.e. download its source distribution and do ``./setup.py install`` (``--user``).
This is also what happens when ``pip`` or ``easy_install`` automatically installs NumPy as a |symfer| dependency.
In these cases, you first need to have the ``python-dev`` package installed,
otherwise you will get error messages about a missing ``Python.h``.
    
Alternative 2: doing without NumPy altogether
---------------------------------------------
If you don't need the built-in evaluator:

- download the |symfer| source distribution (see below)
- edit ``setup.py`` and comment out the ``numpy`` dependency like so::

    install_requires = [
        'PyYAML',
        #'numpy',

- edit ``symfer/__init__.py`` and comment out the ``.evaluator`` import like so::

    # from .evaluator import *  # numpy

- now install |symfer| by running either ``./setup.py install --user`` or ``pip install --user .`` from the root dir. (The first option
  requires you to install the dependencies first.)

--------------------------
Installing |symfer| itself
--------------------------  

For the lazy:

- get the Python installer `pip <http://www.pip-installer.org/>`_, for example from your OS distribution (Ubuntu package ``python-pip``)
- ``pip install --user -f http://mbsd.cs.ru.nl/symfer/installing.html symfer``

However, this entails somewhat of a security risk: ``pip`` will download packages over the Internet (using non-secure connections for all I know). It will usually grab them from the `central Python package repository <http://pypi.python.org>`_, but will also check a distribution's own web site (which is more likely to be compromised) for newer versions. There is no sort of quality assurance whatsoever. (The risk is mitigated here by installing into your home directory (by ``--user``) instead of system-wide.)

Thus, the paranoid and/or picky are better off following these instructions:

- download dependencies yourself:
    - numpy (see `Installing NumPy`_)
    - PyYAML (from http://pyyaml.org, Ubuntu package ``python-yaml``, MacPorts ``py27-yaml``)
    - pyparsing >= 1.5.2, <2 (from http://sourceforge.net/projects/pyparsing/, or
      Ubuntu package ``python-pyparsing``, but the version in 10.04 has a bug that
      produces annoying debug messages "found ignoreExpr,...")
- download the source distribution yourself, choose between:
    - |sdist-tar-file|
    - |sdist-zip-file|
- in the source distribution root dir, execute ``./setup.py install --user`` to install into your home directory
  (or ``sudo ./setup.py install`` to install system-wide)

-------------------------
C evaluator on Windows
-------------------------

Windows does not have a C compiler installed by default.
To use |symfer|'s C evaluator, you can install `MinGW <http://sourceforge.net/projects/mingw/>`_
and add its ``bin`` directory to your ``PATH`` environment variable.

---------------------
Advanced
---------------------

If you don't need all functionality and want |symfer| to work without certain dependencies,
download a source distribution and edit ``symfer/__init__.py`` before installing with ``./setup.py``.
This is also the way to go if you want basic support for *drawing* factor algebra expressions.
For this, |symfer| uses `yapgvb <http://code.google.com/p/yapgvb/>`_, a Python binding to GraphViz.
In Ubuntu, it's in package ``python-yapgvb``. However,
the default ``yapgvb`` installation requires you to install Boost as well, which is why it is currently
disabled in |symfer|.

If you want the latest development (=unstable) version of |symfer|, it can be found at
https://svn.cs.ru.nl/wsvn/symfer/. Check it out with::

    $ svn checkout https://svn.cs.ru.nl/repos/symfer/trunk/

For development, you can install it in *editable mode* (the development directory will be on the Python path)::

    $ pip install --user --no-deps -e .

However, to remove such an editable installation it seems one has to jump through hoops, i.e. remove the ``symfer`` line from
``/usr/local/lib/python2.7/site-packages/easy-install.pth`` and the file ``/usr/local/lib/python2.7/site-packages/symfer.egg-link``
altogether (possibly replacing the path with wherever python locates your user-scheme installations).