=========================
Installation Guide
=========================

This guide is for **Version 6** of esys-escript.

esys-escript is primarily developed on Linux systems. The current version provides
some support for macOS but has not been ported to Windows.

For support and questions, please visit the
`Issues site <https://github.com/esys-escript/esys-escript.github.io/issues>`_.

For complete documentation including user guide and API reference, see the
:doc:`main documentation page <index>`.


Dependencies
============

Essential Dependencies
----------------------

* C++ compiler (g++, clang++, or similar)
* Python 3
* SCons build system
* CMake
* python3-numpy 2
* python3-matplotlib
* Boost libraries:

  - boost-python
  - boost-random
  - boost-iostreams


Non-Essential Dependencies
--------------------------

* LAPACKE - Linear algebra library for matrix operations in PASO solver (``liblapacke-dev`` on Debian/Ubuntu)
* HDF5-serial (for HDF5 file I/O) (``libhdf5-serial-dev`` on Debian/Ubuntu)
* SILO (recommended for VisIt visualization) (``libsilo-dev`` on Debian/Ubuntu)
* netCDF4 (for reading gridded data) (``libnetcdf-c++4-dev`` on Debian/Ubuntu)
* boost-numpy (recommended for Jupyter) (``libboost-numpy-dev`` on Debian/Ubuntu)
* UMFPACK - Direct sparse matrix solver (``libsuitesparse-dev`` on Debian/Ubuntu)
* MUMPS - MUltifrontal Massively Parallel sparse direct Solver, sequential version (``libmumps-seq-dev`` on Debian/Ubuntu)
* zlib - Compression library required by p4est for the oxley domain (``zlib1g-dev`` on Debian/Ubuntu)


Optional Dependencies
---------------------

* MPI implementation (OpenMPI or MPICH) with python3-mpi4py for distributed parallelization
* ParMETIS (for MPI builds)
* SymPy (``python3-sympy``) for symbolic mathematics module - **must be present at build time** (requires version 1.2 or later)
* python3-sphinx and python3-markdown (for building API documentation)
* LaTeX (texlive-latex-base, texlive-latex-extra) for building user guide PDF
* CppUnit (for running tests)

The source code is shipped with `Trilinos <https://trilinos.github.io/>`_ and
`p4est <https://www.p4est.org/>`_.


Recommended Tools
-----------------

These tools are not required at compile time but enhance functionality:

* `gmsh <https://gmsh.info/>`_ - mesh generation
* `VisIt <https://visit-dav.github.io>`_ - visualization via SILO or VTK
* `ParaView <https://www.paraview.org/>`_ - visualization via VTK
* `Mayavi <https://docs.enthought.com/mayavi/mayavi/>`_ - visualization via VTK
* `Matplotlib <https://matplotlib.org/>`_ - 2D plotting


Parallelization Support
=======================

esys-escript supports multiple parallelization strategies:

* **OpenMP** - Shared memory parallelization (multi-core), enabled at compilation
* **MPI** - Distributed memory parallelization (compute clusters), requires mpi4py
* **Hybrid mode** - Both OpenMP and MPI can be used simultaneously


Installation from Source
========================

Quick Start
-----------

1. Download the source code:

   .. code-block:: bash

      git clone --single-branch --branch master https://github.com/esys-escript/esys-escript.github.io.git esys6
      cd esys6

   Alternatively, download a tagged release from the
   `releases page <https://github.com/esys-escript/esys-escript.github.io/releases>`_.

2. Install dependencies for your platform (see Platform-Specific Instructions below)

3. Build esys-escript:

   .. code-block:: bash

      scons -j4 options_file=scons/templates/<OS>_options.py

   Replace ``<OS>`` with your operating system (e.g., ``debian``, ``ubuntu``, ``centos8``, etc.).

4. Set up environment variables:

   .. code-block:: bash

      export PYTHONPATH=$PWD:$PYTHONPATH
      export LD_LIBRARY_PATH=$PWD/lib/esys:$PWD/esys.trilinos/lib:$LD_LIBRARY_PATH

