https://github.com/a6tvhmj/cubelibrary

Rubik's Cube solver in pure Python
https://github.com/a6tvhmj/cubelibrary

kociemba rubiks-cube rubiks-cube-solver ttkbootstrap two-phase-algorithm

Last synced: 24 days ago
JSON representation

Rubik's Cube solver in pure Python

• Host: GitHub
• URL: https://github.com/a6tvhmj/cubelibrary
• Owner: A6TVhmj
• License: gpl-3.0
• Created: 2026-05-10T07:10:18.000Z (about 2 months ago)
• Default Branch: main
• Last Pushed: 2026-05-16T10:42:10.000Z (about 1 month ago)
• Last Synced: 2026-05-29T09:38:13.755Z (26 days ago)
• Topics: kociemba, rubiks-cube, rubiks-cube-solver, ttkbootstrap, two-phase-algorithm
• Language: Python
• Homepage:
• Size: 391 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# CubeLibrary (CL)

**CubeLibrary**（简称 **cl**），是一个向 Herbert Kociemba 经典的 Delphi 版 **Cube Explorer** 致敬的现代化 Python 重制版。

本项目不仅利用 `ttkbootstrap` 赋予了原版等距视角（Isometric 3D）魔方编辑器极具现代感的全新 UI，更在底层**用纯 Python 从零重构了 Kociemba 的两阶段算法（Two-Phase Algorithm）**。结合现代化的多线程队列与内存优化，打造出了一个速度极快、功能极全的魔方极客工具箱。

## ✨ 全新核心特性 (Features)

* 🎨 **经典的 3D 展开图与 WCA 规范**：完美复刻原版视觉体验。支持左/右键快速填色、未知色块（`?`）标记。默认遵循 WCA 标准配色（白顶绿前），并内置自动推导面色（AutoFix）与全局自定义调色板。

* 🌍 **国际化与一秒换肤 (i18n & Themes)**：支持多语言**热切换**，无需重启瞬间生效！内置多种现代应用主题，一键切换暗黑/明亮模式。

* 🎲 **WCA 随机状态打乱生成器 (Random State Scrambler)**：拒绝低效的“随机乱转”。内置真正的状态打乱引擎，生成 100% 符合 WCA 比赛标准的 20 步完美逆向打乱公式。

* 🚀 **双核解算模式**：

  * **Two-Phase (Fast)**：极速模式，应用铁腕深度剪枝，瞬间给出最优的快解还原公式。

  * **Optimal (Slow)**：纯正的最少步（God's Number）死磕模式，绝对最短路径优先输出，自动向下兼容生成高质量次优解。

* 🧩 **残缺魔方模式探测 (Incomplete Search)**：

  * 支持输入带有未知色块的魔方状态。内置角/棱块排列穷举器与奇偶校验（Parity Check），自动过滤物理上无法还原的“错装状态”，输出所有数学合法的推导补全方案。

## ⚡️ 底层算法与工程黑科技 (Under the Hood)

与直接调用第三方封装库的 UI 套壳软件不同，**cl** 拥有完全自主掌控的底层计算引擎 CL Core，并实现了以下极限工程优化：

1. **突破 NumPy 循环封印（Bytes Casting 提速）**：

   在纯 Python 环境的 IDA* 高频循环中，引擎自动将百万量级的状态剪枝表转换为 **Python 原生 `bytes` 内存视图**，彻底消除 NumPy 装箱拆箱开销，寻路速度暴增 2~3 倍。

2. **真正的全局迭代加深（True Iterative Deepening）**：

   重构传统 Phase 1 深度迭代缺陷，**严格按“总步数”逐级展开搜索树**，确保列表最顶端输出的 100% 是数学意义上的绝对最短解。

3. **二阶回溯与物理剪枝（2-step Lookback Pruning）**：

   从底层物理规则上彻底封杀 `U D U'`、`R L R'` 合并等跨步抵消魔法，保证程序吐出的每一条次优解都是**饶了不同物理弯路的高含金量干货公式**，杜绝凑步数的垃圾废话。

4. **电竞级背压控制与异常刺穿（Backpressure & Exception Piercing）**：

   面对每秒成千上万的解法喷涌，采用 `Queue(maxsize=20)` 完美平衡毫秒级引擎算力与屏幕重绘；利用抛出 `StopSearchException` 刺穿深达 20 层的递归树，实现对后台计算引擎的 **0 延迟光速熔断**，彻底告别假死与僵尸线程。

## 🤝 贡献与许可

底层坐标转换与数学模型深受 Herbert Kociemba 先生论文及原始 Delphi 源码的启发，特此致敬。

鸣谢魔方速拧社区及相关算法极客在 Pattern Database 剪枝逻辑上的宝贵讨论。

本项目遵循 GPL-3.0 License 开源协议。如果您修改了本项目的核心算法或在其他软件中衍生使用了本项目代码，请保持同等开源并注明出处，共同促进魔方算法社区的繁荣！

欢迎提交 Issue 或 Pull Request 共同探讨高阶图论搜索算法！