Setting Up Programming Environment

In order to run hands-on exercises in this course, you need Python and several dependencies.

  • If you use your own computer to run exercises, you should follow the instructions described below to install relevant packages and setup a specific programming environment before running hands-on exercises.

  • You can also use the Karolina supercomputer at IT4Innovations to run hands-on exercises. We also provide instructions for other HPC clusters (LUMI, Leonardo Booster) if you have access to them through your institution or HPC allocation.

Objectives

  • Install and configure Miniforge/conda for managing Python environments

  • Set up the python-for-hpc programming environment locally on different operating systems (Mac, Linux, Windows with WSL2)

  • Verify Python version and required package installations (numpy, scipy, pandas, matplotlib, cython, numba, dask, mpi4py)

  • Access and configure interactive sessions on HPC clusters (Karolina, LUMI, Leonardo Booster)

  • Submit and monitor batch and interactive jobs on HPC systems using SLURM

  • Configure Python kernel selection in VS Code for development

Instructor note

  • Time allocation: Allocate 30-45 minutes for this setup episode as environment configuration is critical for subsequent exercises

  • Pre-course checklist: Request participants complete setup before the course begins; provide troubleshooting support for environment issues

  • Alternative paths: Emphasize that participants can use their preferred Python management method (venv, pyenv, etc.) if they have existing workflows

  • WSL2 recommendation: For Windows users, strongly recommend WSL2 over native Windows installation due to MPI4PY compatibility and better HPC tool support

  • HPC access: Confirm in advance which participants will use local vs. HPC cluster resources; provide cluster-specific credentials and project IDs

  • Common issues: Be prepared to troubleshoot conda initialization, PATH configuration, and kernel selection in VS Code

  • Verification step: Consider having participants run a simple verification script to test all package imports and report back before the course starts

Local Installation

Install miniforge

If you already have a preferred way to manage Python versions and libraries, you can stick to that. If not, we recommend that you install Python3 and all libraries using Miniforge, a free minimal installer for the package, dependency and environment manager conda.

Please follow the installation instructions to install Miniforge.

Make sure that conda is correctly installed:

$ conda --version
conda 24.11.2

Install python programming environment on personal computer

For Mac users

With conda installed, install the required dependencies by running:

$ conda env create --yes -f https://raw.githubusercontent.com/ENCCS/hpda-python/main/content/env/environment.yml

This will create a new environment python-for-hpc which you need to activate by:

$ conda activate python-for-hpc

Ensure that the Python version is 3.13 or higher:

$ python --version
Python 3.13.x

Finally, open Jupyter Lab in your browser:

$ jupyter-lab

If you use VS Code, select the python-for-hpc kernel by clicking on “Select Kernel” in the upper right corner, choose “Python Environments”, and you will find the pre-installed python-for-hpc environment.

For Linux users

With conda installed, install the required dependencies by running:

$ conda env create --yes -f https://raw.githubusercontent.com/ENCCS/hpda-python/main/content/env/environment.yml

This will create a new environment python-for-hpc which you need to activate by:

$ conda activate python-for-hpc

Verify the Python version:

$ python --version
Python 3.13.x

Check that all required packages are installed:

$ python -c "import numpy, scipy, pandas, matplotlib, cython, numba, dask, mpi4py; print('All packages installed successfully')"

Launch Jupyter Lab:

$ jupyter-lab

For VS Code users, configure the python-for-hpc kernel by selecting “Python Environments” and choosing the pre-installed python-for-hpc environment.

For Windows users

We recommend using Windows Subsystem for Linux (WSL2) to get the best experience with Python HPC tools. First, install WSL2 and a Linux distribution (e.g., Ubuntu).

Once WSL2 is set up, follow the Linux installation instructions above within your WSL2 environment:

$ conda env create --yes -f https://raw.githubusercontent.com/ENCCS/hpda-python/main/content/env/environment.yml
$ conda activate python-for-hpc
$ python --version
$ jupyter-lab

Alternatively, if you prefer native Windows installation without WSL2:

  • Download and install Miniforge from https://conda-forge.org/download/

  • Open Anaconda Prompt (or Command Prompt)

  • Create the environment:

> conda env create --yes -f https://raw.githubusercontent.com/ENCCS/hpda-python/main/content/env/environment.yml
> conda activate python-for-hpc
> jupyter-lab

For VS Code on Windows, configure Python to use the python-for-hpc environment by installing the Python extension and selecting the environment as your kernel.

Note: Some HPC-specific tools (like MPI4PY) work best with WSL2 or a full Linux system. If you encounter issues with native Windows installation, consider using WSL2.

Using HPC Cluster

Karolina Supercomputer (Primary HPC Resource)

Login to Karolina cluster

To access the Karolina supercomputer at IT4Innovations, you will need credentials and proper SSH configuration. Contact your HPC administrator or visit the IT4Innovations website for access details.

Once you have credentials, connect via SSH:

$ ssh username@karolina.it4i.cz

For graphical interface access, you can use the Karolina web portal or configure SSH tunneling for remote applications.

Running jobs on Karolina cluster