5. (Optional) Test your build:

   .. code-block:: bash

      scons -j4 py_tests options_file=scons/templates/<OS>_options.py


Custom Build Configuration
--------------------------

If you need to customize the build (e.g., disable MPI, change compilers, enable/disable dependencies),
create your own options file:

.. code-block:: bash

   HOST=`uname -n`
   cp scons/templates/<closest_match>_options.py scons/${HOST}_options.py
   # Edit scons/${HOST}_options.py as needed
   scons -j4

**For a complete list of all available configuration options, see the** :doc:`options`.

The options file must include ``escript_opts_version = 203`` to be accepted by the build system.


Building Documentation
----------------------

To build the documentation, install additional dependencies:

.. code-block:: bash

   sudo apt-get install python3-sphinx python3-markdown

For the user guide PDF, also install LaTeX:

.. code-block:: bash

   sudo apt-get install texlive-latex-base texlive-latex-extra texlive-fonts-recommended

Then build the docs:

.. code-block:: bash

   scons -j4 docs

This generates:

* Main entry point: ``release/doc/index.html``
* User guide (PDF): ``release/doc/user/user.pdf``
* Python API docs (Sphinx): ``release/doc/sphinx_api/``
* Example scripts: ``release/doc/escript_examples.{zip,tar.gz}``


Platform-Specific Instructions
==============================

Debian 12+
----------

The default options file (``debian_options.py``) builds with MPI enabled.
Install all required packages:

.. code-block:: bash

   sudo apt-get install python3-dev python3-numpy python3-scipy python3-matplotlib
   sudo apt-get install g++ gfortran scons cmake
   sudo apt-get install libboost-numpy-dev libboost-python-dev libboost-random-dev libboost-iostreams-dev
   sudo apt-get install libhdf5-serial-dev libsilo-dev libnetcdf-dev libsuitesparse-dev liblapacke-dev libmumps-seq-dev zlib1g-dev
   sudo apt-get install libmetis-dev libparmetis-dev
   sudo apt-get install libopenmpi-dev openmpi-bin python3-mpi4py

For building documentation, additionally install:

.. code-block:: bash

   sudo apt-get install python3-sphinx python3-markdown
   sudo apt-get install texlive-latex-base texlive-latex-extra texlive-fonts-recommended

For symbolic mathematics support, additionally install:

.. code-block:: bash

   sudo apt-get install python3-sympy

For running the test suite, additionally install:

.. code-block:: bash

   sudo apt-get install python3-silo

Build esys-escript:

.. code-block:: bash

   scons -j4 options_file=scons/templates/debian_options.py

To build **without MPI**, use ``debian_nompi_options.py`` instead and
``libopenmpi-dev``, ``openmpi-bin``, ``python3-mpi4py``, and ``libparmetis-dev``
can be omitted.


Ubuntu 24.04+
-------------

The default options file (``ubuntu_options.py``) builds with MPI enabled.
Install all required packages:

.. code-block:: bash

   sudo apt-get install python3-dev python3-numpy python3-scipy python3-matplotlib
   sudo apt-get install g++ gfortran scons cmake
   sudo apt-get install libboost-numpy-dev libboost-python-dev libboost-random-dev libboost-iostreams-dev
   sudo apt-get install libhdf5-serial-dev libsilo-dev libnetcdf-dev libsuitesparse-dev liblapacke-dev libmumps-seq-dev zlib1g-dev
   sudo apt-get install libmetis-dev libparmetis-dev
   sudo apt-get install libopenmpi-dev openmpi-bin python3-mpi4py

For building documentation, additionally install:

.. code-block:: bash

   sudo apt-get install python3-sphinx python3-markdown
   sudo apt-get install texlive-latex-base texlive-latex-extra texlive-fonts-recommended

For symbolic mathematics support, additionally install:

.. code-block:: bash

   sudo apt-get install python3-sympy

For running the test suite, additionally install:

.. code-block:: bash

   sudo apt-get install python3-silo

Build esys-escript:

.. code-block:: bash

   scons -j4 options_file=scons/templates/ubuntu_options.py

