.. include:: links.inc

.. _introduction_installation:

Installation
============

.. contents:: Table of Contents
   :local:
   :backlinks: top

Platforms
---------

*SfePy* is known to work on various flavors of Linux, on Intel Macs and
Windows.

Requirements
------------

Installation prerequisites, required to build *SfePy*:

- a C compiler suite (for example gcc)
- `Python`_ 2.6 or 2.7
- `NumPy`_
- `Cython`_

Python packages required for using *SfePy*:

- `Pyparsing`_
- `SciPy`_
- `scikit-umfpack`_, for enabling UMFPACK solver for SciPy >= 0.14.0
- `Matplotlib`_, for various plots; GTKAgg for live plotting via log.py
- `PyTables`_, for storing results in HDF5 files
- `SymPy`_, for some tests and functions
- `Mayavi`_, for postproc.py
- `Pysparse`_, for schroedinger.py
- `igakit`_, for script/gen_iga_patch.py - simple IGA domain generator
- `petsc4py`_ and `mpi4py`_, for running parallel examples and using parallel
  solvers from PETSc
- `pymetis`_, for mesh partitioning using Metis

Make sure the dependencies of those packages are also installed -
`scikit-umfpack`_ does not work without UMFPACK, `petsc4py`_ without PETSc,
etc.

Other dependencies:

- To be able to (re)generate the documentation: `Sphinx`_, `numpydoc`_, LaTeX,
  see :ref:`how_to_regenerate_documentation`.
- If `doxygen` is installed, the documentation of data structures and functions
  can be automatically generated by running "``python setup.py
  doxygendocs``". Then see "``doc/html/index.html``".
- Mesh generation tools use `pexpect` and `gmsh` or `tetgen`.
- `IPython`_ is preferred over the regular Python shell for following some
  parts of primer/tutorial.

On Linux, consult the package manager of your favorite distribution,
see `Platform-specific Notes`_.

On Windows a completely free scientific-oriented distributions
`Python(x,y)`_ and `WinPython`_ can be used, but some missing packages
may need to be installed manually. Instructions for installing
Python(x,y) can be found in `Windows Using Python(x,y)`_.

Furthermore, free versions of commercial multi-platform scientific
Python distributions `Enthought Canopy`_ (formerly Enthought
PythonDistribution) and `Anaconda`_ (`Continuum Analytics`_) can be
used (and recomended), see `Multi-platform Distributions Notes`_.

*SfePy* can be used without any installation by running the scripts from the
top-level directory of the distribution, or can be installed locally or
system-wide.

*SfePy* should work both with bleeding edge (Git) and last released versions of
`NumPy` and `SciPy`. Submit an issue at `Issues`_ page in case this does not hold.

Generic Installation Instructions
---------------------------------

Download the latest development version of the code from
`SfePy git repository`_::

    git clone git://github.com/sfepy/sfepy.git

In case you wish to use a specific release instead of the latest master
version, use::

    git tag -l

to see the available releases - the release tags have form
``release_<year>.<int>``.

See the `download`_ page for additional download options.

.. _compilation:

Compilation of C Extension Modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the *SfePy* top-level directory:

1. Look at ``site_cfg_template.py`` and follow the instructions
   therein. Usually no changes are necessary.

2. Compile the extension modules

   a) for in-place use::

        python setup.py build_ext --inplace

   b) for installation::

        python setup.py build

We recommend starting with the in-place build.

Installation
^^^^^^^^^^^^

(As mentioned above, this step is not required to use *SfePy*.)

- System-wide (may require root privileges)::

    python setup.py install

- Local (requires write access to ``<installation prefix>``)::

    python setup.py install --root=<installation prefix>

If all went well, proceed with `Testing`_.

.. _testing:

Testing
-------

After building in-place or installing *SfePy* you can check if all the
functions are working by running the automated tests.

In-place Build
^^^^^^^^^^^^^^

In the source directory type::

    python run_tests.py

If a particular test fails, please run it in debug mode::

    python run_tests.py --debug tests/failing_test_name.py

and report the output to the `SfePy mailing list`_.

On a Linux-based system, the script can be executed directly by::

    ./run_tests.py

