Installation & Setup

Detailed installation instructions and troubleshooting.

System Requirements

Hardware

  • GPU: NVIDIA, AMD, or Intel with Vulkan support (4GB+ VRAM recommended)

  • CPU: Multi-core processor (4+ cores)

  • RAM: 8GB+ (16GB+ for 2k+ particles)

  • Disk: 500MB for installation

Software

  • Python: 3.10, 3.11, or 3.12 (3.12.2 recommended)

  • OS: Linux, Windows 10/11, macOS 12+

  • Vulkan drivers: Must be installed and working

Step-by-Step Installation

1. Clone the repository

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

2. Create virtual environment

Linux / macOS:

python3.12 -m venv .venv
source .venv/bin/activate

Windows:

py -3.12 -m venv .venv
.venv\Scripts\activate

3. Install dependencies

make install

Or manually:

pip install --upgrade pip setuptools wheel
pip install -e ".[dev]"
This installs:

  • taichi ≥ 1.7.0 (GPU framework)

  • numpy, scipy (numerical computing)

  • h5py (HDF5 I/O)

  • pygame (events, optional)

  • pre-commit (CI/CD hooks)

4. Verify installation

make test
Expected output:

  • 27 tests pass

  • Execution time ~0.6s

  • No errors

5. Run

make run

Or directly:

python -m quantum_collider_sandbox

Development Setup

For contributing to the codebase:

# Install with dev tools
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run linting
make lint

# Run tests
make test

# Build docs
make docs

Taichi Backend Configuration

By default, Taichi uses Vulkan. To use a different backend:

CUDA (NVIDIA GPUs):

export TAICHI_BACKEND=cuda
python -m quantum_collider_sandbox

CPU (for debugging):

export TAICHI_BACKEND=cpu
python -m quantum_collider_sandbox

Metal (macOS, if available):

export TAICHI_BACKEND=metal
python -m quantum_collider_sandbox

Makefile Targets

Target

Description

make run

Start the simulation (main entry point)

make install

Install package in editable mode with dev dependencies

make test

Run pytest (27 physics & logic tests)

make lint

Run pylint, ruff, black (code quality)

make docs

Build Sphinx documentation

make prod-ready

Run all checks: lint, test, docs (pre-commit)

make clean

Remove build artifacts and cache

Troubleshooting

“No GPU detected”

If Taichi cannot find your GPU:

  1. Check your GPU drivers:

    glxinfo | grep "OpenGL driver"

  2. Verify Vulkan support:

    vulkaninfo

  3. Force CPU backend for testing:

    export TAICHI_BACKEND=cpu
python -m quantum_collider_sandbox

“ImportError: cannot import taichi”

Reinitialize your virtual environment:

rm -rf .venv
python -m venv .venv
source .venv/bin/activate
make install

“FPS is very low (< 1 FPS)”

See Performance Tuning section. Common causes:

  • TRAIL_LENGTH too high (reduce from 40 to 5-10)

  • Too many particles for your GPU

  • Rendering resolution too high (reduce WINDOW_WIDTH/HEIGHT)

“Particles not rendering”

  1. Try resetting view: R key

  2. Check particle count slider (ImGui left panel)

  3. Rotate camera: right-mouse drag

  4. Verify GPU backend is working: check console for errors

Getting Help