Quantum Collider Sandbox

Real-Time GPU Particle Physics Simulation with PDG-accurate particle catalog. 40 observable particles, real masses, lifetimes, decay channels, and proper relativistic kinematics.

Documentation: https://ml3m.github.io/quantum-collider-sandbox/

Quick Start

Clone and run in four steps:

git clone https://github.com/ml3m/quantum-collider-sandbox.git
cd quantum-collider-sandbox
python -m venv .venv && source .venv/bin/activate   # Linux/macOS
make install && make run

On Windows, activate with .venv\Scripts\activate instead.

Requirements

System

• Python 3.10 to 3.12 (3.12.2 recommended)
• GPU with Vulkan support (NVIDIA, AMD, Intel)
• Vulkan drivers installed and working

Python dependencies (installed via make install):

• numpy ≥ 1.24
• scipy ≥ 1.10
• taichi ≥ 1.7.0
• h5py ≥ 3.8

Installation

1. Clone the repository

   git clone https://github.com/ml3m/quantum-collider-sandbox.git
   cd quantum-collider-sandbox

2. Create and activate a virtual environment (recommended)

   python -m venv .venv
   source .venv/bin/activate          # Linux / macOS
   # .venv\Scripts\activate           # Windows

3. Install the package in editable mode with dev tools

   make install

   Or manually:

   pip install -e ".[dev]"

4. Run the simulation

   make run

Makefile Targets

Target	Description
run	Start the particle physics simulation
install	Install package in editable mode with dev dependencies
lint	Run pylint on the source code
test	Run pytest test suite
test-cov	Run pytest with coverage report
format-check	Check code formatting (ruff + black)
format	Auto-fix formatting (ruff + black)
docs	Build Sphinx documentation (output in docs/build/)

Command-Line Usage

make run                              # Default demo
python -m quantum_collider_sandbox --particles 100    # Start with N random particles
python -m quantum_collider_sandbox --data event.h5    # Load from HDF5 file
python -m quantum_collider_sandbox --log-physics      # Log physics to data/logs/

Keyboard Controls

Key	Action
SPACE	Pause / Resume
R	Reset to selected preset (or default if none selected)
C	Spawn proton–antiproton collision
T	Toggle trails
F	Toggle collision flashes
Y	Toggle photon visibility
E	Export state and time series to HDF5
B	Toggle black hole
G	Toggle particle gun
TAB	Cycle inspector to next particle
P	Pin / freeze selected particle
1–9, 0	Presets (1=Default, 2=Rutherford, 3=Cyclotron, …, 0=N-body)
RMB	Orbit camera (drag)
Scroll	Zoom
ESC	Quit

Vulkan / GPU Troubleshooting

The simulation uses Taichi with the Vulkan backend. If you see Vulkan-related errors:

• NVIDIA: Install the latest proprietary drivers; Vulkan is usually included.
• AMD: Use Mesa (Linux) or AMD Adrenalin (Windows) with Vulkan support.
• Intel: Ensure Mesa or Intel drivers with Vulkan are installed.

Verify Vulkan with:

vulkaninfo

If Vulkan is unavailable, use the QUANTUM_COLLIDER_ARCH environment variable:

QUANTUM_COLLIDER_ARCH=cpu python -m quantum_collider_sandbox   # CPU fallback
QUANTUM_COLLIDER_ARCH=gpu python -m quantum_collider_sandbox    # Auto-detect GPU

Supported values: vulkan (default), cuda, cpu, gpu.

License

MIT License.