Installed Build
^^^^^^^^^^^^^^^

In a directory different from the source directory, run::

    python run_tests.py

or (on Linux)::

    run_tests.py

Note that this command creates a directory called ``'output'`` in the current
directory as well as some other auxiliary files. Use the in-place build testing
if you do not want to care about this.

Debugging
---------

If something goes wrong, set ``debug_flags = '-DDEBUG_FMF'`` in ``site_cfg.py``
to turn on bound checks in the low level C functions, and recompile the code::

    python setup.py clean
    python setup.py build_ext --inplace

Then re-run your code and report the output.

.. _using-ipython:

Using IPython
-------------

It is preferable to use (a customized) `IPython`_ over the regular Python shell
when following :doc:`tutorial` or :doc:`primer`. Install `IPython`_ and then
customize it as follows:

1. Create a new profile::

     ipython profile create sfepy

2. Open the ``~/.ipython/profile_sfepy/ipython_config.py`` file in a text
   editor and add/edit after the ``c = get_config()`` line the following:

   .. sourcecode:: python

      exec_lines = [
          'from sfepy.base.base import *',
          'from sfepy.discrete import *',
          'from sfepy.discrete.fem import *',
          'from sfepy.applications import solve_pde',
          'import matplotlib as mpl',
          'mpl.use("WXAgg")',
          'from matplotlib.pyplot import *',
          'from sfepy.postprocess.viewer import Viewer',
      ]

      c.InteractiveShellApp.exec_lines = exec_lines

      c.TerminalIPythonApp.gui = 'wx'

      c.TerminalInteractiveShell.colors = 'Linux' # NoColor, Linux, or LightBG

3. Run the customized IPython shell::

     ipython --profile=sfepy

Multi-platform Distributions Notes
----------------------------------

Anaconda
^^^^^^^^

(tested Python 2.7 64-Bit on Ubuntu 14.04 LTS, Windows 8.1 and Mac OS X 10.10)

Download appropriate `Anaconda`_ Python 2.7 installer package (valid
e-mail address is required, but no further Ads) and follow install
instructions. We recommend to choose *user-level* install option (no
admin privileges required).

Install missing/required packages using built-in `conda` package
manager::
  
   conda install mayavi wxpython

Occasionally, you should check for distribution and/or installed packages
updates (there is no built-in automatic update mechanism available)::
  
  conda update conda
  conda update anaconda
  conda update <package>

See `conda help` for further information.  

Platform-specific Notes
-----------------------

The following information has been provided by users of the listed platforms
and may become obsolete over time. The generic installation instructions above
should work in any case, provided the required dependencies are installed.

Gentoo
^^^^^^

::

    emerge -va pytables pyparsing numpy scipy matplotlib ipython mayavi

Archlinux
^^^^^^^^^

::

    pacman -S python2-numpy python2-scipy python2-matplotlib ipython2 python2-sympy
    yaourt -S python-pytables python2-mayavi

Instructions
""""""""""""

Edit Makefile and change all references from python to python2.
Edit scripts and change shebangs to point to python2.

Debian
^^^^^^

   (old instructions, check also Ubuntu below)

::

    apt-get install python-tables python-pyparsing python-matplotlib python-scipy

Ubuntu
^^^^^^

(tested on Ubuntu 14.04 LTS and 14.10)

Prerequisites
"""""""""""""

First, you have to install the dependencies packages::

    sudo aptitude install python-scipy python-matplotlib python-tables python-pyparsing libsuitesparse-dev python-setuptools mayavi2 python-dev ipython python-sympy cython python-sparse

The same packages work also in Kubuntu 14.10. If `aptitude` is not
installed, install it, or try `apt-get install` instead.

Older Versions of Ubuntu
''''''''''''''''''''''''

(tested on Jaunty Jackalope 9.04 and Lucid Lynx 10.04)

The following is required to get working `umfpack`.  Download and install
the umfpack scikits in some local dir. In the following example it will
be installed in $HOME/local::

    svn checkout http://svn.scipy.org/svn/scikits/trunk/umfpack
    cd umfpack
    mkdir -p ${HOME}/local/lib/python2.6/site-packages
    python setup.py install --prefix=${HOME}/local

