.. 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. The release 2019.4 was the last with Python 2.7 support. *SfePy*
should work with any recent Python 3.x that is supported by `NumPy`_ and
`SciPy`_.
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.
.. _Python_distribution:
Notes on selecting Python Distribution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is only matter of taste to use either native OS Python installation, `pip`,
or any other suitable distribution. On all supported platforms we could
recommend multi-platform scientific Python distributions `Anaconda`_ as
easy-to-use, stable and up-to-date Python distribution with all the required
dependencies (including pre-built `sfepy` package). See also `Notes on
Multi-platform Python Distributions`_ for further details.
On different platforms the following options can be recommended:
- **Linux**: `Anaconda`_, OS native installation, if available, or `pip`_.
- **macOS**: `Anaconda`_.
- **Windows**: free versions of commercial scientific Python distributions
`Anaconda`_ or `Enthought Deployment Manager`_ . In addition a completely free
open-source portable distribution `WinPython`_ can be used.
.. _installing_sfepy:
Installing SfePy
----------------
The released versions of SfePy can be installed as follows.
- Using `pip`_::
pip install sfepy
- Using `Anaconda`_: install `sfepy` from `conda-forge`_ channel::
conda install -c conda-forge sfepy
See `Notes on Multi-platform Python Distributions`_ for additional notes.
If the installation succeeded, proceed with `Testing Installation`_.
.. _running_sfepy_docker_images:
Using SfePy Docker Images
---------------------------
Besides the classical installation we also provide official 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 `__.
Currently available all-in-one image is:
- `sfepy/sfepy-desktop
`__ -
an Ubuntu based container containing a full desktop environment in
officially supported flavors accessible via any modern web browser.
For available runtime options and further information see
`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_.`.
See the `download`_ page for additional download options.
Requirements
^^^^^^^^^^^^
Installation prerequisites, required to build *SfePy*:
- a C compiler suite,
- `Python`_ 3.x,
- `NumPy`_,
- `Cython`_.
- `Cmake`_
- `scikit-build`_
- `ninja`_
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,
- `PyTables`_ for storing results in HDF5 files,
- `SymPy`_ for some tests and functions,
- `igakit`_ for generating IGA domains,
- `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`_,
- `Read the Docs`_ `Sphinx`_ theme for building documentation,
- `psutil`_ for memory requirements checking,
- `PyVista`_ for post-processing.
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)
.. _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.
#. For in-place use, compile the extension modules::
python setup.py build_ext --inplace
After a successful compilation, *SfePy* can be used in-place. However, the
the ``sfepy-*`` commands, such as ``sfepy-run`` are only available after
installing the package. Their functionality can be accessed by invoking
directly the corresponding scripts in ``sfepy/scripts/``.
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)::
pip install .
- local::
pip install --user .
- development (editable install)::
pip install -e .
The editable install allows working in-place and at the same time the
``sfepy-*`` commands are available.
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The test suite is based on `pytest`_. Install it by::
pip install pytest
or::
conda install pytest
when working in `Anaconda`_. If *SfePy* was installed, it can be tested using
the command::
sfepy-test
that accepts all of the `pytest`_ options, for example::
sfepy-test -vv --durations=0 -m 'not slow' -k test_assembling.py
The tests output directory can also be specified::
sfepy-test --output-dir=output-tests
In general. the tests can be run using::
python -c "import sfepy; sfepy.test()"
in the *SfePy* top-level directory in case of the in-place build and anywhere
else when testing the installed package. Additional `pytest`_ options can be
passed as arguments to ``sfepy.test()``, for example::
python -c "import sfepy; sfepy.test('-vv', '--durations=0', '-m not slow', '-k test_assembling.py')"
Analogously to ``sfepy-test``, the tests output directory can be specified
using::
python -c "import sfepy; sfepy.test('--output-dir=output-tests')"
See `pytest usage instructions
`_ for other options and
usage patterns.
To test an in-place build (e.g. in a cloned git repository), the following
simpler command can be used in the sources top-level directory::
python -m pytest sfepy/tests
python -m pytest -v sfepy/tests/test_assembling.py
which will also add the current directory to ``sys.path``. If the top-level
directory is already in ``sys.path`` (e.g. using ``export PYTHONPATH=.``), the
simplest way of invoking pytest is::
pytest sfepy/tests
pytest -v sfepy/tests/test_assembling.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 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
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`_).