Installation Guide

Hints and Tips

Source code build using mamba

We recommend that you use a conda / mamba virtual environment to build underworld3 whenever you want to install on a personal workstation or laptop (linux or macOS).The mamba documentation will help you get started if you are not familiar with the philososphy and practice of this package management system.

The underworld3 build / run-time dependencies can be installed using

    (base) % git clone -b development --single-branch https://github.com/underworldcode/underworld3 /path/to/underworld3
    (base) % cd /path/to/underworld3
    (base) % mamba env create -n uw3 -f environment.yml
    (base) % mamba activate uw3

    (uw3) % compile.sh

Source code build using mamba and existing PETSc

If you have an exisiting build of PETSc that you need to use, the following instructions work well. We create the environment as before but remove the pre- installed PETSc and petsc4py.

    (base) % git clone -b development --single-branch https://github.com/underworldcode/underworld3 /path/to/underworld3
    (base) % cd /path/to/underworld3
    (base) % mamba env create -n uw3p -f environment.yml
    (base) % mamba activate uw3p

    (uw3p) % mamba remove petsc4py
    (uw3p) % mamba remove petsc

Next set up PETSc as you like it and build it using the tools within the current mamba virtual environment. Set the PETSC_ARCH environment variable to the name of this virtual environment to keep things from becoming muddled. See PETSc Installation for details on how to configure and build what you need.

    (uw3p) % export PETSC_DIR=/path/to/petsc
    (uw3p) % export PETSC_ARCH="uw3p"
    (uw3p) % git clone -b release https://gitlab.com/petsc/petsc.git $PETSC_DIR
    (uw3p) % cd $PETSC_DIR
    (uw3p) % # Configure & Build step

Next we pip install the petsc4py that we just built into the mamba virtual environment. This ensures that petsc4py is available and also that its internal configuration points to the PETSc installation we just created. This way we don’t need to manage environment variables to point to the build that corresponds to a given virtual environment.

    (uw3p) % mamba install cmake
    (uw3p) % cd $PETSC_DIR/src/binding/petsc4py
    (uw3p) % pip install .

Building underworld3 against this version of PETSc should be identical to the mamba version.

    (uw3p) % cd /path/to/underworld3
    (uw3p) % compile.sh

Did it work ?

First run the tests:

    (uw3p) % cd /path/to/underworld3
    (uw3p) % source test.sh

If you have problems, contact us via the underworl3 GitHub issue tracker

To uninstall underworld3

  (uw3) % pip uninstall underworld3

And to clean the source directory if applicable

  (uw3) % cd /path/to/underworld3
  (uw3) % ./clean.sh

Docker container

Windows users, if you don’t want to create a linux partition, you can use our containers with docker or podman. As the code is still in active development, we are not always able to provide containers for each change to the development branch. We ask that you reach out to us on our GitHub issue tracker to ask for information (use the “question” label).

HPC builds

Underworld3 is inherently parallel and designed for use in high performance computing environments. The symbolic layer is relatively lightweight and should not adversely affect launch time (drawing down libraries from disk) or execution time (very few calculations are done in python itself).

In the HPC environment you may find it difficult to control the software stack. You will need to ensure that you can build against PETSc 3.21 or higher, since important functionality that we need is only available from that release onwards. We are happy to provide assistance with builds on specific machines and ask that you contact us through the GitHub issue tracker so that other people are able to browse the issues and their fixes.