Installation¶
Table of Contents
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 Compilation of C Extension Modules) in order to use Python 3.
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:
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.
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.
Currently available images are:
sfepy/sfepy-notebook - basic command line interface and web browser access to Jupyter notebook/JupyterLab interface,
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 project on Github.
As a convenience, use the following Docker compose file, which will start the
SfePy image, run Jupyter Lab, and map the contents of the local directory
to the SfePy home directory within the image. Just create an empty folder and
add the following to a file named docker-compose.yml
. Then, run docker-compose up
in the same directory.
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.
Requirements¶
Installation prerequisites, required to build SfePy:
Python packages required for using SfePy:
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,
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 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).
MUMPS library for using MUMPS linear direct solver (real and complex arithmetic, parallel factorization)
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 assfepy-run
are only available after installing the package. Their functionality can be accessed by invoking directly the corresponding scripts insfepy/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¶
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¶
We generally recommend to use (a customized) IPython interactive shell over the regular Python interpreter when following Tutorial or 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 thec = get_config()
line: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
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 Installing SfePy 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 <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).