esys-escript 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

Required Dependencies

C++ compiler (g++, clang++, or similar)
Python 3
SCons build system
CMake
python3-numpy
python3-matplotlib
Boost libraries:
boost-python
boost-random
boost-iostreams
boost-numpy (optional, recommended for Jupyter)

Optional Dependencies

LAPACKE (liblapacke-dev on Debian/Ubuntu) - Linear algebra library for matrix operations in PASO solver
MPI implementation (OpenMPI or MPICH) with python3-mpi4py for distributed parallelization
ParMETIS (for MPI builds)
HDF5-serial (for HDF5 file I/O)
SILO (recommended for VisIt visualization)
UMFPACK (libsuitesparse-dev on Debian/Ubuntu) - Direct sparse matrix solver
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.

Recommended Tools

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

gmsh - mesh generation
VisIt - visualization via SILO or VTK
ParaView - visualization via VTK
Mayavi - visualization via VTK
Matplotlib - 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

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

Install dependencies for your platform (see Platform-Specific Instructions below)
Build esys-escript:

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

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

Set up environment variables:

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

(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+

Install 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

For MPI support, additionally install:

sudo apt-get install python3-mpi4py libparmetis-dev

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

Build esys-escript:

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

Ubuntu 24.04+

Install 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

For MPI support, additionally install:

sudo apt-get install python3-mpi4py libparmetis-dev

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

Build esys-escript:

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

Linux Mint 20.3+

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

Arch Linux

Install 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

For MPI support:

sudo pacman -Sy python-mpi4py parmetis

For building documentation:

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

Build esys-escript:

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

Fedora

Install 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

For MPI support:

sudo dnf install python3-mpi4py parmetis-devel

For building documentation:

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

Build esys-escript:

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

OpenSUSE

Install 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

For MPI support:

sudo zypper in python3-mpi4py parmetis-devel

For building documentation:

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

Build esys-escript:

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

CentOS 8 / Rocky Linux / AlmaLinux

Enable required repositories:

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

Install 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

For MPI support:

sudo dnf install python3-mpi4py parmetis-devel

For building documentation:

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

Build esys-escript:

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

macOS with Homebrew

Note: macOS support is limited. Requires Xcode Command Line Tools.

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

Some Python packages may need pip:

pip3 install numpy scipy matplotlib

For MPI support:

brew install open-mpi
pip3 install mpi4py

For building documentation:

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

Build esys-escript:

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

macOS with MacPorts

Note: macOS support is limited. Requires Xcode Command Line Tools.

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

For MPI support:

sudo port install openmpi py311-mpi4py

For building documentation:

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

Build esys-escript:

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

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

For building documentation:

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

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'
Compiler: Change cxx, cc variables
Optimization: Modify cxx_extra flags
Libraries: Adjust library paths and names

MPI Configuration

To enable MPI, ensure in your options file:

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

To disable MPI:

mpi = 'none'

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

Report issues: GitHub 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):

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.