SfePy NTC

Table Of Contents

Previous topic

Introduction

Next topic

Tutorial

This Page

Installation

Supported Platforms

SfePy is known to work on various flavors of recent Linux, Intel-based MacOS and Windows. It can be used with both Python 2.7 and Python 3.x.

Note: Depending on Python installation and OS used, replacing python by python3 might be required in all the commands below (e.g. in Compilation of C Extension Modules) in order to use Python 3.

Requirements

Installation prerequisites, required to build SfePy:

Python packages required for using SfePy:

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

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 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 Using IPython).

Notes on selecting Python Distribution

SfePy should work with any recent Python 2.7 or 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:

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

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

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 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

    • 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

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 (localy 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

It is preferable to use (a customized) IPython over the regular Python shell when following Tutorial or 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:

    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
    

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 2.7/3.6 64-bit on Ubuntu 16.04 LTS, Windows 8.1+ and macOS 10.12+.)

Download appropriate Anaconda Python 2.7 or 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:

  1. 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
    
  2. installing the SfePy dependencies only - then proceed with the Installing SfePy 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