Installation#

How Do I Install Legate#

Legate is available from conda on the legate channel. Please make sure you have at least conda version 24.1 installed, then create a new environment containing Legate:

conda create -n myenv -c conda-forge -c legate legate

or install it into an existing environment:

conda install -c conda-forge -c legate legate

Packages with GPU support are available, and will be chosen automatically by conda install on systems with GPUs.

In an environment without GPUs available, conda install will by default choose a CPU-only package. To install a version with GPU support in such an environment, use environment variable CONDA_OVERRIDE_CUDA:

CONDA_OVERRIDE_CUDA="12.2" \
  conda install -c conda-forge -c legate legate

You will probably also want to install some downstream libraries built on top of Legate, e.g. cuPyNumeric:

conda install -c conda-forge -c legate cupynumeric

Support Matrix#

The following table lists Legate’s minimum supported versions of major dependencies.

“Full support” means that the corresponding versions (and all later ones) are being tested regularly, released as conda packages, and are expected to work. Please report any incompatibility you find against a fully-supported version by opening a bug.

“Best-effort support” means that the corresponding versions are not actively tested, but Legate should be compatible with them. We will not actively work to fix any incompatibilities discovered under these versions, but we accept contributions that fix such incompatibilities.

Support Matrix#

Dependency

Full support (min version)

Best-effort support (min version)

CPU architecture

x86-64 (Haswell), aarch64

older x86-64

OS

RHEL 8, Ubuntu 20.04

other Linux

GPU architecture

Volta

Pascal

CUDA toolkit

12.2

11.0

Python

3.10

NumPy

1.22

Legate is tested and guaranteed to be compatible with Volta and later GPU architectures. You can use Legate with Pascal GPUs as well, but there could be issues due to lack of independent thread scheduling. Please report any such issues by opening a bug.

Installation of the Legate MPI wrapper#

If you encounter runtime failures such as

failed to load MPI wrapper: 'some/path/to/liblegate_mpi_wrapper.so' ...

Or if you want to use Legate in combination with a different MPI library than the one it was compiled against (see the dependencies on the Legate package), e.g. you are on an HPC cluster and want to use the vendor’s MPI library, then you will need to compile and install the Legate MPI wrapper locally on your machine. See FAQ for more information on why this is needed.

Assume Legate is already installed in a conda environment named myenv. We need to activate this environment and install the wrapper packages that contain the scripts necessary to build the wrappers (note the custom channel legate/label/gex in the install command):

$ conda activate myenv
$ conda install -c conda-forge -c legate/label/gex legate-mpi-wrapper

When the wrapper package is installed, the instructions for building the wrapper are displayed:

To finish configuring the Legate MPI wrapper, activate your environment and run /path-to-myenv/mpi-wrapper/build-mpi-wrapper.sh

To build the wrapper, first activate the myenv environment:

$ conda activate myenv


--------------------- CONDA/MPI_WRAPPER/ACTIVATE.SH -----------------------

LEGATE_MPI_WRAPPER=

Note that when the environment is activated without the wrapper built, the activation script for the wrapper package sets the LEGATE_MPI_WRAPPER environment variable to an empty value, since there is no wrapper shared library to find yet.

After the environment is activated, we can build the MPI wrapper:

$ /path-to-myenv/mpi-wrapper/build-mpi-wrapper.sh

In order to build and install the wrapper you will need to have:

  • CMake (at least version 3.0).

  • A C++ compiler.

  • A local installation of MPI.

  • Write access to the conda environment.

You can specify a compiler to the build script using the -c option. Additionally, there are several environment variables that you can set in order to control the build and installation process:

  • CMAKE: name or path to the cmake executable.

  • CMAKE_ARGS or CMAKE_CONFIGURE_ARGS: if set, arguments to be passed to the initial CMake configure command. If both are set, CMAKE_CONFIGURE_ARGS is preferred over CMAKE_ARGS.

  • CMAKE_BUILD_ARGS: if set, arguments to be passed to the CMake build command.

  • CMAKE_INSTALL_ARGS: if set, arguments to be passed to the CMake install command.

Once the wrapper is built, reactivate the environment to set the necessary environment variables:

$ conda deactivate


--------------------- CONDA/MPI_WRAPPER/DEACTIVATE.SH -----------------------

+++ unset LEGATE_MPI_WRAPPER
+++ set +x
$ conda activate myenv


--------------------- CONDA/MPI_WRAPPER/ACTIVATE.SH -----------------------

LEGATE_MPI_WRAPPER=/path-to-myenv/mpi-wrapper/lib64/liblgcore_mpi_wrapper.so

Note that the activation script now successfully located the MPI wrapper shared library.

It might also be useful to remove the MPI conda package that Legate was compiled against (typically openmpi), to make sure that there is only one choice of MPI to use:

` conda uninstall --force openmpi `

Installation of the Legate IPython Kernel#

Please install Legate, then run the following command to install a default Jupyter kernel:

legate-jupyter

If installation is successful, you will see some output like the following:

Jupyter kernel spec Legate_SM_GPU (Legate_SM_GPU) has been installed

Legate_SM_GPU is the default kernel name.

Licenses#

This project will download and install additional third-party open source software projects at install time. Review the license terms of these open source projects before use.

For license information regarding projects bundled directly, see Third-party notices.