MagicCube

1.2.0 · active · verified Fri Apr 17

MagicCube is a Python library providing an NxNxN Rubik's Cube implementation. It allows for cube manipulation, scrambling, and solving (including Kociemba's algorithm). The current stable version is 1.2.0, with ongoing development reflected in beta releases, though stable releases are less frequent.

Common errors

```
AttributeError: module 'magiccube.cube' has no attribute 'Cube'
```
cause Attempting to import `Cube` from `magiccube.cube` after the v1.2.0 change which moved `Cube` to the top-level `magiccube` namespace, and some environments might not correctly resolve the old path.

fix Change the import statement to `from magiccube import Cube`.
```
ValueError: Invalid move 'R3'. Move count must be 1 or 2 for SiGN notation. (Got 3)
```
cause Using a move string with a count greater than 2 (e.g., 'R3') after the v1.2.0 update to SiGN notation.

fix Rewrite the move using SiGN notation (e.g., 'R''' or 'R' instead of 'R3'). For a 'U3' equivalent, use 'U'' or 'U PRIME'.
```
RuntimeError: This library requires Python 3.9 or newer. You are running 3.X.Y
```
cause Running `magiccube` v1.1.0 or newer with a Python interpreter older than 3.9.

fix Upgrade your Python environment to version 3.9 or later. You can use `pyenv` or `conda` to manage multiple Python versions.

Warnings

breaking Rotation notation changed in v1.2.0 to align with SiGN notation. This constrains move counts to a maximum of 2 (e.g., 'U', 'U2', 'U' for prime). Moves like 'U3' are now invalid.
Fix: Update rotation strings to use SiGN notation. For example, change 'R3' to 'R'' or 'R U R2' to 'R U R2' where individual move counts are 1 or 2.
breaking Public objects like `Cube` are now exposed directly in the `magiccube` top-level namespace. Old imports like `from magiccube.cube import Cube` will still work but `from magiccube import Cube` is the new preferred way.
Fix: Refactor imports to `from magiccube import Cube` for top-level objects where applicable, following the library's new structure.
breaking The minimum Python version was raised to 3.9 in v1.1.0.
Fix: Ensure your development environment uses Python 3.9 or newer. Upgrade your Python interpreter if necessary.
breaking The default cube orientation was changed in v1.0.0 to match WCA scrambling orientation. This may affect algorithms or tests that implicitly relied on the previous default orientation.
Fix: If your code relies on a specific initial orientation, explicitly set it or adjust your expectations of the cube's state after initialization.

Install

pip install magiccube Install stable release

Imports

Cube
wrong:
```
from magiccube.cube import Cube
```
correct:
```
from magiccube import Cube
```
As of v1.2.0, key public objects like `Cube` are directly exposed in the top-level `magiccube` namespace. Direct import is preferred.
Move
```
from magiccube.cube import Move
```
While `Cube` is top-level, other related classes like `Move` remain in their submodules.
KociembaSolver
```
from magiccube.solver import KociembaSolver
```
`KociembaSolver` and other solver-related classes are found within the `magiccube.solver` submodule.

Quickstart

This quickstart demonstrates how to instantiate a cube, scramble it, retrieve its state in Kociemba format, solve it using the Kociemba solver, and apply the solution.

from magiccube import Cube
from magiccube.cube import Move
from magiccube.solver import KociembaSolver

# Create a 3x3x3 cube
c = Cube(3)

# Scramble the cube
c.scramble(count=25)
print('Scrambled cube:')
print(c)

# Get facelet colors in Kociemba format
kociemba_colors = c.get_kociemba_facelet_colors()
print(f'Kociemba facelet colors: {kociemba_colors}')

# Solve the cube using Kociemba's algorithm
solver = KociembaSolver(c)
solution = solver.solve()
print(f'Solution: {solution}')

# Apply the solution to verify
c.rotate(solution)
print('Solved cube:')
print(c)
assert c.is_solved()

view raw JSON →