---

♟️ Quantum Chess

A Quantum-Inspired Stochastic Chess Simulation

Course: CSE 4550 – Simulation & Modeling

---

📌 Overview

Quantum Chess is a quantum-inspired, stochastic reimagining of classical chess designed to demonstrate key simulation and modeling concepts.

Unlike traditional chess—which is fully deterministic—this project introduces probability, uncertainty, and random state evolution. Pieces may exist in multiple possible positions simultaneously, and outcomes are resolved probabilistically when interactions occur.

⚠️ This project does not simulate real quantum mechanics. Instead, it uses quantum concepts as metaphors to build an intuitive and educational stochastic simulation system.

---

🎯 Motivation

Real-world systems are rarely deterministic. From network traffic to physical systems, uncertainty is the rule—not the exception.

This project demonstrates how:

• Uncertainty can be modeled computationally
• Multiple system states can coexist
• Probabilistic outcomes can be resolved through simulation
• Complex interactions can be handled using event-driven logic

Chess provides a familiar framework, allowing the focus to remain on modeling techniques rather than rules.

---

🧠 Core Concepts (Quantum-Inspired)

Superposition

A single chess piece can exist in multiple possible positions at once, each with an associated probability.

Simulation view: One piece → multiple state possibilities

Example:

• Knight at c5 → 50%
• Knight at d4 → 50%

---

Measurement (State Collapse)

When a capture or attack occurs, the probabilistic state collapses into a single definite outcome.

Simulation view: Uncertainty resolves when an observable event happens.

---

Entanglement

Two pieces can share a linked probabilistic state. Measuring or collapsing one piece immediately affects the other.

Simulation view: State dependency between entities, modeled using graphs.

---

Interference

Probabilities can reinforce or cancel each other when multiple paths lead to the same square.

Example:

• Bishop at b6 → 50%
• Bishop at g7 → 50%
• Both merge at d4 → 100%

---

🛠️ Simulation & Modeling Techniques Used

• Stochastic Simulation – probabilistic move resolution
• State Space Modeling – multiple board states
• Probability Distributions – piece position likelihoods
• Monte Carlo Methods – random collapse events
• Event-Driven Simulation – captures and attacks
• Graph Modeling – entanglement relationships

---

🤖 Bot & Simulation Flow (Short Code Overview)

The current simulation pipeline is implemented around the quantum engine, then wrapped by controllers and a match runner:

1. Legal actions are engine-generated The AI layer asks the engine for only legal regular, split, and merge actions via enumerate_legal_actions, so bots never bypass rule checks.

2. Bot lineup has been upgraded

   • Heuristic Bot (upgraded): stronger board scoring based on king survival pressure, expected material, mobility, tactical opportunities (captures/promotions), and quantum branch structure.
   • SplitMind Bot: depth-limited minimax (depth 2) in quantum state-space with expected-value leaf scoring and risk-aware blending against worst-case outcomes.
   • Random bot is deprecated/removed from the current bot-focused workflow.

3. Quantum outcomes are resolved by the engine Captures and uncertain paths are resolved probabilistically (Bernoulli sampling), with collapse and entanglement side effects handled inside the engine.

4. SplitMind decision pipeline (high level) The bot follows: legal action generation -> capped candidate ordering -> depth-2 search -> expected-value branch scoring -> final action selection under a move-time budget.

5. SimulationRunner executes and tracks full matches It seeds RNGs deterministically, advances turns, records each ply, and computes per-side analytics (action mix, capture stats, average legal actions, live branches, material swing, king-probability swing, decision time).

6. Match stop conditions are explicit A match ends on winner detection, no legal actions, threefold repetition, illegal action, or max full-move limit.

Quick CLI batch example:

python main.py --cli simulate --white heuristic_v1 --black <splitmind_controller_key> --games 20 --seed 42

Use the SplitMind key currently exposed by your controller catalog/CLI choices.

---

🧪 Technology Stack

Language

• Python 🐍

Libraries

• pygame – GUI & user interaction
• numpy – probability calculations
• random – stochastic events
• networkx – entanglement graphs
• matplotlib – probability visualization
• dataclasses – clean state modeling

Setup Instructions

Follow the steps below to set up Quantum Chess locally.

Prerequisites

• Python 3.10 or newer
• Git
• Internet connection (for installing dependencies)

1. Clone the Repository

git clone https://github.com/tashobi02/QuantumChess.git
cd QuantumChess

---

2. Create and Activate a Virtual Environment

On Linux / macOS

python3 -m venv venv
source venv/bin/activate

On Windows (PowerShell)

python -m venv venv
venv\Scripts\Activate.ps1

On Windows (Command Prompt)

python -m venv venv
venv\Scripts\activate

After activation, your terminal prompt should show (venv).

---

3. Upgrade pip

Keeping pip updated avoids many installation issues.

Linux / macOS

pip install --upgrade pip

Windows

python -m pip install --upgrade pip

---

4. Install Project Dependencies

pip install -r requirements.txt
pip install --upgrade pip

---

5. Run the Project

python main.py

A Pygame window should open, launching the Quantum Chess simulation.

6. Run Higher-Quality Bot Matches (Optional)

The project now exposes one gameplay bot mode (heuristic_v2) for simpler and more consistent matches.

Use the CLI to run automated matches with an explicit think-time budget:

python main.py --cli simulate --white heuristic_v2 --black heuristic_v2 --games 8 --move-time-limit-ms 250 --max-full-moves 80

Current controller guidance:

• heuristic_v2 is the public gameplay bot mode.
• heuristic_v2 evaluates moves using strict 2-ply maximin (best worst-case outcome).
• mcts_v1 remains in the codebase for separate testing/experiments.

For faster matches, lower the move budget:

python main.py --cli simulate --white heuristic_v2 --black heuristic_v2 --games 8 --move-time-limit-ms 120 --max-full-moves 80

---

This setup section is intentionally explicit because:

• virtual environments avoid version conflicts,
• Python behaves slightly differently across OSes,
• and instructors often copy steps verbatim.

📜 License

This project is for academic and educational purposes under CSE 4550.

---

Chess is deterministic. Reality isn’t. This project lives in that gap.