To build **without MPI**, use ``debian_nompi_options.py`` instead and
``libopenmpi-dev``, ``openmpi-bin``, ``python3-mpi4py``, and ``libparmetis-dev``
can be omitted.


Linux Mint 20.3+
----------------

Mint Linux is based on Ubuntu, use the same commands as Ubuntu above.


Arch Linux
----------

The default options file (``arch_options.py``) builds with MPI enabled.
Install all required packages:

.. code-block:: bash

   sudo pacman -Sy python python-numpy python-scipy python-matplotlib
   sudo pacman -Sy gcc scons cmake
   sudo pacman -Sy boost boost-libs suitesparse hdf5 netcdf lapack mumps zlib metis
   sudo pacman -Sy openmpi python-mpi4py

For building documentation:

.. code-block:: bash

   sudo pacman -Sy python-sphinx python-markdown
   sudo pacman -Sy texlive-core texlive-latexextra

For symbolic mathematics support:

.. code-block:: bash

   sudo pacman -Sy python-sympy

For running the test suite, additionally install:

.. code-block:: bash

   sudo pacman -Sy python-silo

Build esys-escript:

.. code-block:: bash

   scons -j4 options_file=scons/templates/arch_options.py

To build **without MPI**, use ``arch_nompi_options.py`` instead and
``openmpi`` and ``python-mpi4py`` can be omitted.


Fedora
------

The default options file (``fedora_options.py``) builds with MPI enabled.
Install all required packages:

.. code-block:: bash

   sudo dnf install python3-devel python3-numpy python3-scipy python3-matplotlib
   sudo dnf install gcc-c++ gcc-gfortran scons cmake
   sudo dnf install boost-devel boost-python3-devel boost-python3 boost-numpy3 boost-iostreams boost-random
   sudo dnf install hdf5-devel netcdf-devel suitesparse-devel lapack-devel MUMPS-devel zlib-devel metis-devel
   sudo dnf install openmpi-devel python3-mpi4py-openmpi

.. note::
   On Fedora, activate the MPI environment before building:
   ``module load mpi/openmpi-x86_64``

For building documentation:

.. code-block:: bash

   sudo dnf install python3-sphinx python3-markdown
   sudo dnf install texlive-scheme-basic texlive-latex texlive-latex-extra

For symbolic mathematics support:

.. code-block:: bash

   sudo dnf install python3-sympy

For running the test suite, additionally install:

.. code-block:: bash

   sudo dnf install python3-silo

Build esys-escript:

.. code-block:: bash

   scons -j4 options_file=scons/templates/fedora_options.py

To build **without MPI**, use ``fedora_nompi_options.py`` instead and
``openmpi-devel`` and ``python3-mpi4py-openmpi`` can be omitted.


OpenSUSE
--------

The default options file (``opensuse_options.py``) builds with MPI enabled.
Install all required packages:

.. code-block:: bash

   sudo zypper in python3-devel python3-numpy python3-scipy python3-matplotlib
   sudo zypper in gcc gcc-c++ gcc-fortran scons cmake
   sudo zypper in libboost_python3-devel libboost_numpy3-devel libboost_random-devel libboost_iostreams-devel
   sudo zypper in hdf5-devel netcdf-devel suitesparse-devel lapack-devel mumps-devel zlib-devel metis-devel
   sudo zypper in openmpi-devel python3-mpi4py

For building documentation:

.. code-block:: bash

   sudo zypper in python3-Sphinx python3-Markdown
   sudo zypper in texlive-latex texlive-latex-extra

For symbolic mathematics support:

.. code-block:: bash

   sudo zypper in python3-sympy

For running the test suite, additionally install:

.. code-block:: bash

   sudo zypper in python3-silo

Build esys-escript:

.. code-block:: bash

   scons -j4 options_file=scons/templates/opensuse_options.py

To build **without MPI**, use ``opensuse_nompi_options.py`` instead and
``openmpi-devel`` and ``python3-mpi4py`` can be omitted.


CentOS 8 / Rocky Linux / AlmaLinux
----------------------------------

