cube_solver.cube.cube module

Cube module.

class cube_solver.cube.cube.Cube(scramble=None, repr=None, random_state=False)[source]

Bases: object

Create Cube object.

Parameters:

scramble (str or None, optional) – Initial scramble. If None, no scramble is applied. Default is None.
repr (str or None, optional) – Cube string representation. If not None, the scramble parameter is ignored and creates a cube with the given string representation. Default is None. See Notes for the string representation format.
random_state (bool, optional) – If True, the scramble and repr parameters are ignored and creates a cube with a uniform random state. Default is False.

Notes

The repr parameter must contain characters from {‘W’, ‘G’, ‘R’, ‘Y’, ‘B’, ‘O’}, representing the colors Color.WHITE, Color.GREEN, Color.RED, Color.YELLOW, Color.BLUE, and Color.ORANGE, respectively. The order of the string representation is:

           ------------
           | 01 02 03 |
           | 04 05 06 |
           | 07 08 09 |
---------------------------------------------
| 10 11 12 | 19 20 21 | 28 29 30 | 37 38 39 |
| 13 14 15 | 22 23 24 | 31 32 33 | 40 41 42 |
| 16 17 18 | 25 26 27 | 34 35 36 | 43 44 45 |
---------------------------------------------
           | 46 47 48 |
           | 49 50 51 |
           | 52 53 54 |
           ------------

If the orientation, permutation, or permutation_parity values cannot be determined correctly from the string representation, the orientation and permutation arrays will contain -1 at those positions, and permutation_parity will be set to None.

The default color scheme used for the cube is as follows (note: this may differ when using the repr parameter):

Examples

>>> from cube_solver import Cube

Initial scramble.

>>> cube = Cube("U F2 R'")
>>> cube  # string representation of the cube state
WWBWWBYYOGGROOROOBGGWGGWRRYBRRBRROOGYOOYBBWBBWWGYYGYYR

Initial string representation.

>>> cube = Cube(repr="WWBWWBYYOGGROOROOBGGWGGWRRYBRRBRROOGYOOYBBWBBWWGYYGYYR")
>>> print(cube)  # print a visual layout of the cube state
        ---------
        | W W B |
        | W W B |
        | Y Y O |
---------------------------------
| G G R | G G W | B R R | Y O O |
| O O R | G G W | B R R | Y B B |
| O O B | R R Y | O O G | W B B |
---------------------------------
        | W W G |
        | Y Y G |
        | Y Y R |
        ---------

Initial random state.

>>> cube = Cube(random_state=True)
>>> cube.coords  # coordinates of the cube state (result might differ) 
(167, 48, 22530, 203841327)

orientation: ndarray

Orientation array.

The orientation array contains the orientation values of the 8 corners and 12 edges of the cube. The first 8 elements represent the corner orientation values, and the remaining 12 elements represent the edge orientation values.

A corner is correctly oriented when the top or bottom facelet of the corner piece matches either the top or bottom color of the cube. Corner orientation values are:

0 if the corner is correctly oriented.
1 if the corner is twisted clockwise relative to the correct orientation.
2 if the corner is twisted counter-clockwise relative to the correct orientation.

An edge is correctly oriented if, when placed in its correct position using only Face.UP, Face.DOWN, Face.RIGHT and Face.LEFT face turns, it does not appear flipped. Edge orientation values are:

0 if the edge is correctly oriented.
1 if the edge is incorrectly oriented (i.e. flipped).

permutation: ndarray

Permutation array.

The permutation array contains the permutation values of the 8 corners and 12 edges of the cube. The first 8 elements represent the corner permutation values, and the remaining 12 elements represent the edge permutation values.

The solved state permutation goes from 0 to 7 for the corners, and from 8 to 19 for the edges. The piece ordering in the solved state is:

Corners: [UBL, UFR, DBR, DFL, UBR, UFL, DBL, DFR]
Edges: [UB, UF, DB, DF, UL, UR, DL, DR, BL, BR, FL, FR]

permutation_parity: bool | None

Permutation parity.

The permutation_parity indicates the parity of both corner and edge permutations (i.e. both parities are always the same), True for odd parity, False for even parity, and None if the parity cannot be determined.

The solved state permutation parity starts with even corner and endge parity.

