puzzlekit

Puzzle Kit

This repository provides 100+ useful, efficient and problem‑specific solvers for a variety of logic puzzles. The underlying solving engine is the open‑source Google OR-Tools CP-SAT solver. For more details of puzzles and their input format, you can refer to docs of puzzlekit.

For simplicity, the dataset is removed to puzzlekit-dataset repo. The structured dataset contains 41k+ instances covering 130+ specific and popular puzzle types (e.g. Nonogram, Slitherlink, Akari, Fillomino, Hitori, Kakuro, Kakuro), mostly from Raetsel’s Janko and puzz.link. The details are listed in the table below.

This repo also provides bidirectional conversion between puzz.link and Penpa+ puzzle URLs for supported genres (19 for now) via a shared intermediate representation. puzz.link-like links from common mirrors (e.g., pzplus.tck.mn, pzv.jp) are also accepted.

Table of puzzles, datasets and solvers.

#.P and #.S indicate the number of puzzles and solutions of specific puzzle type respectively.

Max Size shows the maximum scale of collected puzzles.

Sol? shows if the solver has been implemented currently.

Avg T and Max T indicates the average / maximum time required to solve one puzzle grid among all instances (in seconds).

#.V shows the number of verified solutions compared with the expected solutions. Note that some of solutions failed this mainly because of additional yet unpopular constraints (like diagnonal-ABCEndView, which is a bit rare), or different variants of puzzles(like different shapes of 6x6 Jigsaw Sudoku and Bricks puzzle).

