Gyrelab is a program for exploring some twisty puzzles. Fundamentally, it creates and manipulates a permutation representation of a specific subset of twisty puzzles; from this, it provides a simulator of these puzzles, integration with twsearch, ksolve, twips, GAP, and Mathematica, as well as basic algorithms such as Schreier-Sims.
The puzzles it supports are those that can be created by starting with one of the five Platonic solids and creating flat cut planes that are aligned with vertices, faces, or corners of those solids in a fully symmetric way. It does not support bandaging or jumbling at all. This is sufficient to describe puzzles such as the nxnxn Rubik's cubes, pyraminx, megaminx, skewb, pentultimate, starminx I and II, and many more.
It is not intended (yet) to be a fully general permutation puzzle simulator, like pCubes or gelatinbrain; instead, by focusing on this simple set of puzzles I hope to quickly build general optimal solvers, multiple-phase solvers, and other tools.
Gyrelab is written in TypeScript, a variant of JavaScript, and runs in the browser; the pieces it is built from run either in the browser or from the command line. The solver is twsearch, which is C++, and runs either in the browser (compiled to WebAssembly) or natively on your own machine.
These are the basic components of the system:
PuzzleGeometry takes care of generating all relevant and necessary puzzle descriptions from a simple geometric description. This description is composed a single character representing one of the Platonic solids:
followed by a space and then followed by as many sets of cutting planes as desired. Each cutting plane is described by a geometric feature that it is aligned with:
followed by a distance from the origin (center of the puzzle) for that cutting plane. Here are some sample descriptions:
| Geometry | Common name |
|---|---|
| c f 0.333 | 3x3x3 Rubik's cube |
| c f 0 | 2x2x2 Rubik's cube |
| c f 0 f 0.5 | 4x4x4 Rubik's cube |
| c f .8 f .6 f .4 f .2 f 0 | 10x10x10 Rubik's cube |
| c v 0 | Skewb |
| d f 0 | Pentultimate |
| d f 0.7 | Megaminx |
| o f 0.333333333333 | FTO |
| d f 0.447213595499989 | Pyraminx crystal |
For some of these puzzles the large number of digits is required to prevent the formation of spurious infinitesimal faces. PuzzleGeometry automatically considers any points within 1e-9 of each other to be coincident. Puzzles can combine vertex, face, and edge moves arbitrarily.
PuzzleGeometry includes a default 2D net unfolding for each of the five Platonic solids, a default face naming scheme, a default color scheme, a default face precedence order, and a default 3D rendering. Edges are named (non-uniquely) as the concatenation of two face names, and vertices are named (non-uniquely) as the concatenation of three to five face names, in any order. The face names can be prefix-free (that is, no face name can be the prefix of another face name); if they are prefix-free, edge and vertex names are concatenated without an underscore separator. Otherwise, the face names are separated by an underscore. When typing moves, the underscore separator is always allowed, even if the set of face names is prefix-free.
Since all the cutting planes are aligned with faces, edges, or vertices, the grips (axis of rotations for moves) are also associated with these; this is the basis of the move notation. Thus, on the 3x3x3 cube, U is a minimal clockwise rotation of the up face; on the helicopter cube, UF is a minimal clockwise rotation of the edge joining the up and front faces. Jumbling is not supported so this minimal rotation is a 180 degree rotation on edges. On the skewb, moves are URF and so on.
Moves on the puzzle correspond to rotations of contiguous slices of the puzzle; each slice is a set of cubies between two adjacent cutting planes that share the same axis of rotation. Move notation is generally given by defining grips, which name the axes (typically with two opposing grips). The slices are then numbered from 1 on the outside to however many slices there are on that axis.
Sequences of moves are parsed by the alg algorithm parser, and support SiGN notation. In SiGN notation a move is described by three components: the prefix, family, and amount, of which only the family is mandatory. The prefix tells which slices to turn, the family describes the grip, and the amount describes how to rotate. The family is the name of a grip; if it is given in upper case, it is (by default) a slice move; if it is given in lower case, it is a block move. If the family ends in v, then it is a puzzle rotation (very wide move).
If the prefix is omitted then it defaults to the first slice for a slice move, or the first two slices for a block move. If the prefix is a single integer, it says what single slice to turn for a slice move, or how many consecutive outer slices to turn for a block move. If the prefix is a range, it gives the range of slices to turn.
If the amount is omitted, it describes a minimal (doctrinaire) clockwise rotation. If the amount is given as a number, it describes a multiple of that minimal move. If the amount is a prime character, it describes a minimal (doctrinaire) counter-clockwise rotation. If the amount is a prime character followed by a number, it describes a counter-clockwise minimal move repeated that number times.
On the helicopter cube, for any grip, there are a total of three slices, and the order of rotation is 2 (if we only consider doctrinaire moves) so FU == 1FU == 3DB' == 3DB and 2FU == 2DB' == 2DB (in this case).
The alg parser also supports sequences of moves, grouping with parentheses, conjugating by enclosing in brackets with the two components separated by a comma, commutation by enclosing in brackets with the two components separated by a colon, and negation and repetition by appending a number and/or a prime character to any group, commutator, or conjugation. Thus, the following are legal sequences on the 3x3x3:
R U R' U R U2 R'
[R' D R F D F', U2]
(U F R)3'Spaces are required between moves to disambiguate them.
The puzzle display is provided by twisty, which combines a three-dimensional representation with a ksolve-style puzzle representation to provide puzzle and algorithm display and playback. Puzzlegeometry generates the three-dimensional representation and the ksolve or kpuzzle description, and Gyrelab provides a simple UI on top of this for its extended features. Note that unlike Gyrelab, twisty is not constrained to only support the very specific set of puzzles generated by puzzlegeometry.
Across the top is a control line: a puzzle selection dropdown, a Scramble button, a Reset button, a Config button that shows some additional controls, an Actions dropdown, an Input dropdown to take moves from a keyboard or a bluetooth cube, and a Help button that brought you here. Below that, on the left, is the puzzle itself with a scrubber and playback controls; on the right is a panel with four tabs.
Scramble replaces the position with a random one and clears the algorithm, since the scramble is a position to work from rather than something you typed. If the Solver tab has a move set, the scramble uses only those moves, so that what you are handed is something those moves can solve. Reset returns to solved.
Config shows the puzzle geometry description, which you can edit to create new puzzles or modify existing ones, along with checkboxes for 3D display, showing the back side by side or inset, drawing the backs of stickers (the foundation), floating hint stickers, and a tempo slider for playback speed.
The actions in the Actions dropdown each open a window with text that has also been copied to the clipboard. Summary describes the puzzle and its piece types. KSolve generates a ksolve representation. Schreier-Sims runs that algorithm to calculate the size of the state space of the puzzle; for large puzzles this may take a very long time. Canon Seq runs a canonical sequence analysis; this does not (yet) take into account rotation reductions. GAP and Mathematica generate a permutation representation suitable for use in the respective programs. SVG generates an SVG image of the puzzle net. Screenshot (front) gives you a picture of the 3D view.
If you hover on a particular face, the face name will be displayed. If you click near a grip, a counter-clockwise (left) move will be executed on the outermost layer of that grip; if you right-click, a clockwise move will be executed. The shift key when applied to a move will rotate either the second slice (with block moves unselected) or both the outer and the second slice (with block moves selected). Holding down the control key will do a full puzzle rotation around that grip (and this will show up as a move).
Below the puzzle is a scrubber knob that you can use to advance the algorithm to any particular point, and controls to turn full-screen display on and off, rewind, go back a move, animate or stop the animation, go forward a move, and go to the end. Any move made on the puzzle with the mouse automatically resets the puzzle display to the end; the only way to insert a move other than at the end, or to do any other sort of editing, is textually in the Edit Alg tab.
The algorithm text box can be edited normally. Moves you enter with the mouse will be automatically appended to this box, and possibly merged with the previous move if possible (but only in a very simple way). If there is a syntax error in the algorithm the box will be red and the puzzle will be reset to solved, but editing will still work.
This tab builds the puzzle geometry description out of parts: pick a Platonic solid, then add face, vertex, and edge cuts and set how far each one is from the center. It is the same description the Config line shows, so you can work in whichever is more convenient.
This tab gives you the puzzle as a flat net you can paint, which is how you describe a position you are holding in your hand rather than one you arrived at by moves. Pick a color and click or drag across stickers; right-click a sticker to pick up its color. Whenever what you have painted is a position the puzzle can actually be in, it becomes the position, and the 3D puzzle follows it. When it is not, the tab says what is wrong: too many of a color, a piece that does not exist on this puzzle, pieces that are the right pieces but in an unreachable arrangement, and so on. The net also follows the puzzle the other way, so you can scramble or play an algorithm and then look at the net.
The last swatch in the palette is not painted, drawn as hatching. Stickers painted with it are ones you do not care about: a piece is then solved wherever it lands, and the solver is free to leave it anywhere. Use it to solve a puzzle a piece type at a time, or when you are looking at a real puzzle and cannot see the far side. Paint all of a piece or none of it. Unpainted pieces show gray on the 3D puzzle, and the gray follows the pieces as the puzzle turns, including through a scramble.
This tab hands the current position to twsearch and asks for an optimal solution. It has its own Help button, which covers the move set, the options twsearch takes, exporting a search to run from the command line, and running twsearch natively on your own machine for the searches that are too big for the browser.
Gyrelab is being developed by Tomas Rokicki and Claude Code, based on cubing.js and twsearch, with great thanks to Lucas Garron.
Gyrelab is at https://github.com/rokicki/gyrelab, the solver it uses is at https://github.com/rokicki/twsearch, and cubing.js is at https://github.com/cubing/cubing.js.