property coords: Tuple[int, ...]

Cube coordinates.

Corner orientation, edge orientation, corner permutation, and edge permutation coordinates.

See also

get_coords, set_coords

Examples

>>> from cube_solver import Cube
>>> cube = Cube("U F2 R'")

Get cube coordinates.

>>> cube.coords
(657, 0, 25253, 85684063)

Set cube coordinates.

>>> cube.coords = (0, 0, 0, 0)  # solved state
>>> cube
WWWWWWWWWOOOOOOOOOGGGGGGGGGRRRRRRRRRBBBBBBBBBYYYYYYYYY

property is_solved: bool

Whether the cube is solved.

Examples

>>> from cube_solver import Cube
>>> cube = Cube()
>>> cube.is_solved
True
>>> cube.apply_maneuver("U F2 R'")
>>> cube.is_solved
False

reset()[source]

Reset the cube to the solved state using the default color scheme.

Examples

>>> from cube_solver import Cube
>>> cube = Cube(random_state=True)
>>> cube.reset()
>>> cube
WWWWWWWWWOOOOOOOOOGGGGGGGGGRRRRRRRRRBBBBBBBBBYYYYYYYYY

set_random_state()[source]

Set a uniform random state.

Sets random coords (corner orientation, edge orientation, corner permutation, and edge permutation coordinates).

Examples

>>> from cube_solver import Cube
>>> cube = Cube()
>>> cube.set_random_state()
>>> cube.coords  # result might differ 
(167, 48, 22530, 203841327)

apply_move(move)[source]

Apply a move to the cube.

Parameters:: move (Move) – Move to apply.

Examples

>>> from cube_solver import Cube, Move
>>> cube = Cube()
>>> cube.apply_move(Move.U1)   # U face move
>>> cube.apply_move(Move.M2)   # M2 slice move
>>> cube.apply_move(Move.FW3)  # Fw' wide move
>>> cube.apply_move(Move.X1)   # x rotation
>>> cube
RGGBBORGGWYWWYWGOOGOOGOOYWYYWYYWYRRBRRBRRBWYWBRBBGBOGO

apply_maneuver(maneuver)[source]

Apply a sequence of moves to the cube.

Accepts the following move types:

Face moves (e.g. U, F2, R’).
Slice moves (e.g. M, E2, S’).
Wide moves (e.g. Uw, Fw2, Rw’ or u, f2, r’).
Rotations (e.g. x, y2, z’).

Parameters:: maneuver (str) – The sequence of moves to apply.

Examples

>>> from cube_solver import Cube
>>> cube = Cube()
>>> cube.apply_maneuver("U M2 Fw' x")
>>> cube
RGGBBORGGWYWWYWGOOGOOGOOYWYYWYYWYRRBRRBRRBWYWBRBBGBOGO

get_coord(coord_name)[source]

Get cube coordinate value.

Parameters:

coord_name ({'co', 'eo', 'cp', 'ep', 'pcp', 'pep'}) –

Get the specified cube coordinate.

’co’ means corner orientation.
’eo’ means edge orientation.
’cp’ means corner permutation.
’ep’ means edge permutation.
’pcp’ means partial corner permutation (a value for each corner orbit).
’pep’ means partial edge permutation (a value for each edge orbit).

Returns:

coord – Cube coordinate value. For partial coordinate values, a value of -1 indicates an orbit with no permutation values (e.g., (-1, -1, 0)), meaning the permutation (and orientation) values for that orbit are set to -1. If only the value of the first orbit is available (i.e., (coord, -1, -1)), returns an int representing that partial coordinate value.

The orbit order for partial coordinate values is:

Corner orbits: Orbit.TETRAD_111, Orbit.TETRAD_M11
Edge orbits: Orbit.SLICE_MIDDLE, Orbit.SLICE_EQUATOR, Orbit.SLICE_STANDING

Return type:

int or tuple of int

Examples

>>> from cube_solver import Cube
>>> cube = Cube("U F2 R'")

Get corner coordinates.

>>> cube.get_coord('co')   # corner orientation
657
>>> cube.get_coord('cp')   # corner permutation
25253
>>> cube.get_coord('pcp')  # partial corner permutation
(984, 679)