The default options file (``rhel_options.py``) builds with MPI enabled.

Enable required repositories:

.. code-block:: bash

   sudo dnf install epel-release
   sudo dnf config-manager --set-enabled powertools

Install all required packages:

.. code-block:: bash

   sudo dnf install python3-devel python3-numpy python3-scipy python3-matplotlib
   sudo dnf install gcc gcc-c++ gcc-gfortran scons cmake
   sudo dnf install boost-devel boost-python3 boost-python3-devel
   sudo dnf install hdf5-devel netcdf-devel suitesparse suitesparse-devel lapack-devel MUMPS-devel zlib-devel metis-devel
   sudo dnf install openmpi-devel python3-mpi4py-openmpi

.. note::
   On RHEL-based systems, activate the MPI environment before building:
   ``module load mpi/openmpi-x86_64``

For building documentation:

.. code-block:: bash

   sudo dnf install python3-sphinx python3-markdown
   sudo dnf install texlive-scheme-basic texlive-latex

For symbolic mathematics support:

.. code-block:: bash

   sudo dnf install python3-sympy

For running the test suite, additionally install:

.. code-block:: bash

   sudo dnf install python3-silo

Build esys-escript:

.. code-block:: bash

   scons -j4 options_file=scons/templates/rhel_options.py

To build **without MPI**, use ``rhel_nompi_options.py`` instead and
``openmpi-devel`` and ``python3-mpi4py-openmpi`` can be omitted.


macOS with Homebrew
-------------------

.. note::

   macOS support is limited. Requires Xcode Command Line Tools.

The default options file (``homebrew_options.py``) builds with MPI enabled.
Install Homebrew from https://brew.sh, then:

.. code-block:: bash

   brew install python3 numpy scipy matplotlib
   brew install scons cmake
   brew install boost boost-python3
   brew install hdf5 netcdf suite-sparse lapack mumps metis
   brew install open-mpi

Some Python packages may need pip:

.. code-block:: bash

   pip3 install numpy scipy matplotlib mpi4py

For building documentation:

.. code-block:: bash

   pip3 install sphinx markdown
   brew install --cask mactex  # For LaTeX/PDF documentation

For symbolic mathematics support:

.. code-block:: bash

   pip3 install sympy

Build esys-escript:

.. code-block:: bash

   scons -j4 options_file=scons/templates/homebrew_options.py

To build **without MPI**, use ``homebrew_nompi_options.py`` instead and
``open-mpi`` and ``mpi4py`` can be omitted.


macOS with MacPorts
-------------------

.. note::

   macOS support is limited. Requires Xcode Command Line Tools.

The default options file (``macports_options.py``) builds with MPI enabled.
Install MacPorts from https://www.macports.org, then:

.. code-block:: bash

   sudo port install python311
   sudo port select --set python python311
   sudo port select --set python3 python311
   sudo port install py311-numpy py311-scipy py311-matplotlib
   sudo port install scons cmake boost hdf5 netcdf suitesparse lapack mumps
   sudo port install openmpi py311-mpi4py

For building documentation:

.. code-block:: bash

   sudo port install py311-sphinx py311-markdown
   sudo port install texlive  # For LaTeX/PDF documentation

For symbolic mathematics support:

.. code-block:: bash

   sudo port install py311-sympy

Build esys-escript:

.. code-block:: bash

   scons -j4 options_file=scons/templates/macports_options.py

To build **without MPI**, use ``macports_nompi_options.py`` instead and
``openmpi`` and ``py311-mpi4py`` can be omitted.


FreeBSD
-------

.. note::

   At the time of testing, numpy installation on FreeBSD had issues. Full testing has been limited.

.. code-block:: bash

   sudo pkg install python3 py39-numpy py39-scipy py39-matplotlib
   sudo pkg install scons cmake boost-python-libs hdf5 netcdf suitesparse lapack mumps

For building documentation:

.. code-block:: bash

   sudo pkg install py39-sphinx py39-markdown
   sudo pkg install texlive-full  # For LaTeX/PDF documentation