No.	Puzzle Name	#.P	#.S	Max Size	Sol?	Avg T(s)	Max T(s)	#.V
1	ABCEndView	607	607	8x8	✅	0.014	0.042	591
2	Akari	970	970	100x100	✅	0.014	0.479	970
3	Aqre	90	90	17x17	✅	0.122	2.387	90
4	Araf	120	120	10x18	❌	-	-	-
5	BalanceLoop	70	70	17x17	✅	0.062	0.218	70
6	Battleship	861	860	30x30	✅	0.103	1.748	860
7	Binairo	380	380	14x14	✅	0.007	0.015	380
8	Bosanowa	38	38	11x16	✅	0.015	0.178	38
9	Bricks	210	210	8x8	✅	0.004	0.013	190
10	Buraitoraito	101	100	15x15	✅	0.007	0.159	100
11	Burokku	270	270	10x10	❌	-	-	-
12	ButterflySudoku	77	77	12x12	✅	0.008	0.011	77
13	CanalView	110	110	17x17	✅	0.120	1.157	110
14	CastleWall	110	110	50x50	✅	0.058	1.184	110
15	Cave	419	419	25x25	✅	0.211	11.318	419
16	Chocona	250	250	17x17	❌	-	-	-
17	Clueless1Sudoku	29	29	27x27	✅	0.029	0.042	29
18	Clueless2Sudoku	40	40	27x27	✅	0.035	0.083	40
19	CocktailLamp	50	50	17x17	❌	-	-	-
20	Cojun	120	120	17x17	✅	0.007	0.073	120
21	ConsecutiveSudoku	211	211	9x9	❌	-	-	-
22	CountryRoad	270	270	15x15	✅	0.029	0.128	270
23	Creek	440	440	40x50	✅	0.389	13.115	440
24	CurvingRoad	190	190	14x14	❌	-	-	-
25	Detour	80	80	13x12	✅	0.023	0.184	80
26	DiffNeighbors	140	140	15x15	✅	0.015	0.027	140
27	DigitalBattleship	80	80	12x12	❌	-	-	-
28	Dominos	582	581	41x42	✅	0.006	1.224	580
29	Doors	270	270	12x12	❌	-	-	-
30	DoppelBlock	240	240	8x8	❌	-	-	-
31	DotchiLoop	60	60	17x17	✅	0.038	0.089	60
32	DoubleBack	100	100	26x26	✅	0.026	0.241	100
33	EntryExit	170	170	16x16	✅	0.039	0.095	170
34	Eulero	290	290	5x5	✅	0.004	0.007	290
35	EvenOddSudoku	129	129	9x9	✅	0.004	0.005	129
36	Factors	150	150	11x11	❌	-	-	-
37	Fillomino	840	840	50x64	❌	-	-	-
38	Fobidoshi	250	250	12x12	✅	0.056	0.150	250
39	Foseruzu	310	310	30x45	❌	-	-	-
40	Fuzuli	160	160	8x8	✅	0.010	0.018	160
41	Galaxies	580	580	20x36	❌	-	-	-
42	Gappy	429	427	18x18	✅	0.019	0.062	427
43	Gattai8Sudoku	120	120	21x33	✅	0.021	0.032	120
44	Geradeweg	100	100	14x14	✅	0.050	0.157	100
45	GokigenNaname	780	780	24x36	❌	-	-	-
46	GrandTour	350	350	15x15	✅	0.020	0.070	350
47	Hakoiri	140	140	12x12	✅	0.098	0.263	140
48	Hakyuu	480	480	30x45	✅	0.042	0.801	480
49	Hanare	107	107	16x16	❌	-	-	-
50	Hashi	910	910	40x60	❌	-	-	-
51	Heyawake	787	787	31x45	✅	0.139	4.756	786
52	Hidoku	510	510	10x10	✅	0.026	0.140	510
53	Hitori	941	941	25x25	✅	0.010	1.017	941
54	JigsawSudoku	680	680	9x9	✅	0.003	0.007	665
55	Juosan	80	80	30x45	✅	0.011	0.075	80
56	Kakkuru	400	400	9x9	✅	0.003	0.016	389
57	Kakurasu	280	280	11x11	✅	0.003	0.005	280
58	Kakuro	999	999	31x46	✅	0.011	0.200	999
59	KenKen	430	430	9x9	✅	0.005	0.135	430
60	KillerSudoku	810	810	9x9	✅	0.006	0.119	584
61	Koburin	150	150	12x12	✅	0.020	0.041	150
62	Kuromasu	560	560	31x45	✅	0.070	4.359	560
63	Kuroshuto	210	210	14x14	✅	0.145	0.806	210
64	Kurotto	230	230	19x27	✅	0.853	16.754	227
65	LITS	419	410	40x57	✅	0.619	40.630	410
66	Linesweeper	310	310	16x16	✅	0.017	0.045	310
67	Magnetic	439	439	12x12	✅	0.010	0.025	439
68	Makaro	190	190	15x15	✅	0.007	0.010	190
69	MarginSudoku	149	149	9x9	❌	-	-	-
70	Masyu	830	828	40x58	✅	0.066	0.790	828
71	Mathrax	175	175	9x9	✅	0.004	0.014	175
73	Mejilink	1	0	8x8	✅	0.012	0.012	0
74	MidLoop	2	2	10x10	✅	0.014	0.025	2
75	Minesweeper	360	360	14x24	✅	0.005	0.023	360
76	MoonSun	200	200	30x45	✅	0.041	0.304	200
77	Mosaic	165	104	118x100	✅	0.015	0.133	104
78	Munraito	360	360	12x12	✅	0.010	0.025	360
79	Nanbaboru	270	270	9x9	❌	-	-	-
80	Nanro	159	159	14x14	✅	0.138	0.406	159
81	Nawabari	160	160	14x14	✅	0.020	0.039	160
82	Nondango	110	110	14x14	✅	0.004	0.009	110
83	Nonogram	2338	2337	30x40	✅	0.300	1.494	2337
84	Norinori	289	289	36x54	✅	0.008	0.082	288
85	NumberCross	170	170	8x8	✅	0.003	0.006	170
86	NumberLink	580	580	35x48	❌	-	-	-
87	NumberSnake	70	70	10x10	❌	-	-	-
88	Nurikabe	1130	1130	50x50	❌	-	-	-
89	Nurimisaki	100	100	10x10	✅	0.059	0.114	100
90	OneToX	58	58	10x10	✅	0.011	0.075	58
91	PaintArea	226	226	12x12	✅	0.064	2.336	226
92	Patchwork	211	211	12x12	✅	0.020	0.033	211
93	Pfeilzahlen	360	359	10x10	✅	0.011	0.021	358
94	Pills	164	163	10x10	✅	0.007	0.008	163
95	Pipeline	349	349	20x20	❌	-	-	-
96	Pipelink	190	190	30x45	❌	-	-	-
97	Pipes	2	2	60x40	✅	0.384	0.959	2
100	Putteria	60	60	16x16	✅	0.025	0.056	60
101	RegionalYajilin	70	70	10x18	✅	0.021	0.058	70
102	Rekuto	220	220	14x14	❌	-	-	-
103	Renban	150	150	9x9	✅	0.005	0.059	150
104	SamuraiSudoku	272	272	21x21	✅	0.011	0.022	272
105	Shakashaka	369	369	22x30	❌	-	-	-
106	Shikaku	501	501	50x40	✅	0.010	0.078	498
107	Shimaguni	266	266	30x45	✅	0.032	0.537	266
108	Shingoki	103	103	41x41	✅	0.082	1.204	103
109	Shirokuro	110	110	17x17	✅	0.006	0.008	110
110	ShogunSudoku	90	90	21x45	✅	0.030	0.048	90
111	Shugaku	130	130	30x45	✅	0.665	9.848	130
112	SimpleLoop	70	70	17x18	✅	0.020	0.056	70
113	Skyscraper	470	470	8x8	✅	0.015	0.077	470
114	SkyscraperSudoku	50	50	9x9	❌	-	-	-
115	Slitherlink	1176	1152	60x60	✅	0.067	1.850	1149
116	Snake	230	230	12x12	✅	0.062	0.216	230
117	SoheiSudoku	120	120	21x21	✅	0.010	0.014	120
118	SquareO	120	80	15x15	✅	0.004	0.007	80
119	Starbattle	309	308	25x25	✅	0.009	0.046	308
120	Sternenhimmel	188	188	17x17	❌	-	-	-
121	Stitches	110	110	15x15	✅	0.005	0.013	110
122	Str8t	560	560	9x9	✅	0.004	0.008	560
123	Sudoku	125	125	16x16	✅	0.010	0.019	125
124	Suguru	200	200	10x10	✅	0.008	0.013	200
125	Sukoro	140	140	12x12	❌	-	-	-
126	SumoSudoku	110	110	33x33	✅	0.032	0.046	110
127	Tatamibari	150	150	14x14	✅	0.021	0.051	150
128	TennerGrid	375	374	6x10	✅	0.007	0.010	374
129	Tent	706	706	30x30	✅	0.006	0.026	706
130	TerraX	80	80	17x17	✅	0.009	0.018	80
131	Thermometer	250	250	10x10	✅	0.003	0.006	250
132	TilePaint	377	377	16x16	✅	0.004	0.086	377
133	Trinairo	60	60	12x12	✅	0.018	0.046	60
134	Tripletts	190	190	10x12	❌	-	-	-
135	Usoone	130	130	30x45	✅	0.031	0.430	130
136	WindmillSudoku	150	150	21x21	✅	0.012	0.034	150
137	Yajikabe	100	100	17x17	✅	0.115	0.492	100
138	Yajilin	610	610	39x57	✅	0.052	0.512	610
139	YinYang	170	170	14x14	✅	0.316	1.897	170
140	Yonmasu	120	120	10x10	❌	-	-	-
	Total	41270	41123	-	-	-	-	-

