---
license: mit
tags:
- sudoku
- energy-based-model
- constraint-satisfaction
- pytorch
library_name: pytorch
---

# Kona Sudoku EBM

Energy-based Sudoku solver trained with contrastive learning on puzzle/solution pairs.

## Model

- **Architecture:** CNN + Transformer encoder energy head (`KonaEnergyModel`)
- **Weights:** `kona_ebm_best.pt`
- **Best epoch:** 9
- **Hidden dim:** 64, **Layers:** 2, **Heads:** 4

## Usage

Clone the solver code from [GitHub](https://github.com/Sph3inz/EBM-Sudoku-Solver) and download this checkpoint:

```powershell
pip install torch typer tqdm numpy huggingface_hub

hf download Sph3inxz/ebm-sudoku-solver kona_ebm_best.pt --local-dir checkpoints
```

Solve a puzzle:

```powershell
python -m kona_sudoku.main solve data/my_puzzle.txt `
  --checkpoint checkpoints/kona_ebm_best.pt `
  --device cuda `
  --max-steps 3000 `
  --langevin
```

## Inference settings

Recommended solver flags:
- `--max-steps 3000`
- `--langevin`
- `--lambda-learned 0.1`
- `--lambda-constraints 1.0`

## Training

Trained on `train_large.txt` with AdamW, contrastive EBM loss (margin=2.0), and MCMC negatives.