cube-model 1.0.3__tar.gz

cube_model-1.0.3/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: cube-model
+Version: 1.0.3
+Summary: Orientation-independent cube model in strictly typed Python
+Author: Yitzchak Gale
+Author-email: gale@sefer.org
+Requires-Python: >=3.13,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Project-URL: Homepage, https://github.com/ygale/cube-model
+Project-URL: Repository, https://github.com/ygale/cube-model
+Description-Content-Type: text/markdown
+
+# cube-model
+
+An orientation-independent cube model in strictly typed Python.
+
+## Highlights
+
+- Strict typing (`mypy --strict`)
+- Orientation-independent cube state
+- `Color` and `Side` are enums
+- `CornerSticker` objects form circular linked lists of size 3
+- `EdgeSticker` objects form circular linked lists of size 2
+- `Cube.next_edge` and `Cube.next_corner` encode clockwise sticker order on faces
+
+## Install
+
+```bash
+pip install cube-model
+```
+
+## Example
+
+```python
+from cube_model import Color, Move, Multiplicity, Side, solved, move
+
+cube = solved()
+assert cube.front_color is Color.GREEN
+
+move(Move(Side.FRONT, Multiplicity.CW), cube)
+```
+
+

cube_model-1.0.3/README.md

@@ -0,0 +1,30 @@
+# cube-model
+
+An orientation-independent cube model in strictly typed Python.
+
+## Highlights
+
+- Strict typing (`mypy --strict`)
+- Orientation-independent cube state
+- `Color` and `Side` are enums
+- `CornerSticker` objects form circular linked lists of size 3
+- `EdgeSticker` objects form circular linked lists of size 2
+- `Cube.next_edge` and `Cube.next_corner` encode clockwise sticker order on faces
+
+## Install
+
+```bash
+pip install cube-model
+```
+
+## Example
+
+```python
+from cube_model import Color, Move, Multiplicity, Side, solved, move
+
+cube = solved()
+assert cube.front_color is Color.GREEN
+
+move(Move(Side.FRONT, Multiplicity.CW), cube)
+```
+

cube_model-1.0.3/pyproject.toml

@@ -0,0 +1,28 @@
+[tool.poetry]
+name = "cube-model"
+version = "1.0.3"
+description = "Orientation-independent cube model in strictly typed Python"
+authors = ["Yitzchak Gale <gale@sefer.org>"]
+readme = "README.md"
+packages = [{ include = "cube_model", from = "src" }]
+include = [{ path = "src/cube_model/py.typed", format = ["sdist", "wheel"] }]
+homepage = "https://github.com/ygale/cube-model"
+repository = "https://github.com/ygale/cube-model"
+
+[tool.poetry.dependencies]
+python = ">=3.13,<4.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+
+[build-system]
+requires = ["poetry-core>=1.9.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+mypy_path = ["src", "tests"]
+explicit_package_bases = true

cube_model-1.0.3/src/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-1.0.3/src/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-1.0.3/src/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-1.0.3/src/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