Add README.md

README.md

@@ -18,73 +18,33 @@ task_categories:
 
 # Breakthrough MCVS - Zone Guided AI
 
-**Advanced Monte-Carlo Value Search (MCVS)** engine for the game **Breakthrough** (8x8), powered by a novel **Displacement-based ABC Model** and **Weighted Adjacency Matrices** with **Hilbert-ordered Zone Guidance**.
+**Advanced Monte-Carlo Value Search (MCVS)** engine for the game **Breakthrough** (8x8), powered by a displacement-based **ABC Model** and **Weighted Adjacency Matrices** with **Hilbert-ordered Zone Guidance**.
 
-This repository implements a complete zone-guided reinforcement learning system, including self-play training, neural networks, and comparative tournaments against classic UCT.
+This implementation adapts the zone-guided MCVS framework to the simple but illustrative game Breakthrough, keeping the same neural architectures and zone-database design used by the chess reference implementation.
 
 ## Core Idea
 
 The engine uses:
-- Displacement-based ABC Model with homogeneous coordinates
-- Dynamic Weighted Adjacency Matrices `W = A ⊙ S ⊙ F`
-- Hilbert curve ordering for efficient zone retrieval
-- A learned **Zone Database** that stores winning/losing position patterns
-- **Zone Guidance** (`λ-PUCT`) to bias search toward promising zones
+- Displacement-based ABC Model with homogeneous coordinates to represent piece displacements succinctly
+- Dynamic Weighted Adjacency Matrices `W = A ⊙ S ⊙ F` representing spatial, adjacency and feature similarity
+- Hilbert curve ordering for efficient neighborhood (zone) lookup and compression
+- A learned **Zone Database** that stores winning/losing/drawing position-pattern matrices and provides a k-NN based zone score
+- **Zone Guidance** integrated into PUCT (`λ-PUCT`) to bias MCTS toward favorable zones
 
-For more information please refer to the paper at: https://doi.org/10.13140/RG.2.2.18795.09764
+The Breakthrough variant uses an internal 8×8 numpy board with lightweight move tuples `(fr, fc, tr, tc)`. Policy outputs are flattened 4096-length move logits (from-square * 64 + to-square), and the value net predicts game outcome in [-1,1].
 
 ## Files Overview
 
 | File                        | Purpose |
-|----------------------------|--------|
-| `breakthrough_mcvs.py`     | Main implementation: game logic, ABC model, Zone Database, MCVS, neural networks, incremental training |
-| `mcvs_vs_uct.py`           | 200-game tournament between MCVS and UCT with detailed logging and online learning |
-| `abc_model.py`             | Displacement-based ABC Model |
-| `matrix_model.py`          | Computes the weighted adjacency matrix |
+|----------------------------|---------|
+| `breakthrough_mcvs.py`     | Full MCVS implementation for Breakthrough: game logic, ABC/WeightedMatrix classes, Policy/Value CNNs, Zone DB, MCVS & UCT searchers, self-play and training loop. |
+| `breakthrough_zone_db.npz` | Zone database file: stores Hilbert-ordered matrices for winning, losing, and draw zones used by zone guidance. Created/updated by `breakthrough_mcvs.py`. |
 
 
-## Requirements
+## Notes
 
-## How to use:
-
-A. Incremental Training
-
-python breakthrough_mcvs.py
-
-This runs continuous self-play + training:
-
-1. Generates games using MCVS
-2. Trains the neural networks
-3. Updates and saves the Zone Database
-4. Fully incremental (you can stop and resume anytime)
-
-B. Tournament with Online Learning
-
-This script runs tournament games while the AI learns (NN or just zone guidance).
-
-# With Neural Networks (Full version – Online Learning):
-
-bash: python mcvs_vs_uct.py
-
-What happens:
-
-1. MCVS plays against classic UCT (alternating sides)
-2. Neural Policy and Value networks learn online after every game
-3. Zone Database is updated and saved after each game
-4. Zone guidance turns on automatically after game 1
-5. Creates detailed logs:
-6. breakthrough_full_results.txt — tournament summary
-7. move_log.txt — per-move statistics
-8. learning_log.txt — training progress
-
-# Without Neural Networks (Zone-only Ablation)
-To run the faster ablation version:
-
-1. Open mcvs_vs_uct.py
-2. Change this line near the bottom:
-
-ablation_no_nets=False   # ← Change to True
-
-```bash
-pip install torch numpy
+- The policy network maps a 1×64×64 weighted matrix tensor to a 4096-dimensional logits vector for flat move indexing.
+- The zone DB uses k-NN similarity (L1 normalized) across Hilbert-ordered matrices and returns a zone score Z ∈ [-1, 1].
+- `breakthrough_mcvs.py` includes a training loop that performs self-play data generation, incremental training, checkpointing (`breakthrough_checkpoint.pt`) and periodic MCVS vs UCT evaluation.
 
+For implementation details, inspect `breakthrough_mcvs.py`. If you want a shorter quick-start, ask me to add a minimal README usage section with run commands and environment notes.