For symbolic mathematics support:

.. code-block:: bash

   sudo pkg install py39-sympy


Advanced Configuration
======================

Customizing Build Options
-------------------------

Edit your options file (``scons/<hostname>_options.py``) to customize:

* **OpenMP**: Enable/disable with ``openmp = True`` or ``openmp = False``
* **MPI**: Set ``mpi = 'OPENMPI'`` or ``mpi = 'none'``
* **SymPy**: Enable/disable symbolic module with ``sympy = True`` or ``sympy = False``
* **Compiler**: Change ``cxx``, ``cc`` variables
* **Optimization**: Modify ``cxx_extra`` flags
* **Libraries**: Adjust library paths and names


MPI Configuration
-----------------

Basic MPI Setup
^^^^^^^^^^^^^^^

To enable MPI with auto-detection (recommended):

.. code-block:: python

   mpi = 'auto'       # Auto-detect MPI implementation from mpi4py
   mpi4py = True

When ``mpi='auto'`` is set:

* If ``mpi4py=True``: Automatically detects the MPI implementation (OpenMPI, MPICH, Intel MPI) from your installed mpi4py package
* If ``mpi4py=False``: Sets ``mpi='none'`` (MPI disabled)

To manually specify the MPI implementation:

.. code-block:: python

   mpi = 'OPENMPI'  # or 'MPICH', 'MPICH2', 'INTELMPI'
   mpi_prefix = '/usr/lib/x86_64-linux-gnu/openmpi'
   mpi_libs = ['mpi_cxx', 'mpi']

.. important::

   When using ``mpi4py``, the MPI flavour must match the MPI implementation that mpi4py was compiled against.
   The build system will verify compatibility and report an error if there's a mismatch.

To disable MPI:

.. code-block:: python

   mpi = 'none'

Custom MPI Communicators with mpi4py
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When ``mpi4py = True`` is enabled, all domain factory functions (e.g., ``Rectangle``, ``Brick``,
``ReadMesh``, ``ReadGmsh``) accept an optional ``comm`` parameter that takes an mpi4py communicator object:

.. code-block:: python

   from mpi4py import MPI
   from esys.ripley import Rectangle

   # Use a custom communicator instead of MPI_COMM_WORLD
   custom_comm = MPI.COMM_WORLD.Split(color=..., key=...)
   domain = Rectangle(10, 10, comm=custom_comm)

If the ``comm`` parameter is not provided or is ``None``, ``MPI_COMM_WORLD`` is used by default.


SymPy Symbolic Module
---------------------

.. note::

   SymPy is a **runtime-only dependency** - it is not needed for compiling C++ code.
   However, **SymPy must be installed at build time** when ``sympy = True`` to enable the symbolic module.
   The build system checks for SymPy availability and sets a feature flag.
   If SymPy is not found at build time, the symbolic support will be disabled even if SymPy is installed later.

To enable symbolic mathematics support (requires SymPy 1.2 or later):

.. code-block:: python

   sympy = True

To disable symbolic support:

.. code-block:: python

   sympy = False  # Default

The symbolic module provides support for symbolic expressions, automatic differentiation,
and symbolic PDE formulation. See the `User Guide (PDF) <../user/user.pdf>`_ for details on using the symbolic toolbox.

.. important::

   If you build without SymPy and later install it, you must rebuild with ``sympy = True`` to enable symbolic support.


Trilinos Support
----------------

esys-escript includes Trilinos for advanced solver capabilities. Trilinos is built automatically
during the esys-escript build process.

For complex-valued PDEs and advanced preconditioners, ensure Trilinos support is enabled in your build.


Testing
=======

Unit Tests
----------

Run the test suite:

.. code-block:: bash

   scons -j4 py_tests

Or use the test script:

.. code-block:: bash

   ./utest.sh build -t4  # Run with 4 OpenMP threads

With MPI:

.. code-block:: bash

   ./utest.sh build -t2 -n2  # 2 threads, 2 MPI processes

.. note::

   Some tests require optional features (netCDF, SILO, etc.) and will report failures if those features are disabled.


