Skip to content

installation.md

Latest commit

 

History

History
846 lines (588 loc) · 23 KB

installation.md

File metadata and controls

846 lines (588 loc) · 23 KB

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. For Windows users, we recommend using WSL2 (Windows Subsystem for Linux) - see the Windows section below.

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

  • METIS - Graph partitioning library used by Trilinos for matrix reordering (libmetis-dev on Debian/Ubuntu). Can be used with or without MPI.
  • MPI implementation (OpenMPI or MPICH) with python3-mpi4py for distributed parallelization
  • Graph Partitioning for MPI (requires MPI and METIS):
    • ParMETIS - Parallel graph partitioning for distributed mesh optimization in finley domain (libparmetis-dev on Debian/Ubuntu)
    • PT-Scotch - Alternative parallel graph partitioning library (libscotch-dev or scotch package). Used by both Trilinos and finley domain when ParMETIS is not available.
  • SymPy (python3-sympy) for symbolic mathematics module - must be present at build time (requires version 1.2 or later)
  • python3-sphinx, python3-markdown, and pandoc (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:

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

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

  2. Build esys-escript:

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

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

  1. Set up environment variables:
export PYTHONPATH=$PWD:$PYTHONPATH
export LD_LIBRARY_PATH=$PWD/lib/esys:$PWD/esys.trilinos/lib:$LD_LIBRARY_PATH
  1. (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 pandoc

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 libnetcdf-c++4-dev libsuitesparse-dev liblapacke-dev libmumps-seq-dev zlib1g-dev
sudo apt-get install libmetis-dev

For MPI support, additionally install:

sudo apt-get install python3-mpi4py
# For graph partitioning (choose one or both):
sudo apt-get install libparmetis-dev   # ParMETIS (if available)
sudo apt-get install libscotch-dev     # PT-Scotch (alternative)

For building documentation, additionally install:

sudo apt-get install python3-sphinx python3-markdown pandoc
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

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 libnetcdf-c++4-dev libsuitesparse-dev liblapacke-dev libmumps-seq-dev zlib1g-dev
sudo apt-get install libmetis-dev

For MPI support, additionally install:

sudo apt-get install python3-mpi4py
# For graph partitioning (choose one or both):
sudo apt-get install libparmetis-dev   # ParMETIS (if available)
sudo apt-get install libscotch-dev     # PT-Scotch (alternative)

For building documentation, additionally install:

sudo apt-get install python3-sphinx python3-markdown pandoc
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

Build esys-escript:

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

Linux Mint 20.3+

Linux Mint is based on Ubuntu. Use the same package installation commands as Ubuntu above, then build with:

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

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 mumps zlib metis

For MPI support:

sudo pacman -Sy python-mpi4py
# For graph partitioning (choose one or both):
sudo pacman -Sy parmetis  # ParMETIS (if available)
sudo pacman -Sy scotch    # PT-Scotch (alternative)

For building documentation:

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

For symbolic mathematics support:

sudo pacman -Sy python-sympy

Build esys-escript:

scons -j4 options_file=scons/templates/arch_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 MUMPS-devel zlib-devel metis-devel

For MPI support:

sudo dnf install python3-mpi4py
# For graph partitioning (choose one or both):
sudo dnf install parmetis-devel  # ParMETIS (if available)
sudo dnf install scotch-devel    # PT-Scotch (alternative)

For building documentation:

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

For symbolic mathematics support:

sudo dnf install python3-sympy

Build esys-escript:

scons -j4 options_file=scons/templates/fedora_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 mumps-devel zlib-devel metis-devel

For MPI support:

sudo zypper in python3-mpi4py
# For graph partitioning (choose one or both):
sudo zypper in parmetis-devel  # ParMETIS (if available)
sudo zypper in scotch-devel    # PT-Scotch (alternative)

For building documentation:

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

For symbolic mathematics support:

sudo zypper in python3-sympy

Build esys-escript:

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

RHEL / Rocky Linux / AlmaLinux

Works with RHEL 8/9, Rocky Linux, AlmaLinux, and CentOS Stream.

Enable required repositories:

sudo dnf install epel-release
sudo dnf config-manager --set-enabled powertools  # RHEL 8 / Rocky 8
# or: sudo dnf config-manager --set-enabled crb   # RHEL 9 / Rocky 9

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 MUMPS-devel zlib-devel metis-devel

For MPI support:

sudo dnf install python3-mpi4py
# For graph partitioning (choose one or both):
sudo dnf install parmetis-devel  # ParMETIS (if available)
sudo dnf install scotch-devel    # PT-Scotch (alternative)

For building documentation:

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

For symbolic mathematics support:

sudo dnf install python3-sympy

Build esys-escript:

scons -j4 options_file=scons/templates/rhel_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 scons cmake llvm
brew install boost boost-python3
brew install hdf5 netcdf suite-sparse openblas zlib metis scotch
brew install libomp  # For OpenMP support with Apple Clang

Python packages via Homebrew:

brew install numpy scipy python-matplotlib

For MPI support:

brew install open-mpi mpi4py
# PT-Scotch (scotch package) provides parallel graph partitioning
# ParMETIS is not available in Homebrew

For building documentation:

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

Build esys-escript:

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

Important: Apple Silicon (arm64) Users

The default homebrew_options.py uses Homebrew's LLVM for OpenMP support. However, recent versions of Homebrew LLVM (21.x) have a known bug causing linker errors on arm64 Macs.

If you encounter __hash_memory undefined symbol errors during the Trilinos build, use Apple's system Clang with libomp instead:

# Install libomp for OpenMP support
brew install libomp

# Create a custom options file
cp scons/templates/homebrew_options.py scons/my_options.py

# Edit my_options.py and change:
#   cc = 'clang'
#   cxx = 'clang++'
#   omp_flags = ['-Xpreprocessor', '-fopenmp']
#   omp_ldflags = ['-lomp']

# Then build with:
scons -j4 options_file=scons/my_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 mumps

For MPI support:

sudo port install openmpi py311-mpi4py

For building documentation:

sudo port install py311-sphinx py311-markdown pandoc
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

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 pandoc
sudo pkg install texlive-full  # For LaTeX/PDF documentation

For symbolic mathematics support:

sudo pkg install py39-sympy

Windows (via WSL2)

Native Windows builds are not supported. The recommended approach for Windows users is to use WSL2 (Windows Subsystem for Linux), which provides a full Linux environment.

Installing WSL2

  1. Open PowerShell as Administrator and run:
wsl --install

  1. Restart your computer when prompted.

  2. After restart, Ubuntu will be installed by default. You can also install other distributions:

wsl --install -d Debian
  1. Launch your Linux distribution from the Start menu and complete the initial setup (create username and password).

Building esys-escript in WSL2

Once inside WSL2, follow the standard Linux installation instructions:

# Update package lists
sudo apt-get update

# Install dependencies (same as Debian/Ubuntu)
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 libnetcdf-c++4-dev libsuitesparse-dev liblapacke-dev libmumps-seq-dev zlib1g-dev
sudo apt-get install libmetis-dev

# For building documentation (optional)
sudo apt-get install python3-sphinx python3-markdown pandoc
sudo apt-get install texlive-latex-base texlive-latex-extra texlive-fonts-recommended

# Clone and build
git clone https://github.com/esys-escript/esys-escript.github.io.git esys6
cd esys6
scons -j4 options_file=scons/templates/debian_options.py

For MPI support in WSL2:

sudo apt-get install python3-mpi4py
# For graph partitioning (choose one or both):
sudo apt-get install libparmetis-dev   # ParMETIS (if available)
sudo apt-get install libscotch-dev     # PT-Scotch (alternative)

Note: WSL2 provides near-native Linux performance and full compatibility with esys-escript. GUI applications (like VisIt or ParaView for visualization) require WSLg (included in Windows 11) or an X server on Windows 10.

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