Install

Prerequisites

  • Python: >= 3.11

  • Compiler: gcc or nvcc

  • CMake: >= 3.15

  • Runtime: NVIDIA Drivers, CUDA, CuPy

Environment setup

We strongly recommend using a virtual environment (e.g., mamba or conda):

mamba create -n simenv python=3.13
mamba activate simenv

Install via PyPI

If you have the prerequisites installed, you can install the latest release directly:

pip install iactsim -v

Optional: using NVHPC compilers

Building with gcc is the standard and requires no special configuration. However, if you specifically wish to use the nvcc, you must configure the environment before installation.

Please refer to the NVIDIA HPC SDK section in Runtime configuration for detailed instructions on setting up the environment.

Custom Compiler Flags

You can customize the build options by passing arguments to CMake via pip. The following flags are available:

  • CMAKE_CXX_COMPILER=<compiler>: specify the C++ compiler executable (e.g., nvcc, g++).

  • USE_ZLIBNG=<ON|OFF>: enable/disable zlib-ng support. Default is ON. For the C++ part, by default zlib-ng (zlib data compression library for the next generation systems) will be used (CMake will clone the repo automatically). This is strongly recommended if you plan to read gzipped CORSIKA files. If you have to use the standard system zlib, you can set this to OFF.

Example: explicitly use nvcc and disable zlib-ng

python -m pip install iactsim -v -C cmake.args="-DCMAKE_CXX_COMPILER=nvcc;-DUSE_ZLIBNG=OFF"

Install from source

  1. Clone the repository:

    git clone https://gitlab.com/davide.mollica/iactsim.git
cd iactsim

  2. Editable install: First, install the build dependencies required for the editable install:

    pip install scikit-build-core pybind11 "setuptools_scm[toml]>=8.0" cmake ninja

    Then, install the package in editable mode. This configuration disables build isolation, ensuring that only modified C++ files will be recompiled:

    python -m pip install --no-build-isolation -e .

Runtime configuration

1. Install CuPy (required)

iactsim relies on CuPy for GPU offloading. You must install the cupy package that matches your specific CUDA version.

pip install cupy-cuda<XXX>

Replace <XXX> with your CUDA version (e.g., cupy-cuda12x for CUDA 12). For detailed instructions, refer to the CuPy documentation.

2. Configure CUDA environment

To ensure the custom kernels compile successfully, NVCC and CUDA_PATH must be set correctly. We provide helper scripts to automate this for conda/mamba environments.

Case 1: NVIDIA HPC SDK

If you are using the NVIDIA HPC SDK to provide CUDA libraries, you must configure the enviroment so that CuPy can locate the necessary libraries (you can download HPC SDK from the NVIDIA website).

We suggest to use Environment Modules to handle SDK configuration and then define NVCC and CUDA_PATH enviromental variables:

module load nvhpc
export NVCC=$NVHPC_ROOT/compilers/bin/nvcc
export CUDA_PATH=$NVHPC_ROOT/cuda

With conda/mamba enviroments you can use the provided configuration script configure_conda_env_hpcsdk:

mamba activate simenv
configure_conda_env_hpcsdk simenv
mamba deactivate

This adds an activation script and a deactivation script to the simenv enviroment that will automatically handle the configuration when it is activated or deactivated.

Case 2: CUDA toolkit (conda-forge/nvidia)

If you prefer a self-contained environment without external modules, you can install the CUDA Toolkit via mamba:

mamba install -c nvidia cuda-toolkit

and then configure the environment variables NVCC and CUDA_PATH. You can use the provided configuration script configure_conda_env_cudatoolkit:

mamba activate simenv
configure_conda_env_cudatoolkit simenv
mamba deactivate