.. include:: links.inc

.. _introduction_installation:

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

.. only:: html

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

Supported Platforms
-------------------

*SfePy* is known to work on various flavors of recent Linux, Intel-based MacOS
and Windows. SfePy requires Python 3. The release 2019.4 was the last with
Python 2.7 support.

Note: Depending on Python installation and OS used, replacing ``python`` by
``python3`` might be required in all the commands below
(e.g. in :ref:`compilation`) in order to use Python 3.


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

Installation prerequisites, required to build *SfePy*:

- a C compiler suite,
- `Python`_ 3.x,
- `NumPy`_,
- `Cython`_.

Python packages required for using *SfePy*:

- `Pyparsing`_,
- `SciPy`_,
- `meshio`_ for reading and writing mesh files,
- `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,
- `igakit`_ for script/gen_iga_patch.py - simple IGA domain generator,
- `petsc4py`_ and `mpi4py`_ for running parallel examples and using parallel
  solvers from `PETSc`_,
- `slepc4py`_ for eigenvalue problem solvers from `SLEPc`_
- `pymetis`_ for mesh partitioning using `Metis`_,
- `wxPython`_ for better `IPython`_ integration.
- `Read the Docs`_ `Sphinx`_ theme for building documentation
- `psutil`_ for memory requirements checking
- `PyVista`_ for post-processing via `resview.py`

Make sure the dependencies of those packages are also installed (e.g `igakit`_
reguires FORTRAN compiler, `scikit-umfpack`_ does not work without UMFPACK,
`petsc4py`_ without PETSc etc.). All dependencies of `meshio`_ need to be
installed for full mesh file format support (when using pip: ``pip install
meshio[all]``).

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

Other dependencies/suggestions:

- To be able to (re)generate the documentation `Sphinx`_, `numpydoc`_ and
  `LaTeX`_ are needed (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

- Mesh generation tools use `pexpect` and `gmsh` or `tetgen`.
- `IPython`_ is recommended over the regular Python shell to fluently follow
  some parts of primer/tutorial (see :ref:`using-ipython`).
- `MUMPS`_ library for using MUMPS linear direct solver
  (real and complex arithmetic, parallel factorization)

.. _Python_distribution:

Notes on selecting Python Distribution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*SfePy* should work with any recent Python 3.x (in long-term view
Python 3.6+ is recommended). It is only matter of taste to use either native OS
Python installation or any other suitable distribution. We could recommend
the following distributions to use:

- **Linux**: OS native installation (See `Notes on Installing SfePy
  Dependencies on Various Platforms`_ for further details.)

- **macOS**: multi-platform scientific Python distributions `Anaconda`_ (See
  `Notes on Multi-platform Python Distributions`_ for further details.)

- **Windows**: use free versions of commercial multi-platform
  scientific Python distributions `Anaconda`_ or
  `Enthought Canopy`_ (see `Notes on Multi-platform Python Distributions`_ for
  further details). In addition a completely free open-source portable
  distribution `WinPython`_ can be used.

On any supported platform we could recommend `Anaconda`_ distribution as
easy-to-use, stable and up-to-date Python distribution with all the
required dependencies (including pre-built `sfepy` package).

Note: all *SfePy* releases are regularly tested on recent Linux distributions
(Debian and (K)Ubuntu) using OS Python installation and Anaconda, macOS 10.12+
using Anaconda and Windows 8.1+ using Anaconda.

.. _installing_sfepy:

Installing SfePy
----------------

For `Anaconda`_ and `.deb` based Linux distributions (Debian, (K)Ubuntu),
pre-built *SfePy* packages are available. You may directly install them with:

- `Anaconda`_ distribution: install `sfepy` from `conda-forge`_ channel::

   conda install -c conda-forge sfepy

- Debian/(K)Ubuntu: install `python-sfepy`::

   sudo apt-get install python-sfepy

There are no further steps required to install/configure *SfePy*
(see `Notes on Multi-platform Python Distributions`_ for additional notes).


.. _running_sfepy_docker_images:

Using SfePy Docker Images
---------------------------

Besides the classical installation we also provide experimental Docker images
with ready-to-run Anaconda and *Sfepy* installation.

Before you start using *SfePy* images, you need to first install and configure
Docker on your computer. To do this follow official
`Docker documentation <https://docs.docker.com/get-docker/>`__.

Currently available images are:

- `sfepy/sfepy-notebook <https://hub.docker.com/r/sfepy/sfepy-notebook>`__ -
  basic command line interface and web browser access to
  Jupyter notebook/JupyterLab interface,

- `sfepy/sfepy-x11vnc-desktop
  <https://hub.docker.com/r/sfepy/sfepy-x11vnc-desktop>`__ -
  optimized Ubuntu desktop environment accessible via standard web browser
  or VNC client.

For available runtime options and further information see
`sfepy-docker <https://github.com/sfepy/sfepy-docker>`__ project on Github.


