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

.. _installing_sfepy:

Installing SfePy
----------------

The released versions of SfePy can be installed as follows.

- Using `pip`_::

    pip install sfepy

- Using `conda`_:

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

  #. 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`_.

.. _running_sfepy_docker_images:

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 <https://docs.docker.com/get-docker/>`__.

Currently available all-in-one image is:

- `sfepy/sfepy-desktop
  <https://hub.docker.com/r/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 <https://github.com/sfepy/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_<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, NumPy < 2.0 only,
- `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 :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 `gmsh` or `tetgen`.
- `IPython`_ is recommended over the regular Python shell to fluently follow
  some parts of primer/tutorial.

.. _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 `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
<https://docs.pytest.org/en/latest/how-to/usage.html>`_ 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`_.