cube-model 1.0.3__py3-none-any.whl

cube_model/__init__.py

@@ -0,0 +1,86 @@
+from .new_cube import new_cube, shuffled, solved
+from .model import (
+  Color,
+  Side,
+  Sticker,
+  CornerSticker,
+  EdgeSticker,
+  Cube,
+)
+
+from .navigation import (
+  Nav,
+  nav,
+  nav_cc,
+  parse_navs,
+  HOME_TO_SIDE,
+  corner_on_side,
+  side_corners,
+  sticker_side,
+  side_color,
+  color_side,
+  all_colors,
+)
+
+from .move import (
+  Multiplicity,
+  Move,
+  move,
+  moved,
+)
+
+from .utils import (
+  permutation_cycles,
+  even_permutation,
+  rand_elt,
+  to_radix,
+)
+
+from .reachable import (
+  locations_ok,
+  edge_flips_ok,
+  corner_rotations_ok,
+  reachable,
+)
+
+from .rotate import (
+  rotate,
+  rotated,
+)
+
+__all__ = [
+  'Color',
+  'Side',
+  'Sticker',
+  'CornerSticker',
+  'EdgeSticker',
+  'Cube',
+  'new_cube',
+  'shuffled',
+  'solved',
+  'Nav',
+  'nav',
+  'nav_cc',
+  'parse_navs',
+  'HOME_TO_SIDE',
+  'corner_on_side',
+  'side_corners',
+  'sticker_side',
+  'side_color',
+  'color_side',
+  'all_colors',
+  'Multiplicity',
+  'Move',
+  'move',
+  'moved',
+  'permutation_cycles',
+  'even_permutation',
+  'rand_elt',
+  'to_radix',
+  'locations_ok',
+  'edge_flips_ok',
+  'corner_rotations_ok',
+  'reachable',
+  'rotate',
+  'rotated',
+]

cube_model/action.py

