User Installation (for Non-Developers)

This guide provides step-by-step instructions for installing the itwinai library for users.

Requirements: Linux or macOS environment. Windows is not supported.

Creating a Virtual Environment

While not mandatory, creating a virtual environment is highly recommended to isolate dependencies and prevent conflicts with other Python projects.

Warning

On high-performance computing (HPC) systems, you must load the appropriate modules before activating your virtual environment to ensure compatibility with system libraries. See the dropdown below for detailed instructions:

HPC Systems

On HPC systems, it is common to manage dependencies using Environment Modules or Lmod. These tools allow you to dynamically load and unload software environments. If you are unsure which modules to load for your application, contact your system administrator or refer to your HPC system’s documentation for specific guidance.

For Juelich Supercomputer (JSC) and Vega Supercomputer, these are the modules you should load, depending on whether you want PyTorch or TensorFlow support:

PyTorch

For JSC:

ml --force purge
ml Stages/2024 GCC OpenMPI CUDA/12 cuDNN MPI-settings/CUDA
ml Python CMake HDF5 PnetCDF libaio mpi4py

For Vega:

ml --force purge
ml Python/3.11.5-GCCcore-13.2.0 CMake/3.24.3-GCCcore-11.3.0 mpi4py OpenMPI CUDA/12.3
ml GCCcore/11.3.0 NCCL cuDNN/8.9.7.29-CUDA-12.3.0 UCX-CUDA/1.15.0-GCCcore-13.2.0-CUDA-12.3.0

TensorFlow

For JSC:

ml --force purge
ml Stages/2024 GCC/12.3.0 OpenMPI CUDA/12 MPI-settings/CUDA
ml Python/3.11 HDF5 PnetCDF libaio mpi4py CMake cuDNN/8.9.5.29-CUDA-12

For Vega:

ml --force purge
ml Python/3.11.5-GCCcore-13.2.0 CMake/3.24.3-GCCcore-11.3.0 mpi4py OpenMPI CUDA/12.3
ml GCCcore/11.3.0 NCCL cuDNN/8.9.7.29-CUDA-12.3.0 UCX-CUDA/1.15.0-GCCcore-13.2.0-CUDA-12.3.0

If you don’t already have a virtual environment, you can create one with the following command:

python -m venv <name-of-venv>

Remember to replace <name-of-venv> with the name you want for your virtual environment. Now, you can start your virtual environment with the following command:

source <name-of-venv>/bin/activate

Installing the itwinai Library

You can choose if you want to install itwinai with support for either PyTorch or TensorFlow by using extras:

PyTorch

To install itwinai with PyTorch without GPU acceleration, you can use the following command:

pip install "itwinai[torch]"

To enable GPU acceleration, you can use the following command:

pip install ".[torch]" \
    --extra-index-url https://download.pytorch.org/whl/cu121

TensorFlow

To install itwinai with TensorFlow without GPU acceleration, you can use the following command:

pip install "itwinai[tf]"

To enable GPU acceleration, you can use the following command:

pip install ".[tf-cuda]"

Note

If you want to use the Prov4ML logger, you need to install it explicitly since it is only available on GitHub:

For systems with Nvidia GPUs:

pip install "prov4ml[nvidia]@git+https://github.com/matbun/ProvML@new-main"

For macOS:

pip install "prov4ml[apple]@git+https://github.com/matbun/ProvML@new-main"

Installing Horovod and Microsoft DeepSpeed

If you also want to install Horovod and Microsoft DeepSpeed for distributed ML with PyTorch, then make sure to install them after itwinai. You can choose if you want to do this with or without GPU (CUDA) support:

CPU

pip install --no-cache-dir --no-build-isolation git+https://github.com/horovod/horovod.git
pip install --no-cache-dir --no-build-isolation deepspeed

CUDA

curl -fsSL https://github.com/interTwin-eu/itwinai/raw/main/env-files/torch/install-horovod-deepspeed-cuda.sh | bash

Warning

Horovod requires CMake>=1.13 and other packages Make sure to have them installed in your environment before proceeding.