Supported puzzle types for URL interchange

(canonical IR name, puzz.link token, aliases, Penpa genre tag)

Canonical (IR)	puzz.link token	puzz.link aliases	Penpa genre tag
aqre	aqre	aqre	aqre
ayeheya	ayeheya	ayeheya	ayeheya (ekawayeh)
castle	castle	castle	castlewall
country	country	country	country road
hebi	hebi	hebi, snakes	hebi-ichigo
heyawake	heyawake	heyawake, heyawacky, heyawack	heyawake
kurochute	kurochute	kurochute, kuroshuto, kurochuto	kurochute
kurodoko	kurodoko	kurodoko	kurodoko
kurotto	kurotto	kurotto	kurotto
masyu	masyu	masyu, mashu, pearl	masyu
moonsun	moonsun	moonsun	moon or sun
nonogram	nonogram	nonogram	nonogram
nurikabe	nurikabe	nurikabe	nurikabe
nurimisaki	nurimisaki	nurimisaki	nurimisaki
shikaku	shikaku	shikaku	shikaku
shimaguni	shimaguni	shimaguni	shimaguni (islands)
slitherlink	slither	slitherlink	slitherlink
stostone	stostone	stostone	stostone
yajilin	yajilin	yajilin, yajirin	yajilin

Gallery of some puzzles (not complete!)

