quantum-collider-sandbox 1.1.0

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

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

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.