Download and Install Devito
There are two main approaches to installing Devito.
Docker
, for those looking for the least-friction way to try DevitoVirtual environment
, for those looking to use Devito as part of a project alongside other packages
Docker
Devito Docker image library
In order to facilitate the dissemination, usage, and development of Devito, we provide a series of Docker images. These images support numerous architectures and compilers and are tagged accordingly. You can find all the available images at DevitoHub. The following describes the available images and the workflow to build it yourself.
Devito images
Devito provides several images that target different architectures and compilers. In the following, all images are described as imagename-*
. The *
corresponds to, and should be swapped for, the different release tags dev
, latest
or vx.x.x
depending on if you are interested in specific versions (vx.x.x
), the latest stable release(latest
), or the latest development status (dev
).
Devito on CPU
We provide two CPU images: - devito:gcc-*
with the standard GNU gcc compiler. - devito:icx-*
with the Intel C compiler for Intel architectures.
These images provide a working environment for any CPU architecture and come with Devito, gcc/icx
and mpi
preinstalled, and utilities such as jupyter
for usability and exploration of the package.
To run this image locally, you will first need to install docker
. Then, the following commands will get you started:
# Pull image and start a bash shell
docker run --rm -it -p 8888:8888 -p 8787:8787 -p 8786:8786 devitocodes/devito:gcc-latest /bin/bash
docker run --rm -it -p 8888:8888 -p 8787:8787 -p 8786:8786 --device=/dev/infiniband/uverbs0 --device=/dev/infiniband/rdma_cm devitocodes/devito:gcc-latest /bin/bash
# or start a Jupyter notebook server on port 8888
docker run --rm -it -p 8888:8888 devitocodes/devito:gcc-latest
Alternatively, to run in user context on a cluster with a shared filesystem, you can add the correct user config as docker
options, e.g.:
docker run --rm -it -v `pwd`:`pwd` -w `pwd` -u $(id -u):$(id -g) devitocodes/devito:gcc-latest python examples/seismic/acoustic/acoustic_example.py
Notes: In addition, the following legacy tags are available:
devito:cpu-*
that corresponds todevito:gcc-*
Devito on GPU
Second, we provide three images to run Devito on GPUs, tagged devito:nvidia-nvc-*
, and devito:amd-*
.
devito:nvidia-nvc-*
is intended to be used on NVidia GPUs. It comes with the configuration to use thenvc
compiler foropenacc
offloading. This image also comes with CUDA-aware MPI for multi-GPU deployment.devito:amd-*
is intended to be used on AMD GPUs. It comes with the configuration to use theaoompcc
compiler foropenmp
offloading. This image also comes with ROCm-aware MPI for multi-GPU deployment. This image can also be used on AMD CPUs since the ROCm compilers are preinstalled.
NVidia
To run the NVidia GPU version, you will need nvidia-docker installed and to specify the GPUs to use at runtime with the --gpus
flag. See, for example, a few runtime commands for the NVidia nvc
images.
docker run --gpus all --rm -it -p 8888:8888 -p 8787:8787 -p 8786:8786 devitocodes/devito:nvidia-nvc-latest
docker run --gpus all --rm -it devitocodes/devito:nvidia-nvc-latest python examples/seismic/acoustic/acoustic_example.py
docker run --gpus all --rm -it -p 8888:8888 -p 8787:8787 -p 8786:8786 --device=/dev/infiniband/uverbs0 --device=/dev/infiniband/rdma_cm devitocodes/devito:nvidia-nvc-latest
or to run in user context on a cluster with a shared filesystem, you can add the correct user config as docker
options, e.g.:
docker run --gpus all --rm -it -v `pwd`:`pwd` -w `pwd` -u $(id -u):$(id -g) devitocodes/devito:nvidia-nvc-latest python examples/seismic/acoustic/acoustic_example.py
AMD
Unlike NVidia, AMD does not require an additional Docker setup and runs with the standard docker. You will, however, need to pass some flags so that the image is linked to the GPU devices. You can find a short walkthrough in these AMD notes for their TensorFlow GPU Docker image.
Notes: In addition, the following legacy tags are available:
devito:gpu-*
that corresponds todevito:nvidia-nvc-*
Build a Devito image
To build the images yourself, you only need to run the standard build command using the provided Dockerfile. The main difference between the CPU and GPU images will be the base image used.
To build the (default) CPU image, run:
docker build --network=host --file docker/Dockerfile.devito --tag devito .
To build the GPU image with openacc
offloading and the nvc
compiler, run:
docker build --build-arg base=devitocodes/bases:nvidia-nvc --network=host --file docker/Dockerfile.devito --tag devito .
or if you wish to use the amdclang
compiler with openmp
offloading for AMD architectures:
docker build --build-arg base=devitocodes/bases:amd --network=host --file docker/Dockerfile --tag devito .
Debugging a base image
To build the base image yourself locally, you need to run the standard build command using the provided Dockerfile. Following this, we build the Devito image using the previously built base:
docker build . --file docker/Dockerfile.cpu --tag devito-gcc --build-arg arch=gcc
docker build . --file docker/Dockerfile.devito --tag devito_img --build-arg base=devito-gcc:latest
and then, to run tests or/and examples using the newly built image
docker run --rm --name testrun devito_img pytest -k "not adjoint" -m "not parallel" tests/
docker run --rm --name testrun devito_img py.test --nbval -k 'not dask' examples/seismic/tutorials/
Developing Devito with Docker
For those aiming to develop in Devito using Docker, you can use docker-compose. We start by cloning the repo and entering the Devito directory.
git clone https://github.com/devitocodes/devito.git
cd devito
Example CPU
# Start a terminal to develop/run for CPUs using docker compose
docker-compose run devito /bin/bash
Example GPU
# Start a terminal to develop/run for GPUs using docker compose
docker-compose run devito.nvidia /bin/bash
Virtual environment
venv route
Devito is available as a pip package
in PyPI.
Create a Python virtual environment
python3 -m venv <your_venv_name>
Source the newly created venv
. This needs to be repeated each time a new terminal is open.
source <your_venv_name>/bin/activate
To install the latest Devito release
along with any additional dependencies, follow:
pip install devito
# ...or to install additional dependencies:
# pip install devito[extras,mpi,nvidia,tests]
To install the latest Devito development version, without the tutorials, follow:
pip install git+https://github.com/devitocodes/devito.git
# ...or to install additional dependencies:
# pip install devito[tests,extras,mpi] @ git+https://github.com/devitocodes/devito@master
Additional dependencies:
- extras : optional dependencies for Jupyter notebooks, plotting, benchmarking
- tests : optional dependencies required for testing infrastructure
- mpi : optional dependencies for MPI (mpi4py)
- nvidia : optional dependencies for targetting GPU deployment
Note that here, you do not need to get the code via git clone
. Depending on your needs, this might also be the recommended setup for using Devito in a production-like environment. However, since some components need to be compiled before use, this approach may be sensitive to the C/C++ compilers present on your system and the related environment, including what other packages you might have installed.
conda route
Please install either Anaconda or Miniconda. Once install, you can create a virtual environment with eithera Python virtual environment or a Conda environment:
# Create new env with the name devito
conda create --name devito
# Activate the environment
conda activate devito
and finally, install Devito along with any extra dependencies:
pip install devito
# ... or to install additional dependencies
# pip install devito[extras,mpi,nvidia,tests]
For developers
First clone Devito:
git clone https://github.com/devitocodes/devito.git
cd devito
and then install the requirements in your virtual environment (venv or conda):
# Install requirements
pip install -e .
# ...or to install additional dependencies
# pip install -e .[extras,mpi,nvidia,tests]
Facing issues
If you are facing any issues, we are happy to help on Slack_. Also, have a look at our list of known installation issues or join us on Slack to interact with the developers and the community.