<commit_before>.. 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. SfePy requires Python 3. The release 2019.4 was the last with
Python 2.7 support.

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.


Requirements
------------

Installation prerequisites, required to build *SfePy*:

- a C compiler suite,
- `Python`_ 3.x,
- `NumPy`_,
- `Cython`_.

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,
- `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,
- `igakit`_ for script/gen_iga_patch.py - simple IGA domain generator,
- `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`_,
- `wxPython`_ for better `IPython`_ integration.
- `Read the Docs`_ `Sphinx`_ theme for building documentation
- `psutil`_ for memory requirements checking
- `PyVista`_ for post-processing via `resview.py`

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 :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 `pexpect` and `gmsh` or `tetgen`.
- `IPython`_ is recommended over the regular Python shell to fluently follow
  some parts of primer/tutorial (see :ref:`using-ipython`).
- `MUMPS`_ library for using MUMPS linear direct solver
  (real and complex arithmetic, parallel factorization)

.. _Python_distribution:

Notes on selecting Python Distribution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

- **Linux**: OS native installation (See `Notes on Installing SfePy
  Dependencies on Various Platforms`_ for further details.)

- **macOS**: multi-platform scientific Python distributions `Anaconda`_ (See
  `Notes on Multi-platform Python Distributions`_ for further details.)

- **Windows**: use free versions of commercial multi-platform
  scientific Python distributions `Anaconda`_ or
  `Enthought Canopy`_ (see `Notes on Multi-platform Python Distributions`_ for
  further details). In addition a completely free open-source portable
  distribution `WinPython`_ can be used.

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:

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


.. _running_sfepy_docker_images:

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

Currently available images are:

- `sfepy/sfepy-notebook <https://hub.docker.com/r/sfepy/sfepy-notebook>`__ -
  basic command line interface and web browser access to
  Jupyter notebook/JupyterLab interface,

- `sfepy/sfepy-x11vnc-desktop
  <https://hub.docker.com/r/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 <https://github.com/sfepy/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.

.. code-block:: yaml
   version: "3"
   services:
     sfepy:
       container_name: sfepy_container
       image: sfepy/sfepy-notebook
       command: jupyter lab
       volumes:
         - .:/home/sfepy/
       ports:
         - "8888:8888"



.. _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<commit_msg>Use `code/` subdirectory inside of container<commit_after>.. 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. SfePy requires Python 3. The release 2019.4 was the last with
Python 2.7 support.

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.


Requirements
------------

Installation prerequisites, required to build *SfePy*:

- a C compiler suite,
- `Python`_ 3.x,
- `NumPy`_,
- `Cython`_.

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,
- `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,
- `igakit`_ for script/gen_iga_patch.py - simple IGA domain generator,
- `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`_,
- `wxPython`_ for better `IPython`_ integration.
- `Read the Docs`_ `Sphinx`_ theme for building documentation
- `psutil`_ for memory requirements checking
- `PyVista`_ for post-processing via `resview.py`

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 :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 `pexpect` and `gmsh` or `tetgen`.
- `IPython`_ is recommended over the regular Python shell to fluently follow
  some parts of primer/tutorial (see :ref:`using-ipython`).
- `MUMPS`_ library for using MUMPS linear direct solver
  (real and complex arithmetic, parallel factorization)

.. _Python_distribution:

Notes on selecting Python Distribution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

- **Linux**: OS native installation (See `Notes on Installing SfePy
  Dependencies on Various Platforms`_ for further details.)

- **macOS**: multi-platform scientific Python distributions `Anaconda`_ (See
  `Notes on Multi-platform Python Distributions`_ for further details.)

- **Windows**: use free versions of commercial multi-platform
  scientific Python distributions `Anaconda`_ or
  `Enthought Canopy`_ (see `Notes on Multi-platform Python Distributions`_ for
  further details). In addition a completely free open-source portable
  distribution `WinPython`_ can be used.

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:

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


.. _running_sfepy_docker_images:

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

Currently available images are:

- `sfepy/sfepy-notebook <https://hub.docker.com/r/sfepy/sfepy-notebook>`__ -
  basic command line interface and web browser access to
  Jupyter notebook/JupyterLab interface,

- `sfepy/sfepy-x11vnc-desktop
  <https://hub.docker.com/r/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 <https://github.com/sfepy/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.

.. code-block:: yaml
   version: "3"
   services:
     sfepy:
       container_name: sfepy_container
       image: sfepy/sfepy-notebook
       command: jupyter lab
       volumes:
         - .:/home/sfepy/code/
       ports:
         - "8888:8888"



.. _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
{'fraction_non_alphanumeric': 0.10519933303016522, 'fraction_numerical': 0.006366530241018645, 'mean_word_length': 4.032418001525553, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 13, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7445727', 'n_tokens_mistral': 4140, 'n_tokens_neox': 3873, 'n_words': 1566}