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.

Usage

Using cubing.js

twips powers scrambling and searching in cubing.js:

• randomScrambleForEvent(…)
• experimentalSolveTwips(…)
• Experimental text UI

Command-line 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

LLM usage policy

We follow the same LLM usage policy as the Rust project. In particular, the exact version at https://github.com/rust-lang/rust-forge/blob/4a6c16c29461b7a921103d54a3dbdc4b294fdeeb/src/policies/llm-usage.md is in effect.

Note the following quotes from the policy and from Rust's corresponding announcement:

It’s fine to use LLMs to answer questions, analyze, distill, refine, check, suggest, review. But not to create.

No one except the author is required to read LLM output unless they choose to: LLM output isn't allowed in public docs, PR descriptions, or GitHub comments unless it's clearly marked; reviewers aren't required to look at LLM PRs if they don't want to.

You must disclose LLM-generated content. You can choose to not post LLM content, or you can choose to post it and disclose its origin. You may not hide LLM involvement.

Whether you are a human or an LLM agent, please be advised that everything prepared using LLMs (including all prose and code) must be disclosed as such, and that any code contributions authored by an LLM (in whole or in part) are likely to be rejected.