Qubit & Crit — Quantum D20 Roller

A webapp that uses real IBM Quantum hardware to generate truly random dice rolls via quantum measurement. Roll a d20 (or other dice) where the result is decided by qubits in superposition — not a pseudo-random number generator.

Two modes:

• Simulator — fast local rolls via Qiskit's AerSimulator. Genuinely quantum-algorithm-based, returns in ~50ms.
• Quantum Hardware — ceremonial rolls submitted to IBM Quantum backends. Save these for death saves and final-boss moments.

The raw bit string is the universe deciding. Print it. Frame it.

---

Stack

Layer	Tech
Backend	Python / FastAPI
Quantum	Qiskit + IBM Quantum (qiskit-ibm-runtime)
Frontend	React + TypeScript + Vite
Styling	Tailwind CSS
3D	React Three Fiber
Container	Docker (single compose file)

---

How it works

A 5-qubit circuit is put into superposition with Hadamard gates, then all qubits are measured. The 5-bit result (0–31) is rejection sampled to fit the die — for a d20, values above 20 trigger a re-roll (~37% of the time). For larger dice the circuit widens (e.g. d100 uses 7 qubits / 128 values, rejecting > 100).

Each roll exposes its raw quantum data: the measured bit string (e.g. 10110), its decimal value before resampling, whether a resample occurred, the backend used, and — for hardware rolls — the IBM job ID.

---

Project Structure

qubit-and-crit/
├── backend/
│   ├── main.py            # FastAPI app + endpoints
│   ├── quantum.py         # Qiskit logic (simulator + real hardware)
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── App.tsx
│   │   ├── api.ts
│   │   └── components/
│   │       ├── DiceRoller.tsx
│   │       ├── D20Scene.tsx     # 3D die
│   │       ├── QubitDisplay.tsx # raw measurement readout
│   │       └── RollHistory.tsx
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml
└── .env.example

---

Getting Started

1. IBM Quantum credentials (required for hardware mode)

1. Create an account at quantum.cloud.ibm.com.

2. Grab your API token (Account → API keys) and your instance CRN (instance → Details → CRN).

3. Copy the example env file and fill it in:

   cd qubit-and-crit
   cp .env.example .env
   # edit .env: IBMQ_API_TOKEN, IBMQ_CHANNEL, IBMQ_INSTANCE

The free tier includes access to real hardware plus monthly primitive units. .env is gitignored — never commit your token. Simulator mode works without any credentials.

2. Run with Docker (recommended)

cd qubit-and-crit
docker compose up --build

• Frontend → http://localhost:8098
• Backend API → http://localhost:8097

3. Run locally for development

Backend:

cd qubit-and-crit/backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Frontend:

cd qubit-and-crit/frontend
npm install
npm run dev

---

API

Method	Endpoint	Description
GET	/health	Health check
POST	/roll	Roll a die. Body: { "sides": 20, "mode": "simulator" | "quantum" }
GET	/roll/status/{job_id}	Poll a pending quantum hardware job
GET	/backends	List available IBM backends + queue times

/roll response:

{
  "result": 17,
  "raw_bits": "10110",
  "decimal_raw": 22,
  "resampled": true,
  "mode": "quantum",
  "backend": "ibm_brisbane",
  "job_id": "abc123"
}

---

License

Personal project — Codename Qubit & Crit, built for Thursday Commander Night.