Get edge coordinates.

>>> cube.get_coord('eo')   # edge orientation
0
>>> cube.get_coord('ep')   # edge permutation
85684063
>>> cube.get_coord('pep')  # partial edge permutation
(8087, 7016, 3576)

set_coord(coord_name, coord)[source]

Set cube coordinate value.

Parameters:

coord_name ({'co', 'eo', 'cp', 'ep', 'pcp', 'pep'}) –
Set the specified cube coordinate.
- ’co’ means corner orientation.
- ’eo’ means edge orientation.
- ’cp’ means corner permutation.
- ’ep’ means edge permutation.
- ’pcp’ means partial corner permutation (a value for each corner orbit).
- ’pep’ means partial edge permutation (a value for each edge orbit).
coord (int or tuple of int) –
Cube coordinate value. For partial coordinate values, a value of -1 indicates an orbit with no permutation values (e.g., (-1, -1, 0)), meaning the permutation (and orientation) values for that orbit are set to -1. If an int is passed as a partial coordinate value, the value will be applied only to the first orbit (i.e., (coord, -1, -1)).

The orbit order for partial coordinate values is:
- Corner orbits: Orbit.TETRAD_111, Orbit.TETRAD_M11
- Edge orbits: Orbit.SLICE_MIDDLE, Orbit.SLICE_EQUATOR, Orbit.SLICE_STANDING

Notes

Corner and edge permutation parities are always either both even or both odd. This constraint is enforced when setting the (partial) corner permutation and the normal edge permutation coordinates by adjusting the permutation of the edges in the permutation array while preserving the same normal edge permutation coordinate (i.e. the number of valid edge permutations is effectively halved). When setting the partial edge permutation coordinate, if the edge permutation parity does not match the corner permutation parity, permutation_parity will be set to None.

Examples

>>> from cube_solver import Cube
>>> cube = Cube()

Set corner coordinates.

>>> cube.set_coord('co', 456)           # corner orientation
>>> cube.orientation[:8]
array([0, 1, 2, 1, 2, 2, 0, 1])
>>> cube.set_coord('cp', 28179)         # corner permutation
>>> cube.permutation[:8]
array([5, 4, 0, 7, 1, 3, 6, 2])
>>> cube.set_coord('pcp', (1273, 391))  # partial corner permutation
>>> cube.permutation[:8]
array([5, 4, 0, 7, 1, 3, 6, 2])

Set edge coordinates.

>>> cube.set_coord('eo', 673)                  # edge orientation
>>> cube.orientation[8:]
array([0, 1, 0, 1, 0, 1, 0, 0, 0, 0, 1, 0])
>>> cube.set_coord('ep', 96690777)             # edge permutation
>>> cube.permutation[8:]
array([12, 18, 10, 19,  9, 13, 14, 17, 16,  8, 11, 15])
>>> cube.set_coord('pep', (7262, 2633, 8640))  # partial edge permutation
>>> cube.permutation[8:]
array([12, 18, 10, 19,  9, 13, 14, 17, 16,  8, 11, 15])

Set some partial coordinates with -1.

>>> cube.set_coord('pcp', (1273, -1))      # same as cube.set_coord('pcp', 1273)
>>> cube.permutation[:8]
array([-1, -1,  0, -1,  1,  3, -1,  2])
>>> cube.set_coord('pep', (7262, -1, -1))  # same as cube.set_coord('pep', 7262)
>>> cube.permutation[8:]
array([-1, -1, 10, -1,  9, -1, -1, -1, -1,  8, 11, -1])

get_coords(partial_corner_perm=False, partial_edge_perm=False)[source]

Get cube coordinates.

Get the corner orientation, edge orientation, (partial) corner permutation and (partial) edge permutation coordinates.

Parameters:

partial_corner_perm (bool, optional) – If True, returns the partial corner permutation coordinate, otherwise returns the normal corner permutation coordinate. Default is False.
partial_edge_perm (bool, optional) – If True, returns the partial edge permutation coordinate, otherwise returns the normal edge permutation coordinate. Default is False.

Returns:

coords – Cube coordinates in the following order: corner orientation, edge orientation, (partial) corner permutation, (partial) edge permutation.

Return type:

tuple of (int or tuple of int)