| --- |
| license: apache-2.0 |
| tags: |
| - sudoku |
| - reasoning |
| - curriculum |
| - jax |
| --- |
| |
| # Sudoku superposition instances |
|
|
| Concrete board assignments for a 12-stage Sudoku latent curriculum. |
| Each stage keeps a candidate set per cell; this dataset materializes |
| those sets as ordinary `(row, col, value)` sequences so training is |
| standard next-token cross-entropy (no multi-hot candidate head). |
|
|
| Repo: [Avra98/Sudoku_superposition](https://huggingface.co/Avra98/Sudoku_superposition) |
|
|
| ## Dataset |
|
|
| | split | puzzles | instances | mean / puzzle | |
| | --- | ---: | ---: | ---: | |
| | train | 1,804,462 | 89,236,838 | 49.45 | |
| | test | 99,999 | 4,945,532 | 49.46 | |
|
|
| Mean instances per stage (train, stage 0 → 11): |
| `6.28, 5.96, 5.65, 5.34, 5.02, 4.68, 4.32, 3.88, 3.33, 2.58, 1.41, 1.00` |
|
|
| Stage 11 is the unique solution. No empty `(puzzle, stage)` pair. |
|
|
| ### Files (`data/`) |
|
|
| | file | shape | dtype | role | |
| | --- | --- | --- | --- | |
| | `{split}_assignments.npy` | `(M, 81)` | uint8 | one full board per instance, cell `r*9+c` | |
| | `{split}_starts.npy` | `(N, 12)` | int32 | first row in `assignments` for `(puzzle, stage)` | |
| | `{split}_counts.npy` | `(N, 12)` | uint8 | number of instances for `(puzzle, stage)` | |
| | `{split}_index.npy` | `(M, 3)` | int32 | `[puzzle_idx, stage, k]` (optional; starts/counts are enough) | |
|
|
| The trainer only needs `assignments`, `starts`, and `counts`. |
|
|
| Puzzle clue/solution arrays are **not** in this repo (they are the |
| original Sudoku npy files). Candidate masks used to *build* the |
| instances live in `datasets_multicandidate_s12/`. |
|
|
| ### How a training example is built |
|
|
| 1. Take the usual solver-order sequence: clue triples, then K latent |
| placeholders, then empty-cell triples. |
| 2. Sample one instance for the current curriculum stage. |
| 3. Rewrite **values only**. Location order stays solver-order. |
| 4. Predict the output triples with softmax CE. Latent slots are not |
| predicted. |
|
|
| Curriculum stage `t` (1..12) trains on stage-`(t-1)` instances. |
| Stage 12 targets the unique solution. |
|
|
| ## Code (`code/`) |
|
|
| - `code/train/` — JAX trainer (`data.py`, `trainer.py`, `evaluater.py`, |
| `train_and_evaluate.py`, `train_backtrack.py`, `main.py`, `model.py`) |
| - `code/build_superposition_dataset.py` — instance generator |
| - `code/build_instance_offsets.py` — `starts` / `counts` tables |
| - `code/superposition_instances.py` — per-puzzle instance sampler |
| - `code/sbatch_instance_latent.sh` — Slurm launch (feanor / H200) |
|
|
| Set `SUDOKU_INSTANCE_DIR` to the `data/` folder (or a local copy). |
|
|
| ```bash |
| from huggingface_hub import snapshot_download |
| snapshot_download("Avra98/Sudoku_superposition", local_dir="Sudoku_superposition") |
| ``` |
|
|
