Twizzle Pattern Searcher (twips)

A twisty puzzle search program to that can find algs and scrambles for WCA puzzles and a wide variety of other permutation puzzles. twips is inspired by KSolve and uses concepts and algorithms from the C++ twsearch implementation and other state-of-the-art solvers. It is primarily designed for KPuzzle definitions but also provides an API for arbitrary implementations of semigroup search.

Twizzle Search powers alg search and scramble functionality for Twizzle and cubing.js, and can be used from the commandline or as a library in many environments.

Project Goals

1. Maintainability
   • We want twips to serve as a foundation for the cubing software ecosystem for a long time.
   • The project has multiple maintainers from the start, and we want to focus on a sustainable model for stewardship.
2. Ease of use
   • Powerful APIs that are easy to get started with.
   • Can either be used directly, or as a library in other projects.
   • Ability to scale from mobile devices all the way to native binaries that can fully utilize high-end hardware.
   • Can be used on any website through cubing.js, either by running in the browser itself or optionally connecting to a computer.
3. Performance
   • Great performance out of the box for a wide variety of puzzles.
   • Tunable optimizations for heavy-duty searches, including reusable prune tables for time-memory tradeoff.

Example usage

Install using one of:

# Homebrew (https://brew.sh/)
brew install --HEAD cubing/cubing/twips

# cargo (using `rustup`: https://rustup.rs/)
cargo install --locked --no-default-features twips-cli # option 1: without SIMD
cargo +nightly install --locked twips-cli # option 2: with experimental SIMD
twips completions <your shell> # Get completions for your shell

# From the source repo
git clone https://github.com/cubing/twips/ && cd twips
cargo install --path ./src/cli
twips completions <your shell> # Get completions for your shell

# Run without installing
git clone https://github.com/cubing/twips/ && cd twips
cargo run --release -- # Use this instead of `twips` in the commands below.

Examples (using files in the repo):

# Find 10 <U, F, R> algs for T-Perm
twips search \
  --generator-moves "U,F,R" \
  --min-num-solutions 10 \
  samples/3x3x3/3x3x3-Reid.def.json \
  samples/3x3x3/T-perm.scramble.json

# Generate scrambles
twips scramble --amount 7 sq1 2>/dev/null

# Solve a scramble for a known puzzle.
twips solve-known-puzzle 3x3x3 "U' F2 U' R2 F2 D' B2 D B2 U L2 U2 R2 L2 F2 L' D2 U2 B' U F2 R B' F L"

# Calculate the graphs for God's algorithm for 2×2×2
twips gods-algorithm \
  --generator-moves U,F,R \
  samples/2x2x2/2x2x2.kpuzzle.json

# Run a server for the web interface: https://experiments.cubing.net/cubing.js/twips/text-ui.html
twips serve

Scrambles

The Rust implementation contains scrambling code intended to replace tnoodle-lib.

Derived scrambles

twips implements a protocol to derive scrambles from a competition root seed (a 64-character hex string). Test like this:

twips \
  derive \
  67002dfc95e6d4288f418fbaa9150aa65b239fd5581f2d067d0293b9321a8b67 \
  EBNLEND@MABLNHJFHGFEKFIA@DNBKABHHNANA@FD@KKADJAKNFCIJNJGIFCBLEDF/scrambles/333/r1/g1/a1/333/sub1

Official events

Event	Supported	Min optimal solution moves	Min scramble alg moves	Prefix/Suffix	Potential features
333, 333oh, 333ft	✅ (MRSS)	✅ (2)	☑️ (N/A)	☑️ (N/A)
222	✅ (MRSS)	✅ (4)	✅ (11)	☑️ (N/A)
333bf, 333mbf	✅ (MRSS)	✅ (2)	☑️ (N/A)	✅ (wide moves)
333fm	✅ (MRSS)	✅ (2)	☑️ (N/A)	✅ (R' U' F)
444	✅ (MRSS)	✅ (2)	☑️ (N/A)	☑️ (N/A)
444bf	✅ (MRSS)	✅ (2)	☑️ (N/A)	☑️ (not necessary)
555	✅ (60 random moves)	✅ (2)	☑️ (N/A)	☑️ (N/A)	layered randomization
555bf	✅ (60 random moves + suffix)	✅ (2)	☑️ (N/A)	✅ (wide moves)	layered randomization
666	✅ (80 random moves)	✅ (2)	☑️ (N/A)	☑️ (N/A)	layered randomization, use 3Fw instead of 3Bw
777	✅ (100 random moves)	✅ (2)	☑️ (N/A)	☑️ (N/A)	layered randomization
clock	✅ (MRSS)	✅ (2)	☑️ (N/A)	☑️ (N/A)
minx	✅ (random moves — Pochmann style)	✅ (2)	☑️ (N/A)	☑️ (N/A)	TODO: ask xyzzy
pyram	✅ (MRSS)	✅ (6)	✅ (11)	☑️ (N/A)
skewb	✅ (MRSS)	✅ (7)	✅ (11)	☑️ (N/A)
sq1	✅ (MRSS)	✅ (11)	☑️ (N/A)	☑️ (N/A)

Unofficial events

Event	Supported	Min optimal solution moves	Min scramble alg moves	Prefix/Suffix	Potential features
fto	🚧 (MRSS)	🚧 (2 moves?)	☑️ (N/A)	☑️ (N/A)
master_tetraminx	🚧 (MRSS)	🚧 (2 moves?)	☑️ (N/A)	☑️ (N/A)
kilominx	✅ (MRSS)	✅ (4 moves)	☑️ (N/A)	☑️ (N/A)
redi_cube	🚧 (MRSS)	🚧 (2 moves?)	☑️ (N/A)	☑️ (N/A)
baby_fto	✅ (MRSS)	✅ (5 moves)	✅ (10 moves)	☑️ (N/A)

Build tools

• Rust and cargo via rustup.
  • Note that this project uses rust-toolchain.toml, which effectively requires rustup to manage Rust toolchain versions.
• bun

License

This work is dual-licensed under the Mozilla Public License 2.0 and GPL 3.0 (or any later version). If you use this work, you can choose either (or both) license terms to adhere to.

SPDX-License-Identifier: MPL-2.0 OR GPL-3.0-or-later