Project 14AI engineering
Puppet Cube solver
Picks a verified Puppet Cube phase-3 algorithm for a requested edge swap, 3-cycle or flip, and builds one from the guide's macros with breadth-first and meet-in-the-middle search when no published case fits. Pure standard-library Python with a Tk window and a CLI.
The problem
The Puppet Cube is a 3×3×3 shape mod in which several pieces are fused into larger blocks, so a face turn can drag hidden layers of the mechanism, and an algorithm only works from the grip it was designed for. A guide fixes the edges with 36 published phase-3 algorithms, but using them means knowing which one produces the effect in front of you, how to hold the cube, and what to do when none fits.
What I built
- An edge-only cube model. Face turns are −90° Rodrigues rotations of integer face vectors, so no move table is typed by hand, and wide turns and regrips come from the same code.
- A verified catalogue. The 36 published algorithms are simulated in the guide’s exact grips, with the Puppet blocks modeled as hidden wide turns, and de-duplicated into 34 verified entries.
- A fallback search over the 14 distinct macro effects: BFS up to 4 macros, and for exact flips a bidirectional meet-in-the-middle search that reaches 8 macros while holding at most 60,838 states, where a one-way search would need 3,830,186 states by six macros.
- Group-theory checks. All macros are even permutations, so an odd number of swaps without two free edges is rejected up front.
Results
- count
- 34verified catalogue entries from 36 published algorithms, re-simulated before display
- operations
- ≈ 0.5 sslowest request, an 8-macro flip, on an Apple M5
- count
- 96unit tests, with CI on Python 3.11 to 3.14
Every two-edge flip, single swap and unprotected 3-cycle on the 9 movable edges is answered; the slowest request, an eight-macro exact flip, takes about half a second on an Apple M5. Verification is against the simulation model.
Links
- RepositoryOpen: Repository