Add to your .bashrc the line::

    export PYTHONPATH="${HOME}/local"

then re-open a terminal and if the scikits was installed correctly importing
scikits.umfpack in python should give no error::

    python
    >>> import scikits.umfpack
    >>>

Next Download sympy 6.7 or later. Extract the contents.

cd sympy-0.6.7

python setup.py install --prefix=${HOME}/local

Installing *SfePy*
""""""""""""""""""

Now download the latest *SfePy* tarball release (or the latest development
version).

Uncompress the archive and enter the *SfePy* dir, then type::

    python setup.py build_ext --inplace

after a few minutes the compilation finishes.

Finally you can test *SfePy* with::

    ./run_tests.py

If some test fails see `Testing`_ section for further
details.

Fedora 8
^^^^^^^^
Notes on using umfpack (contributed by David Huard).

entry in numpy site.cfg::

    [umfpack]
    library_dirs=/usr/lib64
    include_dirs = /usr/include/suitesparse

Comment by david.huard, Mar 26, 2008::

  Of course, suitesparse and suitesparse-devel must be installed.

Windows Using Python(x,y)
^^^^^^^^^^^^^^^^^^^^^^^^^

(tested on Windows 7/8.1)

Here we provide instructions for using *SfePy* on Windows through
`Python(x,y)`_. We will also use `msysgit`_ to install the umfpack scikit to
speed up performance.

This procedure should work in theory for any recent Windows version
supported by Python(x,y) and msysgit, but your milage may vary.

There several steps, but hopefully it is straightforward to follow this
procedure. If you have any questions or difficulties please feel free to ask on
the `SfePy mailing list`_ (see `SfePy web site`_). Also, if you have any
suggestions for improving or streamlining this process, it would be very
beneficial as well!

We assume the installation to be done in C:\\ - substitute your path
where appropriate.

Steps to Get a Working *SfePy* on Windows Using Python(x,y)
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

#. Minimum 4 GB of free disk space is required due to the
   installed size of `python(x,y)` and `msysgit`.

#. Download the latest `Python(x,y)`_ windows installer (version 2.7.X.X) and
   make a *Full installation* in the default installation directory.

#. Download the latest `pyparsing`_ windows installer (Python version 2.7) and
   install it in the default installation directory.

#. Download the latest `msysgit`_ windows installer and install it in the
   default installation directory:

   -  either get the file that begins with "Git-", which gives you
      `gitbash` - a bash shell in Windows,

   - or get the file that begins with "msysGit-fullinstall".

   Below we refer to either `gitbash` or `msys` as "shell".

#. Download the latest `umfpackpy`_ zip archive and follow the instructions
   below:

   a) Extract the *umfpackpy_<version>.zip* to your convenient location in
      Hard disk, Lets assume it's extracted in C:\\. Now there will be
      two files on the extracted folder, *ez_setup.py* and
      *scikits.umfpack-5.1.0-py2.7-win32.egg*.

   b) Start a shell and write the following to go to the extracted folder::

          cd /c/umfpackpy_<version>/

   c) Install the UMFPACK library for Python::

          ez_setup.py scikits.umfpack-5.1.0-py2.7-win32.egg

#. Either `download`_ the latest *SfePy* tarball and extract it to your
   convenient location in hard disk, lets assume it's extracted in C:\\.

   Or, if you want to use the latest features and contribute to the
   development of *SfePy*, clone the git development repository

      * In shell, type::

          cd /c/
          git clone git://github.com/sfepy/sfepy.git

   Then follow the instructions below:

   a) In shell, go to the extracted folder::

          cd /c/sfepy_folder_name/

   b) Compile *SfePy* C extensions::

          python setup.py build_ext --inplace --compiler=mingw32

#. You should now have a working copy of *SfePy* on Windows. Please help
   aid *SfePy* development by running the built-in tests. Run the
   `run_tests.py` in Python IDLE or write the following code in the
   shell::

       ./run_tests.py --filter-less

   * Report any failures to the `SfePy mailing list`_.
   * See `Testing`_ for further details.