.. _installing_from_sources:

Installing SfePy from Sources
-----------------------------

The latest stable release can be obtained from the `download`_ page. Otherwise,
download the 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:

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

#. Compile the extension modules

   - for in-place use::

        python setup.py build_ext --inplace

   - for installation::

        python setup.py build

  We recommend starting with the in-place build.

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

*SfePy* can be used without any installation by running its main scripts
and examples from the top-level directory of the distribution or can be
installed *locally* or *system-wide*:

- 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 Installation`_.

.. _testing_installation:

Testing Installation
--------------------

After building and/or installing *SfePy* you should check if all the
functions are working properly by running the automated tests.

Running Automated Test Suite
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Depending on type of your build run following tests:

- in-place build::

    python ./run_tests.py

  or ::

    python ./sfepy-run run_tests

  or (on Unix-based systems) directly by ::

    ./sfepy-run run_tests


- installed (local or system-wide) build::

    sfepy-run run_tests

  (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.)

  Please note this method is *not fully supported on Windows
  systems yet*. It can be currently used only with pre-compiled `sfepy`
  packages (see `Installing SfePy`_).


Running Failing Tests in Raise Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If a particular test fails, run it in the raise mode ::

    python sfepy-run run_tests --raise tests/<failing_test_name.py>

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

It is also possible to automatically start a debugger when/if an exception
is raised by running a test in the debug mode::

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



Debugging
---------

If something goes wrong,  edit the ``site_cfg.py`` config file and set
``debug_flags = '-DDEBUG_FMF'``
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 to the `SfePy mailing list`_.

.. _using-ipython:

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

We generally recommend to use (a customized) `IPython`_ interactive shell over
the regular Python interpreter when following :doc:`tutorial` or
:doc:`primer` (or even for any regular interactive work with *SfePy*).

Install `IPython`_ (as a generic part of your selected distribution) and then
customize it to your choice.

Depending on your IPython usage, you can customize your `default` profile or
create a *SfePy* specific new one as follows:

#. Create a new *SfePy* profile::

     ipython profile create sfepy

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

   .. sourcecode:: python

      exec_lines = [
          'import numpy as nm',
          'import matplotlib as mpl',
          'mpl.use("WXAgg")',
      #
      # Add your preferred SfePy customization here...
      #
      ]

      c.InteractiveShellApp.exec_lines = exec_lines
      c.TerminalIPythonApp.gui = 'wx'
      c.TerminalInteractiveShell.colors = 'Linux' # NoColor, Linux, or LightBG

   Please note, that generally it is not recommended to use `star` (*)
   imports here.

#. Run the customized IPython shell::

     ipython --profile=sfepy


.. _multi_platform_distributions_notes:

Notes on Multi-platform Python Distributions
--------------------------------------------

Anaconda
^^^^^^^^

We highly recommend this scientific-oriented Python distribution.

(Currently regularly tested by developers on *SfePy* releases
with Python 3.6 64-bit on Ubuntu 16.04 LTS, Windows 8.1+ and macOS 10.12+.)

Download appropriate `Anaconda`_ Python 3.x installer package and follow
install instructions. We recommend to choose *user-level* install option (no
admin privileges required).

Anaconda can be used for:

#. installing the latest release of *SfePy*  directly from the `conda-forge`_
   channel (see `sfepy-feedstock`_). In this case, follow the instructions
   in `Installing SfePy`_.

   Installing/upgrading *SfePy*  from the conda-forge channel can also be
   achieved by adding `conda-forge`_ to your channels with::

     conda config --add channels conda-forge

   Once the `conda-forge`_ channel has been enabled, *SfePy* can be installed
   with::

     conda install sfepy

   It is possible to list all of the versions of *SfePy*  available on your
   platform with::

     conda search sfepy --channel conda-forge

#. installing the *SfePy* dependencies only - then proceed with the
   :ref:`installing_from_sources` instructions.

   In this case, install the missing/required packages using built-in `conda`
   package manager::

     conda install mayavi wxpython

   See `conda help` for further information.

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>

or try::

  conda update --all


Compilation of C Extension Modules on Windows
"""""""""""""""""""""""""""""""""""""""""""""

To build *SfePy* extension modules, included `mingw-w32/64`_ compiler tools
should work fine. If you encounter any problems, we recommend to install and
use Microsoft `Visual C++ Build Tools`_ instead (see `Anaconda FAQ`_).


Notes on Installing SfePy Dependencies on Various Platforms
-----------------------------------------------------------

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 `(K)Ubuntu`_ below.)

First, you have to install the dependencies packages::

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

Than *SfePy* can be installed with::

   apt-get install python-sfepy

(K)Ubuntu
^^^^^^^^^

(Tested on Kubuntu 16.04 LTS.)

First, you have to install the dependencies packages (if `apt-get` is not
installed, install it or try `apt-get install` instead)::

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

Than *SfePy* can be installed with::

   apt-get install python-sfepy