@@ -0,0 +1,189 @@
+'''Standard cube move notation: actions, parsing, and dispatch.
+
+Action is the union Move | Rotation | WideMove | SliceMove.
+Rotation, WideMove, and SliceMove are frozen dataclasses wrapping a
+Move, distinct concrete types at runtime while serving as newtypes of
+Move at the type-checker level.
+
+act(action, cube) applies an action in place.
+acted(action, cube) returns a new cube with the action applied.
+
+Decompositions:
+  WideMove(m)  — rotate(m, cube); move(Move(opp_side[m.face], m.mult), cube)
+  SliceMove(m) — rotate(m, cube); move(Move(opp_side[m.face], m.mult), cube);
+                 move(Move(m.face, invert[m.mult]), cube)
+
+parse_actions(s, ci=False) parses standard cube move notation.
+Tokens may be written with or without spaces between them. Each token
+is a base letter followed by an optional modifier: nothing (CW),
+apostrophe (CCW), or 2 (TWO).
+
+Standard notation:
+  Face moves:  U D F B L R
+  Rotations:   x y z
+  Wide moves:  u d f b l r  or  Uw Dw Fw Bw Lw Rw
+  Slice moves: M E S
+
+When ci=True, all letters are folded to uppercase. Bare lowercase
+letters parse as face moves. Wide moves require the w or W suffix.
+'''
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+from .model import Cube, Side, opp_side, shallow_copy
+from .move import Move, Multiplicity, invert, move
+from .rotate import rotate
+
+@dataclass(frozen=True)
+class Rotation:
+    '''A rigid cube rotation (x, y, z); newtype of Move.'''
+    move: Move
+
+@dataclass(frozen=True)
+class WideMove:
+    '''A wide two-layer move; newtype of Move.'''
+    move: Move
+
+@dataclass(frozen=True)
+class SliceMove:
+    '''A middle-layer slice move (M, E, S); newtype of Move.'''
+    move: Move
+
+# Any action representable in standard cube notation.
+type Action = Move | Rotation | WideMove | SliceMove
+
+# An iterator of Action values.
+type Actions = Iterator[Action]
+
+_MULT_SUFFIX: dict[str, Multiplicity] = {
+    '':  Multiplicity.CW,
+    "'": Multiplicity.CCW,
+    '2': Multiplicity.TWO,
+}
+
+_FACE_SIDE: dict[str, Side] = {
+    'U': Side.TOP,
+    'D': Side.BOTTOM,
+    'F': Side.FRONT,
+    'B': Side.BACK,
+    'L': Side.LEFT,
+    'R': Side.RIGHT,
+}
+
+_ROTATION_SIDE: dict[str, Side] = {
+    'x': Side.RIGHT,
+    'y': Side.TOP,
+    'z': Side.FRONT,
+}
+
+_WIDE_SIDE: dict[str, Side] = {
+    'u': Side.TOP,
+    'd': Side.BOTTOM,
+    'f': Side.FRONT,
+    'b': Side.BACK,
+    'l': Side.LEFT,
+    'r': Side.RIGHT,
+}
+
+_SLICE_SIDE: dict[str, Side] = {
+    'M': Side.LEFT,
+    'E': Side.BOTTOM,
+    'S': Side.FRONT,
+}
+
+class ParseError(ValueError):
+    '''Raised when a move token cannot be parsed.'''
+
+def _parse_mult(s: str, pos: int) -> tuple[Multiplicity, int]:
+    '''Parse a multiplicity modifier at pos, returning (mult, new_pos).'''
+    if pos < len(s) and s[pos] == "'":
+        return Multiplicity.CCW, pos + 1
+    if pos < len(s) and s[pos] == '2':
+        return Multiplicity.TWO, pos + 1
+    return Multiplicity.CW, pos
+
+def _parse_one(s: str, pos: int, ci: bool) -> tuple[Action, int]:
+    '''Parse one token from s starting at pos.
+
+    Returns (action, new_pos). Raises ParseError on invalid input.
+    '''
+    if pos >= len(s):
+        raise ParseError(f'unexpected end of input at position {pos}')
+    base: str = s[pos]
+    pos += 1
+
+    # w/W suffix: wide move. Valid for any face letter, either case.
+    if pos < len(s) and s[pos] in ('w', 'W'):
+        pos += 1
+        mult, pos = _parse_mult(s, pos)
+        upper: str = base.upper()
+        if upper not in _FACE_SIDE:
+            raise ParseError(
+                f'unknown wide-move face {base!r}'
+            )
+        return WideMove(Move(_FACE_SIDE[upper], mult)), pos
+
+    if ci:
+        upper = base.upper()
+        mult, pos = _parse_mult(s, pos)
+        if upper in _FACE_SIDE:
+            return Move(_FACE_SIDE[upper], mult), pos
+        if upper in ('X', 'Y', 'Z'):
+            return Rotation(Move(_ROTATION_SIDE[base.lower()], mult)), pos
+        if upper in ('M', 'E', 'S'):
+            return SliceMove(Move(_SLICE_SIDE[upper], mult)), pos
+        raise ParseError(f'unknown move letter {base!r}')
+
+    mult, pos = _parse_mult(s, pos)
+    if base in _FACE_SIDE:
+        return Move(_FACE_SIDE[base], mult), pos
+    if base in _ROTATION_SIDE:
+        return Rotation(Move(_ROTATION_SIDE[base], mult)), pos
+    if base in _WIDE_SIDE:
+        return WideMove(Move(_WIDE_SIDE[base], mult)), pos
+    if base in _SLICE_SIDE:
+        return SliceMove(Move(_SLICE_SIDE[base], mult)), pos
+    raise ParseError(f'unknown move letter {base!r}')
+
+def parse_actions(s: str, ci: bool = False) -> list[Action]:
+    '''Parse standard cube move notation into a list of actions.
+
+    Tokens may be separated by optional whitespace. Each token is a
+    base letter followed by an optional modifier: nothing (CW),
+    apostrophe (CCW), or 2 (TWO).
+
+    Raises ParseError on unrecognised letters or modifiers.
+    '''
+    actions: list[Action] = []
+    pos: int = 0
+    while pos < len(s):
+        if s[pos].isspace():
+            pos += 1
+            continue
+        action, pos = _parse_one(s, pos, ci)
+        actions.append(action)
+    return actions
+
+def act(action: Action, cube: Cube) -> None:
+    '''Apply an action to a cube in place.'''
+    match action:
+        case Rotation(move=m):
+            rotate(m, cube)
+        case WideMove(move=m):
+            rotate(m, cube)
+            move(Move(opp_side[m.face], m.mult), cube)
+        case SliceMove(move=m):
+            rotate(m, cube)
+            move(Move(opp_side[m.face], m.mult), cube)
+            move(Move(m.face, invert[m.mult]), cube)
+        case Move() as m:
+            move(m, cube)
+
+def acted(action: Action, cube: Cube) -> Cube:
+    '''Return a new cube with an action applied, leaving the original unchanged.'''
+    new: Cube = shallow_copy(cube)
+    act(action, new)
+    return new

