rapidcube 0.2.0

A lightning-fast 2x2 and 3x3 Rubik's Cube simulator for Python, implemented in Rust.

rapidcube

rapidcube is a high-performance Rubik's Cube simulator for Python, implemented in Rust with PyO3.

It is designed for fast state transitions, algorithm simulation, and experimentation workflows such as search, benchmarking, and machine learning.

Features

• Rust-backed speed with a Python-friendly API
• 2x2 and 3x3 cube models
• Fast face-turn methods for each basic move and inverse move
• Move-sequence parser via standard cube notation
• Compact integer state encoding for efficient state handling
• ANSI-colored text rendering for quick terminal inspection

Installation

From PyPI

# using pip
pip install rapidcube

# Using uv 
uv add rapidcube

From Source (development)

Requirements:

• Python 3.13 recommended (package metadata currently targets 3.8+)
• Rust toolchain (stable)
• uv (recommended) or maturin

git clone [e-mail]:oblo0810/rapidcube.git
cd rapidcube

# Using uv (recommended)
uv sync
uv run maturin develop --release

# Or using standard pip
python -m pip install maturin
maturin develop --release

Quick Start

2x2 Example

from rapidcube import Cube2x2

cube = Cube2x2()
print(cube)

cube.do_moves("R U R' U'")

print(cube)
print("Binary encoding:", cube.to_binary())

3x3 Example

from rapidcube import Cube3x3

cube = Cube3x3()
cube.do_moves("F R U R' U' F'")

print("Corners encoding:", cube.to_binary())
print(cube)

Move Notation

The move parser supports whitespace-separated tokens:

• Face turns: U D R L F B
• Inverse turns: append ' or ! (example: R', U!)
• Double turns: append 2 (example: F2)

Example:

R U R' U' F2 D B'

Note: unknown tokens are ignored by do_moves.

API Overview

Cube2x2

• Cube2x2()
• state: int (read-only)
• get_next_states(cubes: list[Cube2x2] | list[Cube3x3]) -> numpy.ndarray returning a (len(cubes) * 12, 24) or (len(cubes) * 12, 54) sticker matrix
• Single-move methods:
  • do_u_move, do_u_prime_move
  • do_d_move, do_d_prime_move
  • do_r_move, do_r_prime_move
  • do_l_move, do_l_prime_move
  • do_f_move, do_f_prime_move
  • do_b_move, do_b_prime_move
• do_moves(moves: str)
• to_binary() -> str (64-bit binary string)
• str(cube) returns an ANSI-colored net

Cube3x3

• Cube3x3()
• corners: int (read-only)
• Same move methods as Cube2x2
• do_moves(moves: str)
• to_binary() -> str (corner-state binary encoding)
• str(cube) returns an ANSI-colored net

CubeBatch

• CubeBatch(cubes: list[Cube2x2] | list[Cube3x3])
• Stores cubes in Rust-owned native storage, not Python objects
• len(batch) / batch[i] work as a sequence; indexed access materializes only the requested cube
• CubeBatch.from_count(count, cube_type) creates a typed batch of solved cubes
• batch.cube_type() returns Cube2x2 or Cube3x3

Benchmarks

Benchmark tests are included under benchmarks/ and compare selected operations against other Python cube libraries.

Run benchmarks with:

uv run pytest benchmarks/

Testing

Run unit tests with:

uv run pytest -q

Project Status

The project is currently in early development. The public API may evolve as testing and feature coverage expand.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.