Installation Layout
===================

After building, the directory structure is::

   esys-escript.github.io/
   ├── bin/
   │   └── run-escript              # Launcher script
   ├── esys/                        # Python package
   │   ├── escript/
   │   ├── finley/
   │   ├── ripley/
   │   ├── oxley/
   │   └── speckley/
   ├── lib/
   │   └── esys/                    # Compiled libraries
   ├── esys.trilinos/               # Trilinos installation
   │   └── lib/
   ├── release/                     # Documentation (if built)
   │   └── doc/
   │       ├── index.html
   │       └── sphinx_api/
   └── README.md


Running esys-escript
====================

Using the Launcher
------------------

.. code-block:: bash

   ./bin/run-escript myscript.py

The launcher automatically sets up the environment (PYTHONPATH, LD_LIBRARY_PATH, etc.).


Parallel Execution
------------------

With OpenMP (4 threads):

.. code-block:: bash

   ./bin/run-escript -t 4 myscript.py

With MPI (4 processes):

.. code-block:: bash

   ./bin/run-escript -n 4 myscript.py

Hybrid OpenMP + MPI (2 processes, 4 threads each):

.. code-block:: bash

   ./bin/run-escript -n 2 -t 4 myscript.py


Direct Python Usage
-------------------

If not using the launcher, set environment variables:

.. code-block:: bash

   export PYTHONPATH=/path/to/esys-escript.github.io:$PYTHONPATH
   export LD_LIBRARY_PATH=/path/to/esys-escript.github.io/lib/esys:$LD_LIBRARY_PATH
   export LD_LIBRARY_PATH=/path/to/esys-escript.github.io/esys.trilinos/lib:$LD_LIBRARY_PATH

   python3 myscript.py


Troubleshooting
===============

Common Issues
-------------

**Import errors:**

* Ensure ``PYTHONPATH`` and ``LD_LIBRARY_PATH`` are set correctly
* Check that all dependencies are installed

**Build failures:**

* Verify all required packages are installed
* Check compiler compatibility (C++11 support required)
* Review ``config.log`` for detailed error messages

**Test failures:**

* Some tests require optional features (HDF5, SILO, MPI)
* Tests will report failures for disabled features - this is expected

**MPI issues:**

* Ensure mpi4py version matches your MPI implementation
* Check that MPI paths in options file are correct
* Verify MPI is properly initialized with ``mpirun`` or ``mpiexec``


Getting Help
------------

* Report issues: `GitHub Issues <https://github.com/esys-escript/esys-escript.github.io/issues>`_
* Documentation: https://esys-escript.github.io/
* User guide: See ``release/doc/user/user.pdf`` after building docs


Optional Extras
===============

Direct Solvers
--------------

To enable UMFPACK (direct sparse solver):

.. code-block:: bash

   sudo apt-get install libsuitesparse-dev

Add to your options file:

.. code-block:: python

   umfpack = True


Visualization
-------------

Install visualization tools:

.. code-block:: bash

   # VisIt (via SILO format)
   sudo apt-get install visit

   # ParaView (via VTK format)
   sudo apt-get install paraview

   # Mayavi (via VTK format)
   pip3 install mayavi


Mesh Generation
---------------

Install gmsh for mesh generation:

.. code-block:: bash

   sudo apt-get install gmsh  # Linux
   brew install gmsh          # macOS


Compiler Requirements
=====================

esys-escript requires a C++11 compliant compiler. Tested compilers include:

* GCC g++ 10.2+
* Clang 11.0+
* Intel icpc v17+

Required C++11 features:

* ``std::complex<>``
* ``auto`` type declarations
* ``decltype(T)`` type declarations
* Explicit template instantiation
* ``std::isnan()`` in ``std`` namespace


License and Credits
===================

See `LICENSE <https://github.com/LutzGross/esys-escript.github.io/blob/master/LICENSE>`_
and `CREDITS <https://github.com/LutzGross/esys-escript.github.io/blob/master/CREDITS>`_
files in the distribution for license information and contributor acknowledgments.
