SfePy NTC

Table Of Contents

Previous topic

Introduction

Next topic

Tutorial

This Page

Installation

Platforms

SfePy is known to work on various flavors of Linux, on Intel Macs and Windows. It can work with both Python 2.7 and Python 3. 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.

The easiest way to install SfePy is to use Anaconda, see Multi-platform Distributions Notes.

Requirements

Installation prerequisites, required to build SfePy:

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

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

    1. for in-place use:

      python setup.py build_ext --inplace
      
    2. 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

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 the raise mode:

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

and 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 run_tests.py --debug tests/failing_test_name.py

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

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
    

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 or 3.x 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).

Anaconda can be used for

  1. installing the latest release of sfepy directly from the conda-forge channel, see sfepy-feedstock. In this case, simply do:

    conda install -c conda-forge sfepy
    

    Installing 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 Generic Installation Instructions 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>

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)

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

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

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

  4. 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”.

  5. Download the latest umfpackpy zip archive and follow the instructions below:

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

    2. Start a shell and write the following to go to the extracted folder:

      cd /c/umfpackpy_<version>/
      
    3. Install the UMFPACK library for Python:

      ez_setup.py scikits.umfpack-5.1.0-py2.7-win32.egg
      
  6. 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:

    1. In shell, go to the extracted folder:

      cd /c/sfepy_folder_name/
      
    2. Compile SfePy C extensions:

      python setup.py build_ext --inplace --compiler=mingw32
      
  7. 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