Related Projects & Online Play

If you are looking for online playing or a browser-based solver with excellent performance, here are some fantastic alternatives:

• Noqx 🎉, with interactive penpa-edit style web interface: An enhanced and more-efficient logic puzzle solver based on Clingo (Answer Set Program (ASP) solver) and WASM. It supports 170+ puzzle types, covering most of this repo with same or even better efficiency compared with this repo. It’s highly recommend to give it a try.
• nikoli-puzzle-solver (Z3): Another SAT-based solver with interactive penpa-style web page via z3 solver for 100+ puzzle types. It supports more grid format like hex, triangle and more.
• puzzle_solver for 90+puzzles by Ar-Kareem, also in OR-Tools.
• Puzzles-Solver in action by newtomsoft, with browser plugins provided.

How Puzzlekit differs:

Puzzlekit is designed as a Python library (WIP… though) for developers and researchers, offering programmatic access, a unified API, and a massive structured dataset for benchmarking.

Usage

Dependencies: Python >= 3.10, e.g.,

conda create -n py310 python=3.10.14

install the solvers via pip:

pip install puzzlekit

Then a quick tour:

import puzzlekit

problem_str = """
10 10
- - - - - b - - - -
- b - - w - - b - -
w - - - - - - - - -
- - - - - - - - w -
- - - - - b b - b -
- w - w w - - - - -
- w - - - - - - - -
- - - - - - - - - b
- - b - - b - - w -
- - - - w - - - - -
"""
res = puzzlekit.solve(problem_str, "masyu")
# res.show() # If you want to visualize it.

The detailed usage of specific logic puzzles can be found in the docs of puzzlekit.

If you want a batch-run, clone the dataset you need via puzzlekit-dataset to ./assets folder in the root. Then run the scripts/benchmark.py like:

python scripts/benchmark.py -p Hidoku 

The script will create ./benchmark_results folder where two files, benchmark_{timestamp}.csv and README_STATS_{puzzle_name}_{timestamp}.md can show you the details.

If you want to run all instances, use:

python scripts/benchmark.py -a

Currently it will take ~30 min to solve all 30k+ instances available.

---

If you want to try the bi-directional conversion between penpa+ and puzz.link, follow the quick tour:

import puzzlekit

# 1st method
ir = puzzlekit.decode("https://puzz.link/p?slither/10/10/g188227cl1dg367bdcg3ddgbhdgd1agbd760dg2cl633661d")
penpa_url = puzzlekit.encode(ir, "penpa")
print(penpa_url)
# get:
# https://swaroopg92.github.io/penpa-edit/#m=edit&p=7VdtT9swEP7Or0...


# 2nd method (recommend)
penpa_url = "YOUR_PENPA_URL" # both full URL or `m=edit&p=...` are okay
puzzlink_url = puzzlekit.convert(penpa_url, "puzzlink")
print(puzzlink_url)
# get:
# https://puzz.link/p?slither/10/10/b86ag68dg127bg62aldg8dad8bgdl26dg722cg68dg88b3

See also scripts/quick_start.py for a runnable sample.

Roadmap

• 130+ Puzzle Solvers & 40k+ Dataset.
• Unified Python API (pip install puzzlekit).
• Unified Converter: Batch converting internal formats to penpa-edit or puzz.link URLs.
• Dataset update, remove duplicates.
• Docs update.

---

Reference

Aside from links mentioned above, please refer to the following:

Solving Tools:

• OR-Tools CP-SAT solver by Google.
• Z3 SMT Solver by microsoft.
• Clingo and Clasp by the University of Potsdam, an answer set solving collection.
• Hakank’s OR-Tools tutorials
• More…

Dataset and online play:

• Raetsel’s Janko;
• Puzzle-xx.com.
• puzz.link, and variants like pzplus, pvz.jp
• pzprjs format for puzzle encoding.
• More…