cube_model/model.py

@@ -0,0 +1,99 @@
+'''Core cube model: colors, sides, stickers, and the Cube dataclass.'''
+
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+class Color(Enum):
+  '''Enumeration of the six cube colors.'''
+  WHITE = auto()
+  YELLOW = auto()
+  RED = auto()
+  ORANGE = auto()
+  BLUE = auto()
+  GREEN = auto()
+
+class Side(Enum):
+  '''Enumeration of the six cube sides.'''
+  FRONT = auto()
+  BACK = auto()
+  LEFT = auto()
+  RIGHT = auto()
+  TOP = auto()
+  BOTTOM = auto()
+
+@dataclass(eq=False)
+class Sticker(ABC):
+  '''Abstract sticker with a color and cyclic partner.'''
+  color: Color
+  other: Sticker = field(init=False)
+  _hash: int = field(init=False, repr=False, compare=False)
+
+  def __post_init__(self) -> None:
+    '''Initialize as a self-loop before wiring.'''
+    self._rewire(self)
+
+  def _rewire(self, other: Sticker) -> None:
+    '''Set partner and recompute hash.'''
+    self.other = other
+    self._hash = hash((self.color, other.color))
+
+  def __eq__(self, other: object) -> bool:
+    '''Equality based on color pair.'''
+    if not isinstance(other, Sticker):
+      return NotImplemented
+    return (
+      self.color == other.color
+      and self.other.color == other.other.color
+    )
+
+  def __hash__(self) -> int:
+    '''Hash based on this sticker's color and its partner's color.'''
+    return self._hash
+
+@dataclass(eq=False)
+class CornerSticker(Sticker):
+  '''Corner sticker linked in a 3-cycle.'''
+  other: CornerSticker = field(init=False)
+
+@dataclass(eq=False)
+class EdgeSticker(Sticker):
+  '''Edge sticker linked in a 2-cycle.'''
+  other: EdgeSticker = field(init=False)
+
+@dataclass
+class Cube:
+  '''Cube defined by one corner and cyclic adjacency maps.'''
+  home: CornerSticker
+  front_color: Color
+  top_color: Color
+  next_edge:   dict[CornerSticker, EdgeSticker]
+  next_corner: dict[EdgeSticker, CornerSticker]
+
+# Opposite face for each side.
+opp_side: dict[Side, Side] = {
+    Side.LEFT:   Side.RIGHT,
+    Side.RIGHT:  Side.LEFT,
+    Side.BOTTOM: Side.TOP,
+    Side.TOP:    Side.BOTTOM,
+    Side.BACK:   Side.FRONT,
+    Side.FRONT:  Side.BACK,
+}
+
+def shallow_copy(cube: Cube) -> Cube:
+  '''Return a new Cube sharing all sticker objects but with new dicts.
+
+  Moves only reassign dict values (which sticker a key maps to); they
+  never mutate sticker objects themselves. A shallow copy therefore
+  gives full independence between the two cubes without allocating new
+  sticker objects.
+  '''
+  return Cube(
+    home=cube.home,
+    front_color=cube.front_color,
+    top_color=cube.top_color,
+    next_edge=dict(cube.next_edge),
+    next_corner=dict(cube.next_corner),
+  )

