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.

For complete documentation including user guide and API reference, see the main documentation page.

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

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:

    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.

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

  3. Build esys-escript:

    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:

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

  5. (Optional) Test your build:

    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:

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 Build Options Reference.

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:

sudo apt-get install python3-sphinx python3-markdown

For the user guide PDF, also install LaTeX:

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

Then build the docs:

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:

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:

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:

sudo apt-get install python3-sympy

For running the test suite, additionally install:

sudo apt-get install python3-silo

Build esys-escript:

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:

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:

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:

sudo apt-get install python3-sympy

For running the test suite, additionally install:

sudo apt-get install python3-silo

Build esys-escript:

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:

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:

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

For symbolic mathematics support:

sudo pacman -Sy python-sympy

For running the test suite, additionally install:

sudo pacman -Sy python-silo

Build esys-escript:

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:

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:

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

For symbolic mathematics support:

sudo dnf install python3-sympy

For running the test suite, additionally install:

sudo dnf install python3-silo

Build esys-escript:

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:

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:

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

For symbolic mathematics support:

sudo zypper in python3-sympy

For running the test suite, additionally install:

sudo zypper in python3-silo

Build esys-escript:

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:

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

Install all required packages:

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:

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

For symbolic mathematics support:

sudo dnf install python3-sympy

For running the test suite, additionally install:

sudo dnf install python3-silo

Build esys-escript:

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:

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:

pip3 install numpy scipy matplotlib mpi4py

For building documentation:

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

For symbolic mathematics support:

pip3 install sympy

Build esys-escript:

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:

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:

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

For symbolic mathematics support:

sudo port install py311-sympy

Build esys-escript:

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.

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:

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

For symbolic mathematics support:

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

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:

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:

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:

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

sympy = True

To disable symbolic support:

sympy = False  # Default

The symbolic module provides support for symbolic expressions, automatic differentiation, and symbolic PDE formulation. See the User Guide (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:

scons -j4 py_tests

Or use the test script:

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

With MPI:

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

./bin/run-escript myscript.py

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

Parallel Execution

With OpenMP (4 threads):

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

With MPI (4 processes):

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

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

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

Direct Python Usage

If not using the launcher, set environment variables:

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

Optional Extras

Direct Solvers

To enable UMFPACK (direct sparse solver):

sudo apt-get install libsuitesparse-dev

Add to your options file:

umfpack = True

Visualization

Install visualization tools:

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

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 and CREDITS files in the distribution for license information and contributor acknowledgments.