Underworld Installation

Underworld 2 can be installed in multiple ways, using the container (preferred), from source code (advanced). It can also be installed on HPC clusters. These installation methods are documented below.

Container

Containers provide a type of lightweight virtualisation. The Underworld 2 container includes the latest version of Underworld 2 with all the dependencies packages and is the preferred method for usage on personal computers.

You will first need to install podman (recommended) or docker on your system. Both these tools can be used from the command line, but new users may wish to use the GUI Desktop versions to get started with it.

The following script is the recommended way for launching the container with podman.

sh ./docs/development/container/launch-container.sh

This will take a moment to load up - be patient please. What you’ll get is a container running a functioning Jupyterlab environment with the latest Underworld 2 installed at localhost:20000. A directory called uw_space will be create in the user’s home directory which is (volume) mapped into the container, this acts as a tranfser directory for sending files to and from the container.

Remember to take note of the Jupyterlab token from the start up messages. It will look something like.

http://127.0.0.1:20000/lab?token=e79006f4e441cf781440a9ea0cad8cf2a0dfd3b9c236a0ca

The value must be copy-pasted into the jupyterlab launch page the first time.

We welcome feedback and support requests at our github issue tracker.

HPC Installation

Detailed instructions for supported HPC platforms may be found at docs/install_guides. You may also find useful usage information (on docker/hpc/compilation/other) on the Underworld blog.

Pixi (Developer Installation)

Pixi is the recommended method for developers building Underworld2 from source. It manages a reproducible conda-forge + PyPI environment with lock files for deterministic builds.

Requirements

  • pixi installed on your system

Building

pixi install        # create/restore environment with all dependencies
pixi run build      # build and install the C/C++ extension (CMake+Ninja+SWIG)
pixi run test       # run the test suite

To activate the environment for interactive use:

pixi shell

Under the hood, pixi run build executes pip install . which drives the CMake configure → build → install pipeline for the libUnderworld extension.

The complete set of dependencies is defined in pixi.toml and locked to exact versions in pixi.lock for reproducibility.

Native Installation

Build environment

  • cmake >= 3.16

  • MPICH or OPENMPI

  • PETSc

  • HDF5

  • SWIG (>= 4.0)

  • LibXML (>= 2.0)

  • Python (>3.5, <= 3.11)

  • Numpy

  • Ninja

Running Requirements

  • h5py: The standard h5py (installed via pip) is the recommended version for desktop usage. However, note that it will be the non-parallel enabled version, and for large parallel simulations saving/reading data may become a bottleneck, and collective IO via MPI-enabled h5py is recommended. The following command may be useful for installed MPI-enabled h5py where necessary:

    CC=mpicc HDF5_MPI="ON" HDF5_DIR=/path/to/your/hdf5/install/ pip install --no-binary=h5py h5py

    or alternatively you might use CC=h5pcc (if available). Note that you will also need to have a parallel HDF5 library installed. Please check the h5py site for more information. Underworld will automatically perform save()/load() operations collectively if MPI-enabled hdf5 is available.

  • mpi4py

  • pint

  • lavavu: For rendering of visualisations, you will also need to install lavavu (via pip). Please check the lavavu page for further installation instructions.

Building Underworld

You can install Underworld using pip as follows:

pip install underworld2

or using our GitHub repository:

pip install -v git+https://github.com/underworldcode/underworld2

Testing

Simple tests can be run to check your installation. They will require you to install pytest (usually via pip). Note that some tests also require matplotlib

  • pytest

pytest -vvv ./docs/pytests