cube_model/move.py

@@ -0,0 +1,167 @@
+'''Face moves implemented via local sticker cycles.'''
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+from .model import CornerSticker, Cube, EdgeSticker, Side, shallow_copy
+from .navigation import (
+  Nav,
+  nav_cc,
+  corner_on_side,
+  side_corners,
+  parse_navs,
+)
+
+class Multiplicity(Enum):
+  '''Move multiplicity.'''
+  CW = auto()
+  CCW = auto()
+  TWO = auto()
+
+# Inverse multiplicity: CW<->CCW, TWO is self-inverse.
+invert: dict[Multiplicity, Multiplicity] = {
+    Multiplicity.CW:  Multiplicity.CCW,
+    Multiplicity.CCW: Multiplicity.CW,
+    Multiplicity.TWO: Multiplicity.TWO,
+}
+
+@dataclass(frozen=True)
+class Move:
+  '''A face move: a side and a multiplicity.'''
+  face: Side
+  mult: Multiplicity
+
+restore_home: dict[tuple[Side, Multiplicity], list[Nav]] = {
+  (Side.FRONT, Multiplicity.CW): parse_navs('ONNO'),
+  (Side.FRONT, Multiplicity.CCW): parse_navs('NN'),
+  (Side.FRONT, Multiplicity.TWO): parse_navs('NNNN'),
+
+  (Side.LEFT, Multiplicity.CW): parse_navs('OONN'),
+  (Side.LEFT, Multiplicity.CCW): parse_navs('OONNOO'),
+  (Side.LEFT, Multiplicity.TWO): parse_navs('ONNNNOO'),
+
+  (Side.TOP, Multiplicity.CW): parse_navs('NNOO'),
+  (Side.TOP, Multiplicity.CCW): parse_navs('OONNO'),
+  (Side.TOP, Multiplicity.TWO): parse_navs('OONNNNO'),
+}
+
+def _move_corner(
+  cube: Cube, corner: CornerSticker, m: Multiplicity
+) -> None:
+  '''Rotate the face of a corner with given multiplicity.
+
+  Note: caller may need to restore cube.home afterwards.
+  '''
+  corners: list[CornerSticker] = side_corners(cube, corner)
+
+  corners_oo: list[CornerSticker] = [
+    c.other.other for c in corners
+  ]
+
+  edges_no: list[EdgeSticker] = [
+    cube.next_edge[c].other for c in corners_oo
+  ]
+
+  match m:
+    case Multiplicity.CW:
+      (
+        cube.next_edge[corners_oo[0]],
+        cube.next_edge[corners_oo[1]],
+        cube.next_edge[corners_oo[2]],
+        cube.next_edge[corners_oo[3]],
+      ) = (
+        cube.next_edge[corners_oo[1]],
+        cube.next_edge[corners_oo[2]],
+        cube.next_edge[corners_oo[3]],
+        cube.next_edge[corners_oo[0]],
+      )
+
+      (
+        cube.next_corner[edges_no[0]],
+        cube.next_corner[edges_no[1]],
+        cube.next_corner[edges_no[2]],
+        cube.next_corner[edges_no[3]],
+      ) = (
+        cube.next_corner[edges_no[3]],
+        cube.next_corner[edges_no[0]],
+        cube.next_corner[edges_no[1]],
+        cube.next_corner[edges_no[2]],
+      )
+
+    case Multiplicity.CCW:
+      (
+        cube.next_edge[corners_oo[0]],
+        cube.next_edge[corners_oo[1]],
+        cube.next_edge[corners_oo[2]],
+        cube.next_edge[corners_oo[3]],
+      ) = (
+        cube.next_edge[corners_oo[3]],
+        cube.next_edge[corners_oo[0]],
+        cube.next_edge[corners_oo[1]],
+        cube.next_edge[corners_oo[2]],
+      )
+
+      (
+        cube.next_corner[edges_no[0]],
+        cube.next_corner[edges_no[1]],
+        cube.next_corner[edges_no[2]],
+        cube.next_corner[edges_no[3]],
+      ) = (
+        cube.next_corner[edges_no[1]],
+        cube.next_corner[edges_no[2]],
+        cube.next_corner[edges_no[3]],
+        cube.next_corner[edges_no[0]],
+      )
+
+    case Multiplicity.TWO:
+      (
+        cube.next_edge[corners_oo[0]],
+        cube.next_edge[corners_oo[2]],
+      ) = (
+        cube.next_edge[corners_oo[2]],
+        cube.next_edge[corners_oo[0]],
+      )
+
+      (
+        cube.next_edge[corners_oo[1]],
+        cube.next_edge[corners_oo[3]],
+      ) = (
+        cube.next_edge[corners_oo[3]],
+        cube.next_edge[corners_oo[1]],
+      )
+
+      (
+        cube.next_corner[edges_no[0]],
+        cube.next_corner[edges_no[2]],
+      ) = (
+        cube.next_corner[edges_no[2]],
+        cube.next_corner[edges_no[0]],
+      )
+
+      (
+        cube.next_corner[edges_no[1]],
+        cube.next_corner[edges_no[3]],
+      ) = (
+        cube.next_corner[edges_no[3]],
+        cube.next_corner[edges_no[1]],
+      )
+
+def _move_home(cube: Cube, side: Side, m: Multiplicity) -> None:
+  '''Restore home pointer after a face move.'''
+  key: tuple[Side, Multiplicity] = (side, m)
+  if key in restore_home:
+    cube.home = nav_cc(restore_home[key], cube, cube.home)
+
+def move(m: Move, cube: Cube) -> None:
+  '''Rotate a face with given multiplicity.'''
+  corner: CornerSticker = corner_on_side(cube, m.face)
+  _move_corner(cube, corner, m.mult)
+  _move_home(cube, m.face, m.mult)
+
+def moved(m: Move, cube: Cube) -> Cube:
+  '''Return a new cube after rotating a face.'''
+  new: Cube = shallow_copy(cube)
+  move(m, new)
+  return new

