ParticleTransformer Student Project

Overview

This repository contains educational materials for learning about the ParticleTransformer model used in particle physics jet tagging.

Setup Instructions

Step 1: Download Required Files

Download the data files from CERNBox:

• Go to: https://cernbox.cern.ch/s/mj7eKKcO89c7jW4
• Download all ROOT files (.root files)
• Place them in the test_inference_results/ folder in this project

Step 2: Install Python Dependencies

Create a virtual environment (recommended):

# Create virtual environment
python -m venv student_env

# Activate virtual environment
# On Windows:
student_env\Scripts\activate
# On macOS/Linux:
source student_env/bin/activate

Install required packages:

Option 1: Use requirements.txt (recommended)

# Install all dependencies at once
pip install -r requirements.txt

Option 2: Install manually

# Install PyTorch (choose appropriate version for your system)
# For CPU only:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# For GPU support (if you have CUDA):
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Install other dependencies
pip install numpy matplotlib pandas scikit-learn jupyter notebook uproot

Step 3: Verify Installation

Test that everything works:

# Run the verification script
python verify_installation.py

# If all checks pass, start Jupyter
cd student_project
jupyter notebook

# Open notebooks/01_model_exploration.ipynb and run the first cell

Step 4: Start Learning

• Open notebooks/01_model_exploration.ipynb
• Follow the guided exercises
• Check solutions/ folder when you need help

What's Included

• 5 Interactive Notebooks with guided exercises
• Complete Solutions for all tasks
• Pre-trained Model (ParT_full.pt)
• Test Data (10 ROOT files with predictions)
• Utility Functions for data loading and visualization

Tasks

1. Model Exploration - Understand the basic architecture
2. Prediction Analysis - Analyze model performance
3. Attention Visualization - See what the model focuses on
4. Feature Importance - Understand which features matter most
5. Physics Insights - Discover physics patterns in the data

Requirements

• Python 3.8+
• PyTorch
• ROOT/uproot
• Jupyter Notebook
• Standard scientific Python stack (numpy, matplotlib, pandas, scikit-learn)

Data Files

File structure after download:

particle_transformer_student_project/
├── test_inference_results/          # ← Place downloaded files here
│   ├── HToBB_test_predictions.root
│   ├── HToCC_test_predictions.root
│   ├── ... (all 10 files)
│   └── ZToQQ_test_predictions.root
├── student_project/
│   ├── notebooks/                   # ← Start here
├── ParT_full.pt                     # ← Pre-trained model
└── example_ParticleTransformer.py   # ← Model architecture

Model

Happy learning! 🚀