Installation

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.

Installing SfePy

The released versions of SfePy can be installed as follows.

• Using pip:

  pip install sfepy
  

• Using conda:

  1. Install miniforge. The miniforge distribution contains the minimal installers for Conda and Mamba specific to conda-forge. The packages are automatically pulled from the conda-forge channel. In case of a prior installation, remove the defaults channel to avoid a potential Anaconda terms of service violation:

     conda config --remove channels defaults
     

  2. Install sfepy:

     conda install sfepy
     

The above commands pull automatically all required dependencies. This, in combination with installing_from_sources, enables to try the git version easily. For example with conda, use:

conda remove --force sfepy

to remove the installed sfepy package but keep the dependencies installed.

If the installation succeeded, proceed with Testing Installation.

Using SfePy Docker Images

Besides the classical installation we also provide official Docker images with a ready-to-run miniforge-based 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 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:

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

• mumpspy or python-mumps for linear direct and Schur solver MUMPS

• 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, mumpspy requires MUMPS library, 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 gmsh or tetgen.

• IPython is recommended over the regular Python shell to fluently follow some parts of primer/tutorial.

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

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