alphacube 0.1.0__tar.gz

alphacube-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 1.2
+Name: alphacube
+Version: 0.1.0
+Summary: A powerful & flexible Rubik's Cube solver
+Home-page: https://alphacube.dev/
+Author: Kyo Takano
+License: MIT
+Project-URL: Documentation, https://alphacube.dev/docs/index.html
+Project-URL: Source, https://github.com/kyo-takano/alphacube
+Description: UNKNOWN
+Platform: UNKNOWN
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >= 3.6

alphacube-0.1.0/README.md

@@ -0,0 +1,168 @@
+# AlphaCube
+
+AlphaCube is a powerful & flexible Rubik's Cube solver that extends [EfficientCube](https://github.com/kyo-takano/efficientcube).
+
+## App
+
+We offer an interactive demo application for you to try out AlphaCube:
+[alphacube.dev](https://alphacube.dev)
+
+## Installation
+
+Open a terminal and execute the following command:
+
+```sh
+pip install alphacube
+```
+
+## Usage
+
+### Basic
+
+Using AlphaCube in Python is as simple as this:
+
+```python
+import alphacube
+
+# Load a trained DNN
+alphacube.load(model_id="small") # the default model
+
+# Solve the cube using a given scramble
+result = alphacube.solve(
+    scramble="D U F2 L2 U' B2 F2 D L2 U R' F' D R' F' U L D' F' D R2",
+    beam_width=1024,
+)
+print(result)
+```
+
+> **Output**
+> ```python
+> {
+>     'solutions': [
+>         "D L D2 R' U2 D B' D' U2 B U2 B' U' B2 D B2 D' B2 F2 U2 F2"
+>     ],
+>     'num_nodes': 19744,
+>     'time':1.4068585219999659
+> }
+> ```
+
+AlphaCube selects the smallest model by default and takes about a few seconds to find moderately good solution(s).
+
+### Better Solutions
+
+If you want even shorter solutions, simply increase the `beam_width` parameter:
+
+```python
+alphacube.load() # model_id="small"
+result = alphacube.solve(
+    scramble="D U F2 L2 U' B2 F2 D L2 U R' F' D R' F' U L D' F' D R2",
+    beam_width=65536,
+)
+print(result)
+```
+
+> **Output**
+> ```python
+> {
+>     'solutions': [
+>         "D' R' D2 F' L2 F' U B F D L D' L B D2 R2 F2 R2 F'",
+>         "D2 L2 R' D' B D2 B' D B2 R2 U2 L' U L' D' U2 R' F2 R'"
+>     ],
+>     'num_nodes': 968984,
+>     'time': 45.690575091997744
+> }
+> ```
+
+You generally get more and better solutions, at the sacrifice of an increased wall-clock time and computational cost.
+
+### Applying Ergonomic Bias
+
+```python
+ergonomic_bias = {
+    "U": 0.9,   "U'": 0.9,  "U2": 0.8,
+    "R": 0.8,   "R'": 0.8,  "R2": 0.75,
+    "L": 0.55,  "L'": 0.4,  "L2": 0.3,
+    "F": 0.7,   "F'": 0.6,  "F2": 0.6,
+    "D": 0.3,   "D'": 0.3,  "D2": 0.2,
+    "B": 0.05,  "B'": 0.05, "B2": 0.01,
+    "u": 0.45,  "u'": 0.45, "u2": 0.4,
+    "r": 0.3,   "r'": 0.3,  "r2": 0.25,
+    "l": 0.2,   "l'": 0.2,  "l2": 0.15,
+    "f": 0.35,  "f'": 0.3,  "f2": 0.25,
+    "d": 0.15,  "d'": 0.15, "d2": 0.1,
+    "b": 0.03,  "b'": 0.03, "b2": 0.01
+} # Each value represents the desirability score
+
+result = alphacube.solve(
+    scramble="D U F2 L2 U' B2 F2 D L2 U R' F' D R' F' U L D' F' D R2",
+    beam_width=65536,
+    ergonomic_bias=ergonomic_bias
+)
+print(result)
+```
+
+> **Output**
+> ```python
+> {
+>     'solutions': [
+>         "u' U' f' R2 U2 R' L' F' R D2 f2 R2 U2 R U L' U R L",
+>         "u' U' f' R2 U2 R' L' F' R D2 f2 R2 U2 R d F' U f F",
+>         "u' U' f' R2 U2 R' L' F' R u2 F2 R2 D2 R u f' l u U"
+>     ],
+>     'num_nodes': 1078054,
+>     'time': 56.13087955299852
+> }
+> ```
+
+### GPU Acceleration
+
+If you have a GPU, we highly recommend you select the largest model for the best possible performance:
+
+```python
+alphacube.load(model_id="large")
+result = alphacube.solve(
+    scramble="D U F2 L2 U' B2 F2 D L2 U R' F' D R' F' U L D' F' D R2",
+    beam_width=65536,
+)
+print(result)
+```
+
+> **Output**
+> ```python
+> {
+>     'solutions': ["D F L' F' U2 B2 U F' L R2 B2 U D' F2 U2 R D'"],
+>     'num_nodes': 903448,
+>     'time': 20.46845487099995
+> }
+> ```
+
+You will get even better solutions in an order of magnitude smaller amount of time.
+
+On the contrary, using a model larger than `"small"` (i.e., `"base"` or `"large"`) *on CPU* will likely result in inferior temporal performance.
+
+### Verbose Mode
+
+Additionally, you may call `alphacube.set_verbose()` to keep track of the progress. It will display the current depth of search on your terminal.
+
+Please refer to our [documentation](https://alphacube.dev/docs) for more, especially ["Getting Started"](https://alphacube.dev/docs/getting-started/index.html)
+
+## How It Works
+
+At the heart of AlphaCube lies a methodology rooted in the paper titled ["Self-Supervision is All You Need for Solving Rubik's Cube" (TMLR'23)](https://openreview.net/forum?id=bnBeNFB27b), the official code of which is also available as a [GitHub repository](https://github.com/kyo-takano/efficientcube).
+This project releases the three largest solvers trained in Half-Turn Metric (HTM) as described in **Section 7. Scaling Law**.
+
+In EfficientCube, a Deep Neural Network (DNN) is trained to predict the **probability distribution of the next moves** that would bring a given state one step closer to the goal. 
+These predicted moves are then applied sequentially to solve a given scramble.
+
+This project releases the three largest, compute-optimally trained solvers as described in **Section 7. Scaling Law**.
+
+You may also read ["How It Works"](https://alphacube.dev/docs/how-it-works/index.html) in the documentation for illustrated descriptions.
+
+## Contributing
+
+You are more than welcome to collaborate on AlphaCube.
+If you're interested, please read our [CONTRIBUTING](https://github.com/kyo-takano/alphacube/CONTRIBUTING.md) guide to get started.
+
+## License
+
+AlphaCube is open-sourced under the [MIT license](https://github.com/kyo-takano/alphacube/LICENSE), granting you the freedom to use and modify it.

alphacube-0.1.0/alphacube/__init__.py

@@ -0,0 +1,161 @@
+"""
+This package provides functions to load a deep neural Rubik's Cube solver (DNN) and to solve a scrambled Rubik's Cube with it.
+It also offers a command-line utility for solving a Rubik's Cube using AlphaCube.
+
+Functions:
+
+- ``load(*args, **kwargs)``: Load a trained DNN.
+- ``solve(*args, **kwargs)``: Solve a Rubik's Cube using the loaded solver.
+- ``cli()``: Command-line utility for solving a Rubik's Cube using AlphaCube.
+- ``set_verbose(loglevel=logging.INFO)``: Set the verbosity level of the logger.
+
+Example::
+
+    import alphacube
+    alphacube.load(model_id="base")
+    solution = alphacube.solve(format='moves', scramble="R U R' U'", beam_width=1024)
+
+"""
+import logging
+from rich.console import Console
+from rich.logging import RichHandler
+
+logger = logging.getLogger("rich")
+logger.propagate = False
+logger.addHandler(RichHandler(console=Console(stderr=True)))
+logger.setLevel(logging.WARNING)
+logargs = dict(extra={"markup": True})
+
+# Set up logging level
+def set_verbose(loglevel=logging.INFO):
+    """
+    Set the verbosity level of the logger.
+
+    Args:
+        loglevel (int): Logging level (e.g., logging.INFO, logging.DEBUG) to control the verbosity.
+
+    Returns:
+        None
+    """
+    global logger
+    logger.setLevel(loglevel)
+    
+from ._validator import Input
+from .solver import Solver
+
+_solver = Solver()
+
+def load(*args, **kwargs):
+    """
+    Load the Rubik's Cube solver model.
+
+    Args:
+        *args, **kwargs: Arguments to configure model loading.
+
+    Returns:
+        None
+    """
+    _solver.load(*args, **kwargs)
+
+def solve(*args, **kwargs):
+    """
+    Solve a Rubik's Cube puzzle using the loaded solver model.
+
+    Args:
+        *args, **kwargs: Arguments to configure puzzle solving; passed down to ``alphacube.solver.Solver.__call__()`` and ``alphacube.search.beam_search``.
+
+    Returns:
+        dict | None: A dictionary containing solutions and performance metrics. None if failed.
+    """
+    if _solver.model is None:
+        raise ValueError('Model not loaded. Call `load` with appropriate arguments first.')
+
+    return _solver(*args, **kwargs)
+
+# CLI Option
+def cli():
+    """
+    Command-line utility for solving a Rubik's Cube using AlphaCube.
+
+    Usage::
+
+        alphacube [--model_id MODEL_ID] [--format FORMAT] [--scramble SCRAMBLE]
+                [--beam_width BEAM_WIDTH] [--extra_depths EXTRA_DEPTHS]
+
+    Command-line Arguments:
+
+    * ``--model_id``, ``-m`` (str): Choose a specific model for solving (default: 'small').
+    * ``--format``, ``-f`` (str): Specify the input format ('moves' or 'stickers').
+    * ``--scramble``, ``-s`` (str): Define the initial cube state using either a sequence of moves or a stringify JSON dictionary.
+    * ``--beam_width``, ``-bw`` (int): Set the beam width for search (default: 1024).
+    * ``--extra_depths``, ``-ex`` (int): Specify additional depths for exploration (default: 0).
+    * ``--verbose``, ``-v``: Enable verbose output for debugging and tracking progress.
+
+    Example Usages:
+
+    1. Solve a cube using default settings::
+
+        alphacube --scramble "R U R' U'"
+
+    2. Solve a cube with custom settings::
+
+        alphacube --model_id large --beam_width 128 --extra_depths 2 \\
+                --scramble "R U2 F' R2 B R' U' L B2 D' U2 R F L"
+
+    3. Solve a cube using a sticker representation::
+
+        alphacube --format stickers \\
+                --scramble '{ \\
+                    "U": [0, 0, 5, 5, 0, 5, 5, 4, 0], \\
+                    "D": [1, 3, 3, 4, 1, 1, 4, 1, 3], \\
+                    "L": [4, 5, 1, 0, 2, 2, 0, 1, 4], \\
+                    "R": [5, 2, 0, 2, 3, 3, 2, 0, 2], \\
+                    "F": [4, 3, 2, 4, 5, 1, 1, 4, 3], \\
+                    "B": [1, 5, 5, 0, 4, 3, 3, 2, 2] \\
+                }' \\
+                --beam_width 64
+
+    :return: None
+    """
+    from rich import print
+
+    import argparse
+    parser = argparse.ArgumentParser(description="AlphaCube -- State-of-the-Art Rubik's Cube Solver")
+    parser.add_argument("--model_id", "-m", type=str, default="small", help="ID of the model to solve a given scramble with (`small`, `base`, or `large`)")
+    parser.add_argument("--format", "-f", type=str, default="moves", help="Format of the input scramble (`moves` or `stickers`)")
+    parser.add_argument("--scramble", "-s", type=str, help="Sequence of scramble in HTM (including wide moves) or dictionary of sticker indices by face.")
+    parser.add_argument("--beam_width", "-bw", type=int, default=1024, help="Beam width, the parameter strongly correlated with solution optimality and computation time")
+    parser.add_argument("--extra_depths", "-ex", type=int, default=0, help="Number of additional depths to explore during the search")
+    parser.add_argument('--verbose', '-v', dest="loglevel", action="store_const", const=logging.INFO, help="Enable verbose output for tracking progress")
+    args = parser.parse_args()
+
+    if args.loglevel:
+        set_verbose(args.loglevel)
+
+    # Manual validation
+    model_id = args.model_id
+    assert model_id in ["small", "base","large"], "Model ID must be either 'base' or 'large'"
+
+    logger.info(args)
+    
+    # Pydantic validation
+    args = Input(
+        format=args.format,
+        scramble=args.scramble,
+        beam_width=args.beam_width,
+        extra_depths=args.extra_depths,
+        ergonomic_bias=None
+    )
+        
+    # Load only once validated
+    _solver.load(model_id=model_id)
+    # Solve
+    solutions = _solver(
+        format=args.format,
+        scramble=args.scramble,
+        beam_width=args.beam_width,
+        extra_depths=args.extra_depths
+    )
+    print(solutions)
+
+__all__ = ['load', 'solve', "cli"]

alphacube-0.1.0/alphacube/_validator.py

@@ -0,0 +1,149 @@
+"""
+Input Validator
+
+This module defines the input validator for the AlphaCube application. It includes a Pydantic `Input` class that validates input data for the application's tasks. The input data must adhere to specific format and validation rules.
+
+Validation Rules:
+
+- ``format`` attribute must be either 'moves' or 'stickers'.
+    - For 'moves' format, the `scramble` attribute must consist of valid moves.
+    - For 'stickers' format (not implemented), additional validation may be performed.
+- ``beam_width`` attribute must be a positive integer.
+- ``extra_depths`` attribute must be a non-negative integer.
+
+Usage Example::
+
+    input_data = {
+        'format': 'moves',
+        'scramble': "R U R' U'",
+        'beam_width': 256,
+        'extra_depths': 2,
+        'ergonomic_bias': None
+    }
+    validated_input = Input(**input_data)
+
+Note: 
+
+    The ergonomic bias information is optional and not strictly validated.
+
+"""
+
+from pydantic import BaseModel, validator, model_validator
+from typing import Optional
+import json
+import re
+
+class Input(BaseModel):
+    """
+    Input validator (& preprocessor) for AlphaCube.
+    """
+
+    format: str                     # The format of the input data. Must be either 'moves' or 'stickers'.
+    scramble: list                  # The scramble data in the specified format.
+    beam_width: int                 # The beam width for the task. Must be a positive integer.
+    extra_depths: int               # The number of extra depths for the task. Must be a non-negative integer.
+    ergonomic_bias: Optional[dict]  # Optional ergonomic bias information (not strictly validated).
+
+    @validator('format')
+    @classmethod
+    def validate_format(cls, value: str) -> str:
+        """
+        Validate the input format.
+
+        Args:
+            value (str): The format value to be validated.
+
+        Returns:
+            str: The validated format value.
+
+        Raises:
+            ValueError: If the format is not 'moves' or 'stickers'.
+        """
+        if value not in ["moves", "stickers"]:
+            raise ValueError("Invalid input format. Must be either 'moves' or 'stickers'.")
+        return value
+
+    @validator("beam_width")
+    @classmethod
+    def validate_beam_width(cls, value):
+        """
+        Validate the beam width.
+
+        Args:
+            value: The beam width value to be validated.
+
+        Returns:
+            int: The validated beam width value.
+
+        Raises:
+            ValueError: If the beam width is not a positive integer.
+        """
+        if value <= 0:
+            raise ValueError("Beam width must be a positive integer.")
+        return value
+
+    @validator("extra_depths")
+    @classmethod
+    def validate_extra_depths(cls, value):
+        """
+        Validate the extra depths.
+
+        Args:
+            value: The extra depths value to be validated.
+
+        Returns:
+            int: The validated extra depths value.
+
+        Raises:
+            ValueError: If the extra depths value is negative.
+        """
+        if value < 0:
+            raise ValueError("Extra depths must be a non-negative integer.")
+        return value
+
+    @model_validator(mode='before')
+    @classmethod
+    def validate_scramble(cls, values):
+        """
+        Validate & preprocess the scramble data based on the chosen format.
+
+        Args:
+            values (dict): The input values.
+
+        Returns:
+            dict: The input values with validated scramble data.
+
+        Raises:
+            ValueError: If there are invalid moves in 'scramble' for 'moves' format.
+            ValueError: If unexpected center-piece configuration in 'scramble' for 'stickers' format (not implemented).
+
+        Todo: 
+            Also check for potential orientation, permutation, parity
+        """
+
+        format = values["format"]
+        scramble = values["scramble"]
+
+        if format == "moves":
+            if isinstance(scramble, str):
+                scramble = scramble.split()
+            scramble = [m.replace("2'", "2") for m in scramble]
+            invalid_moves = [m for m in scramble if not re.match(r"^[UDLRFBudlrfb'2]{1,2}$", m)]  # no wide moves -- yet
+            if invalid_moves:
+                raise ValueError(f"Invalid move{'s' if len(invalid_moves) > 1 else ''} in `scramble`: {invalid_moves}")
+        elif format == "stickers":
+            if isinstance(scramble, str):
+                scramble = json.loads(scramble.replace("\\\n", ""))
+            if isinstance(scramble, dict): 
+                sticker_colors = [scramble[face] for face in "UDLRBF"]
+                # Reset axes if centers are modified
+                center_indices = [stickers[4] for stickers in sticker_colors]
+                if sorted(center_indices) != list(range(6)):
+                    raise ValueError('Unexpected center-piece configuration.')
+                # Deconstruct a dict of lists to a flat list
+                scramble = sum(sticker_colors, [])
+
+        # Update
+        values["scramble"] = scramble
+
+        return values