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

Unofficial events

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