If you want to run an interactive job on Karolina asking for 1 GPU node and 1 hour:

$ salloc -A <project_id> -N 1 -t 1:00:00 -p gpu --gpus=1

$ srun <some-command>

To run on CPU nodes:

$ salloc -A <project_id> -N 1 -t 1:00:00 -p cpu --cpus-per-task=16

Exit interactive allocation with exit.

You can also submit your job with a batch script submit.sh:

#!/bin/bash -l
#SBATCH --account=<project_id>
#SBATCH --job-name=python-hpc-job
#SBATCH --output=job.o%j
#SBATCH --error=job.e%j
#SBATCH --partition=gpu
#SBATCH --nodes=1
#SBATCH --gpus=1
#SBATCH --time=1:00:00

# Load Python module (if available)
module load Python

# Activate the python-for-hpc environment
conda activate python-for-hpc

# Run your Python script
python your_script.py

Some useful commands are listed below:

  • Submit the job: sbatch submit.sh

  • Monitor your job: squeue --me

  • Kill job: scancel <JOB_ID>

Using the python-for-hpc programming environment on Karolina

To use Python for HPC on Karolina, first SSH into the cluster and set up your environment:

$ ssh username@karolina.it4i.cz

$ module avail  # List available modules
$ module load Python  # Load Python module (version may vary)
$ module load GCC  # Load compiler for Cython/Numba
$ conda create -n python-for-hpc python=3.13 numpy scipy pandas matplotlib cython numba dask mpi4py jupyter

$ conda activate python-for-hpc

$ python --version
Python 3.13.x

$ jupyter --version

Alternatively, if a shared python-for-hpc environment is available on your system, you can activate it directly:

$ source /opt/python-for-hpc/bin/activate

Check with your HPC administrator for the exact path and availability.

If Karolina provides a web-based portal for interactive sessions (such as JupyterHub), you can access it through the web interface:

  1. Navigate to the Karolina portal URL (provided by your HPC administrator)

  2. Log in with your credentials

  3. Request an interactive session with:

    • Project: Your assigned project ID

    • Partition: gpu or cpu (depending on your needs)

    • Number of CPU cores: Recommend 2-4 for development

    • Time: 2-4 hours

    • Python environment: Select or create python-for-hpc

  4. Wait for the session to be allocated

  5. Connect to Jupyter and select the Python 3 (python-for-hpc) kernel

For SSH tunneling to Jupyter on a compute node:

$ ssh -L 8888:compute-node:8888 username@karolina.it4i.cz
$ # Then in your browser: localhost:8888

Alternative HPC Resources: LUMI and Leonardo Booster

For participants with access to other HPC clusters (e.g., through ENCCS or PRACE), the following instructions apply:

LUMI Supercomputer

Login to Leonardo Booster cluster

Follow instructions at HERE to get your access to Leonardo Booster cluster.

Running jobs on Leonardo Booster cluster

Leonardo Booster supports job submission through SLURM. Key steps:

  1. Load modules: Load Python and compiler modules:

$ module load python/3.13
$ module load gcc

  1. Create environment: Create a conda environment for the course:

$ conda create -n python-for-hpc python=3.13 numpy scipy pandas matplotlib cython numba dask mpi4py jupyter
$ conda activate python-for-hpc

  1. Submit interactive job:

$ salloc -A <project_id> -N 1 -t 2:00:00 --gpus=1 -p booster

  1. Submit batch job: Create a submit script similar to Karolina’s format and use sbatch submit.sh

  2. Monitor jobs: Use squeue --me to check job status and scancel <JOB_ID> to cancel jobs

Using the python-for-hpc programming environment on Leonardo Booster

To set up the environment on Leonardo Booster:

  1. Login and load modules:

$ ssh username@leonardo.cilea.it
$ module load python/3.13
$ module load gcc/12.2.0

  1. Create conda environment:

$ conda create -n python-for-hpc python=3.13 numpy scipy pandas matplotlib cython numba dask mpi4py jupyter
$ conda activate python-for-hpc

  1. Verify installation:

$ python --version
$ python -c "import numpy, dask, mpi4py; print('All packages imported successfully')"

  1. Use in batch scripts: Add the following to your SLURM batch script:

module load python/3.13
module load gcc/12.2.0
conda activate python-for-hpc
python your_script.py

For more information, visit the Leonardo Booster documentation

Conclusion

Keypoints

  • Miniforge/conda is the recommended environment manager for managing Python versions and HPC-related dependencies

  • Python 3.13 or higher is required for this course

  • Windows users should use WSL2 for better compatibility with HPC tools, especially MPI4PY

  • The python-for-hpc environment must be activated before running exercises

  • HPC clusters use SLURM job scheduler; interactive jobs with salloc and batch jobs with sbatch are the primary submission methods

  • VS Code users can select the python-for-hpc kernel via “Python Environments” after configuration

  • SSH tunneling can be used for remote Jupyter access on HPC clusters

  • Different HPC systems (Karolina, LUMI, Leonardo) have similar but slightly different module and partition names; cluster-specific documentation should be consulted