cube_model/navigation.py

@@ -0,0 +1,155 @@
+'''Navigation algebra over cube stickers.'''
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from enum import Enum, auto
+from typing import cast
+
+from .model import Color, CornerSticker, Cube, EdgeSticker, Side, Sticker
+from .new_cube import solved
+
+class Nav(Enum):
+  '''Navigation steps: next or other.'''
+  NEXT = auto()
+  OTHER = auto()
+
+# A sequence of Nav steps, accepted as an argument to nav().
+type NavPath = Iterable[Nav]
+
+def nav(nav_path: NavPath | str, cube: Cube, sticker: Sticker) -> Sticker:
+  '''Apply a sequence of navigation steps.'''
+  steps: NavPath
+  if isinstance(nav_path, str):
+    steps = parse_navs(nav_path)
+  else:
+    steps = nav_path
+
+  current: Sticker = sticker
+  is_edge: bool = isinstance(current, EdgeSticker)
+  step: Nav
+  for step in steps:
+    match step:
+      case Nav.NEXT:
+        if is_edge:
+          current = cube.next_corner[cast(EdgeSticker, current)]
+        else:
+          current = cube.next_edge[cast(CornerSticker, current)]
+        is_edge = not is_edge
+      case Nav.OTHER:
+        current = current.other
+  return current
+
+def nav_cc(
+  nav_path: NavPath | str, cube: Cube, sticker: CornerSticker
+) -> CornerSticker:
+  '''Navigate corner to corner under even NEXT parity.'''
+  return cast(CornerSticker, nav(nav_path, cube, sticker))
+
+def parse_navs(text: str) -> list[Nav]:
+  '''Parse a string of N and O into navigation steps.'''
+  result: list[Nav] = []
+  ch: str
+  for ch in text:
+    match ch:
+      case 'N':
+        result.append(Nav.NEXT)
+      case 'O':
+        result.append(Nav.OTHER)
+      case _:
+        raise ValueError(f'invalid nav character: {ch!r}')
+  return result
+
+HOME_TO_SIDE: dict[Side, list[Nav]] = {
+  Side.FRONT: parse_navs(''),
+  Side.TOP: parse_navs('OO'),
+  Side.RIGHT: parse_navs('NNOO'),
+  Side.LEFT: parse_navs('O'),
+  Side.BOTTOM: parse_navs('ONNOO'),
+  Side.BACK: parse_navs('OONNOO'),
+}
+
+def corner_on_side(cube: Cube, side: Side) -> CornerSticker:
+  '''Return a representative corner sticker for a side.'''
+  return nav_cc(HOME_TO_SIDE[side], cube, cube.home)
+
+def side_corners(
+  cube: Cube, start: CornerSticker
+) -> list[CornerSticker]:
+  '''Return the four corners on the same side.'''
+  result: list[CornerSticker] = [start]
+  current: CornerSticker = start
+  for _ in range(3):
+    edge: EdgeSticker = cube.next_edge[current]
+    current = cube.next_corner[edge]
+    result.append(current)
+  return result
+
+def sticker_side(cube: Cube, sticker: Sticker) -> Side:
+  '''Return the side containing the given sticker.'''
+  corner: CornerSticker
+  if isinstance(sticker, EdgeSticker):
+    corner = cube.next_corner[sticker]
+  else:
+    corner = cast(CornerSticker, sticker)
+  corners: list[CornerSticker] = side_corners(cube, corner)
+  side: Side
+  path: list[Nav]
+  for side, path in HOME_TO_SIDE.items():
+    home_corner: CornerSticker = nav_cc(path, cube, cube.home)
+    if home_corner in corners:
+      return side
+  raise ValueError('sticker not found on any side')
+
+# --- precompute orientation tables ---
+
+_temp: Cube = solved()
+
+side_colors: dict[tuple[Color, Color, Side], Color] = {}
+
+corner: CornerSticker
+for corner in _temp.next_edge.keys():
+  s: CornerSticker = corner
+  for _ in range(3):
+    side: Side
+    path: list[Nav]
+    for side, path in HOME_TO_SIDE.items():
+      target: CornerSticker = nav_cc(path, _temp, s)
+      side_colors[(s.color, s.other.other.color, side)] = target.color
+    s = s.other
+
+color_sides: dict[tuple[Color, Color, Color], Side] = {
+  (a, b, c): side
+  for (a, b, side), c in side_colors.items()
+}
+
+del _temp
+
+def side_color(cube: Cube, side: Side) -> Color:
+  '''Return the color of a side.'''
+  return side_colors[(cube.front_color, cube.top_color, side)]
+
+def color_side(cube: Cube, color: Color) -> Side:
+  '''Return the side corresponding to a color.'''
+  return color_sides[(cube.front_color, cube.top_color, color)]
+
+def all_colors(cube: Cube) -> dict[Side, list[Color]]:
+  '''Return the eight outer sticker colors on each side in
+  clockwise order, beginning with corner that bounds on the
+  following other two sides:
+  front: left, top
+  top: front, left
+  right: front, top
+  left: top, front
+  bottom; left, front
+  back: top, left'''
+  result: dict[Side, list[Color]] = {}
+  side: Side
+  for side in Side:
+    st: Sticker = corner_on_side(cube, side)
+    colors: list[Color] = []
+    for _ in range(8):
+      colors.append(st.color)
+      st = nav([Nav.NEXT], cube, st)
+    result[side] = colors
+  return result