Quick Start Guide

Get the simulation running in minutes.

Installation (60 seconds)

Linux / macOS:

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

Windows:

git clone https://github.com/ml3m/quantum-collider-sandbox.git
cd quantum-collider-sandbox
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
python -m quantum_collider_sandbox

First Run

When you start the simulation:

  1. Wait for initialization (~3-5 seconds) - Taichi loads (first-time JIT compilation) - GPU buffers allocate

  2. You should see: - 3D particle visualization in center - ImGui control panels on left - Status bar showing particle count, FPS, energy

  3. Try these keys immediately: - SPACE — Play/pause simulation - R — Reset (spawn default particles) - T — Toggle particle trails - Mouse scroll — Zoom camera - Right-mouse drag — Rotate view

Common First Steps

Spawn more particles:

  1. Use ImGui “# Particles” slider on left panel (0-100)

  2. Or press + / - keys to increment

Change simulation preset:

  1. Click “Presets” dropdown in ImGui panel

  2. Select one: Rutherford, Cyclotron, LHC pp, e⁺e⁻ annihilation, etc.

Turn off trails:

  1. Press T key to toggle trails (saves FPS)

  2. Or disable in ImGui “Trails” checkbox

Adjust physics constants (real-time):

  1. Find sliders: Coulomb K, Gravity G, Magnetic B, etc.

  2. Drag to tune forces

Export data:

  1. Press Ctrl+S to save current state as HDF5

  2. Press Ctrl+Shift+J to export physics events as JSONL

Control Reference (Quick)

Next Steps

See full documentation:

  • Advanced Controls → Controls Reference

  • Configuration → Tuning Parameters

  • Presets Explained → Built-in Presets

  • Physics Model → Physics Background

  • Performance Tuning → Optimization Guide

  • API → Python API Reference