qsl-quantum 0.1.0__tar.gz

qsl_quantum-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Song Ziming
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qsl_quantum-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: qsl-quantum
+Version: 0.1.0
+Summary: Quantum Search Language - DSL for Grover search with simulator and IBM Quantum backends
+Home-page: https://gitee.com/song_jack/qsl
+Author: Song Ziming
+Author-email: Song Ziming <15011462616@163.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ibm
+Requires-Dist: qiskit>=1.0.0; extra == "ibm"
+Requires-Dist: qiskit-aer>=0.14.0; extra == "ibm"
+Requires-Dist: qiskit-ibm-runtime>=0.20.0; extra == "ibm"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+<h1 align="center">QSL &mdash; 量子搜索语言</h1>
+
+<p align="center">
+  <b>用一句话描述你想找什么，剩下的交给量子计算。</b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.9+-blue?logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/License-MIT-green" alt="License">
+  <img src="https://img.shields.io/badge/tests-123%20passed-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/dependencies-zero-success" alt="Dependencies">
+</p>
+
+---
+
+## 这是什么？
+
+一个 **Python 库**，让你用日常的布尔表达式描述搜索条件，自动在量子计算机（或本地模拟器）上找到答案。
+
+> 传统做法：手写量子电路，理解 H 门、CNOT 门、相位翻转……  
+> QSL 的做法：写 `x0 & ~x1`，然后等结果。
+
+---
+
+## 5 秒看懂
+
+```python
+from qsl import QSLProgram, compile_and_run
+
+# 我想找：3 个变量中，哪些赋值同时满足这三个条件？
+program = QSLProgram(
+    name="3-SAT",
+    n_qubits=3,
+    premises=[
+        "x0 | ~x1",    # x0 为真，或者 x1 为假
+        "x1 | x2",     # x1 为真，或者 x2 为真
+        "~x0 | ~x2",   # x0 为假，或者 x2 为假
+    ],
+    shots=10
+)
+
+result = compile_and_run(program)
+print(result.get_solutions())
+```
+
+**输出：**
+
+```
+[3, 4]   # 即二进制 011 和 100 —— 这两个就是答案
+```
+
+就这么简单。不需要懂量子力学。
+
+---
+
+## 两种运行模式
+
+| 模式 | 说明 | 需要什么 |
+|------|------|----------|
+| **本地模拟** | 在你的电脑上模拟量子计算 | 零依赖，纯 Python |
+| **真实硬件** | 连接 IBM 量子计算机跑真任务 | `pip install qsl-quantum[ibm]` + IBM 账号 |
+
+```python
+# 模式 1：本地模拟（默认）
+compiler = QSLCompiler(backend="simulator")
+result = compiler.compile_and_run(program)
+
+# 模式 2：IBM 真实量子芯片
+compiler = QSLCompiler(backend="ibm", backend_options={"token": "your_token"})
+result = compiler.compile_and_run(program)
+```
+
+---
+
+## 还能更简单 —— DSL 文本语法
+
+不想写 Python？用配置文件式的文本语法：
+
+```text
+program "图着色" {
+    qubits: 3
+
+    premise {
+        x0 ^ x1       # 相邻顶点不能同色
+        x1 ^ x2
+    }
+
+    main {
+        algorithm: grover
+        shots: 10
+    }
+}
+```
+
+```python
+from qsl import parse_qsl, compile_and_run
+
+source = open("problem.qsl").read()
+program = parse_qsl(source)
+result = compile_and_run(program)
+```
+
+---
+
+## 它能做什么？
+
+用布尔表达式描述**任意搜索约束**，QSL 自动找到所有满足条件的解：
+
+| 实际问题 | 布尔表达式 | 说明 |
+|----------|-----------|------|
+| SAT 求解 | `x0 \| ~x1` | 逻辑可满足性 |
+| 图着色 | `x0 ^ x1` | 相邻顶点不同色 |
+| 约束满足 | `x0 & ~x1 & x2` | 精确约束条件 |
+| 组合优化 | `(x0&x1) \| (x2&x3)` | 任意布尔函数 |
+
+**支持全部逻辑运算符：** `&`（与） `|`（或） `^`（异或） `~`（非） `()`（括号）
+
+---
+
+## 安装
+
+```bash
+pip install qsl-quantum
+```
+
+> 核心部分零外部依赖。只有在使用 IBM 真实硬件时才需要 `qiskit`。
+
+---
+
+## 为什么用 Grover 算法？
+
+| | 经典搜索 | QSL（Grover） |
+|------|----------|---------------|
+| 搜索 N 个可能 | 查 N 次 | 查约 &radic;N 次 |
+| 256 个状态 | 最多查 256 次 | 约 16 次 |
+| 1024 个状态 | 最多查 1024 次 | 约 32 次 |
+| 百万级 | 不可行 | 约 1000 次 |
+
+> 搜索空间越大，优势越明显。这是量子计算为数不多已被**数学证明**比经典算法快的场景。
+
+---
+
+## 项目结构
+
+```
+qsl/
+├── core/           量子态、布尔解析、Grover 算法
+├── compiler/       编译器 + DSL 解析器
+├── backends/       模拟器后端 + IBM 后端
+└── utils/          异常体系、输入验证
+tests/              123 个测试用例
+```
+
+---
+
+## 运行测试
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v        # 123 passed
+```
+
+---
+
+## 作者
+
+宋梓铭 &middot; [Gitee](https://gitee.com/song-jack/qsl) &middot; 15011462616@163.com
+
+---
+
+## 许可证
+
+MIT &mdash; 随意使用、修改、分发。

qsl_quantum-0.1.0/README.md

@@ -0,0 +1,173 @@
+<h1 align="center">QSL &mdash; 量子搜索语言</h1>
+
+<p align="center">
+  <b>用一句话描述你想找什么，剩下的交给量子计算。</b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.9+-blue?logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/License-MIT-green" alt="License">
+  <img src="https://img.shields.io/badge/tests-123%20passed-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/dependencies-zero-success" alt="Dependencies">
+</p>
+
+---
+
+## 这是什么？
+
+一个 **Python 库**，让你用日常的布尔表达式描述搜索条件，自动在量子计算机（或本地模拟器）上找到答案。
+
+> 传统做法：手写量子电路，理解 H 门、CNOT 门、相位翻转……  
+> QSL 的做法：写 `x0 & ~x1`，然后等结果。
+
+---
+
+## 5 秒看懂
+
+```python
+from qsl import QSLProgram, compile_and_run
+
+# 我想找：3 个变量中，哪些赋值同时满足这三个条件？
+program = QSLProgram(
+    name="3-SAT",
+    n_qubits=3,
+    premises=[
+        "x0 | ~x1",    # x0 为真，或者 x1 为假
+        "x1 | x2",     # x1 为真，或者 x2 为真
+        "~x0 | ~x2",   # x0 为假，或者 x2 为假
+    ],
+    shots=10
+)
+
+result = compile_and_run(program)
+print(result.get_solutions())
+```
+
+**输出：**
+
+```
+[3, 4]   # 即二进制 011 和 100 —— 这两个就是答案
+```
+
+就这么简单。不需要懂量子力学。
+
+---
+
+## 两种运行模式
+
+| 模式 | 说明 | 需要什么 |
+|------|------|----------|
+| **本地模拟** | 在你的电脑上模拟量子计算 | 零依赖，纯 Python |
+| **真实硬件** | 连接 IBM 量子计算机跑真任务 | `pip install qsl-quantum[ibm]` + IBM 账号 |
+
+```python
+# 模式 1：本地模拟（默认）
+compiler = QSLCompiler(backend="simulator")
+result = compiler.compile_and_run(program)
+
+# 模式 2：IBM 真实量子芯片
+compiler = QSLCompiler(backend="ibm", backend_options={"token": "your_token"})
+result = compiler.compile_and_run(program)
+```
+
+---
+
+## 还能更简单 —— DSL 文本语法
+
+不想写 Python？用配置文件式的文本语法：
+
+```text
+program "图着色" {
+    qubits: 3
+
+    premise {
+        x0 ^ x1       # 相邻顶点不能同色
+        x1 ^ x2
+    }
+
+    main {
+        algorithm: grover
+        shots: 10
+    }
+}
+```
+
+```python
+from qsl import parse_qsl, compile_and_run
+
+source = open("problem.qsl").read()
+program = parse_qsl(source)
+result = compile_and_run(program)
+```
+
+---
+
+## 它能做什么？
+
+用布尔表达式描述**任意搜索约束**，QSL 自动找到所有满足条件的解：
+
+| 实际问题 | 布尔表达式 | 说明 |
+|----------|-----------|------|
+| SAT 求解 | `x0 \| ~x1` | 逻辑可满足性 |
+| 图着色 | `x0 ^ x1` | 相邻顶点不同色 |
+| 约束满足 | `x0 & ~x1 & x2` | 精确约束条件 |
+| 组合优化 | `(x0&x1) \| (x2&x3)` | 任意布尔函数 |
+
+**支持全部逻辑运算符：** `&`（与） `|`（或） `^`（异或） `~`（非） `()`（括号）
+
+---
+
+## 安装
+
+```bash
+pip install qsl-quantum
+```
+
+> 核心部分零外部依赖。只有在使用 IBM 真实硬件时才需要 `qiskit`。
+
+---
+
+## 为什么用 Grover 算法？
+
+| | 经典搜索 | QSL（Grover） |
+|------|----------|---------------|
+| 搜索 N 个可能 | 查 N 次 | 查约 &radic;N 次 |
+| 256 个状态 | 最多查 256 次 | 约 16 次 |
+| 1024 个状态 | 最多查 1024 次 | 约 32 次 |
+| 百万级 | 不可行 | 约 1000 次 |
+
+> 搜索空间越大，优势越明显。这是量子计算为数不多已被**数学证明**比经典算法快的场景。
+
+---
+
+## 项目结构
+
+```
+qsl/
+├── core/           量子态、布尔解析、Grover 算法
+├── compiler/       编译器 + DSL 解析器
+├── backends/       模拟器后端 + IBM 后端
+└── utils/          异常体系、输入验证
+tests/              123 个测试用例
+```
+
+---
+
+## 运行测试
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v        # 123 passed
+```
+
+---
+
+## 作者
+
+宋梓铭 &middot; [Gitee](https://gitee.com/song-jack/qsl) &middot; 15011462616@163.com
+
+---
+
+## 许可证
+
+MIT &mdash; 随意使用、修改、分发。

qsl_quantum-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=64.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qsl-quantum"
+version = "0.1.0"
+description = "Quantum Search Language - DSL for Grover search with simulator and IBM Quantum backends"
+authors = [
+    {name = "Song Ziming", email = "15011462616@163.com"}
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+ibm = [
+    "qiskit>=1.0.0",
+    "qiskit-aer>=0.14.0",
+    "qiskit-ibm-runtime>=0.20.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+qsl = "qsl.__main__:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.setuptools.packages.find]
+exclude = ["tests", "tests.*"]

qsl_quantum-0.1.0/qsl/__init__.py

@@ -0,0 +1,59 @@
+"""
+QSL - Quantum Search Language
+=============================
+
+基于"前提-工具-问题-主函数"框架的量子搜索领域专用语言。
+
+两种运行模式:
+    1. 经典模拟器 (默认) - 零外部依赖，本地运行
+    2. IBM 量子计算机 - 需要 qiskit，在真实量子硬件上执行
+
+快速开始:
+    >>> from qsl import QSLProgram, QSLCompiler
+    >>> program = QSLProgram(
+    ...     name="我的搜索问题",
+    ...     n_qubits=3,
+    ...     premises=["x0 & x1", "~x2 | x0"],
+    ...     shots=10
+    ... )
+    >>> compiler = QSLCompiler()  # 默认模拟器后端
+    >>> result = compiler.compile_and_run(program)
+
+数学基础:
+    Grover 搜索: O(sqrt(N)) vs 经典 O(N)
+    布尔表达式 -> 量子 Oracle 自动编译
+"""
+
+__version__ = "1.0.0"
+__author__ = "Song Ziming"
+__email__ = "15011462616@163.com"
+
+# 公共 API
+from .compiler.program import QSLProgram
+from .compiler.compiler import QSLCompiler, compile_and_run, analyze
+from .compiler.dsl import parse_qsl
+from .core.parser import parse_bool
+from .core.state import QuantumState
+from .core.grover import GroverSearch, GroverResult
+from .backends.registry import list_backends, get_backend
+from .backends.simulator import SimulatorBackend
+
+__all__ = [
+    # 核心 API
+    "QSLProgram",
+    "QSLCompiler",
+    "compile_and_run",
+    "analyze",
+    "parse_qsl",
+    "parse_bool",
+    # 量子底层
+    "QuantumState",
+    "GroverSearch",
+    "GroverResult",
+    # 后端
+    "SimulatorBackend",
+    "list_backends",
+    "get_backend",
+    # 元数据
+    "__version__",
+]

qsl_quantum-0.1.0/qsl/__main__.py

@@ -0,0 +1,134 @@
+"""
+QSL 命令行入口。
+
+使用:
+    python -m qsl              # 交互式选择示例
+    python -m qsl --demo 1     # 运行指定示例
+"""
+
+import sys
+
+
+def main():
+    """命令行主入口。"""
+    from qsl import QSLProgram, QSLCompiler, parse_qsl
+
+    if len(sys.argv) > 1 and sys.argv[1] == "--demo":
+        run_demo()
+    elif len(sys.argv) > 1 and sys.argv[1] == "--help":
+        print_help()
+    else:
+        run_interactive()
+
+
+def print_help():
+    print("""
+QSL - Quantum Search Language
+=============================
+
+用法:
+    python -m qsl             交互式模式
+    python -m qsl --demo 1    运行指定示例
+    python -m qsl --help      显示此帮助
+""")
+    print("""
+Python API:
+    >>> from qsl import QSLProgram, QSLCompiler
+    >>> program = QSLProgram(
+    ...     name="我的搜索问题",
+    ...     n_qubits=4,
+    ...     premises=["x0 & x1", "~x2 | x3"],
+    ...     shots=10
+    ... )
+    >>> compiler = QSLCompiler(backend="simulator")
+    >>> result = compiler.compile_and_run(program)
+""")
+
+
+def run_demo():
+    print("\n" + "=" * 60)
+    print("  QSL - Quantum Search Language v1.0.0")
+    print("  Grover 量子搜索演示")
+    print("=" * 60)
+
+    from qsl import QSLProgram, QSLCompiler
+
+    # 内嵌示例
+    demos = {
+        "1": ("SAT 求解 (n=3)", QSLProgram(
+            name="3-SAT 求解",
+            n_qubits=3,
+            premises=["x0 | ~x1", "x1 | x2", "~x0 | ~x2"],
+            shots=5,
+        )),
+        "2": ("图着色 (3顶点2色)", QSLProgram(
+            name="图着色",
+            n_qubits=3,
+            premises=["x0 ^ x1", "x1 ^ x2"],
+            shots=5,
+        )),
+        "3": ("恰好一个1 (n=3)", QSLProgram(
+            name="恰好一个1",
+            n_qubits=3,
+            premises=["x0 | x1 | x2", "~x0 | ~x1", "~x0 | ~x2", "~x1 | ~x2"],
+            shots=5,
+        )),
+        "4": ("大空间搜索 (n=6)", QSLProgram(
+            name="大空间搜索",
+            n_qubits=6,
+            premises=["~(x0 ^ x1 ^ x2)", "x3 | x4", "x5"],
+            shots=3,
+        )),
+    }
+
+    print("\n可用示例:")
+    for key, (desc, _) in demos.items():
+        print(f"  {key}. {desc}")
+    print(f"  0. 运行所有示例")
+
+    try:
+        choice = input("\n请选择 [0-4]: ").strip()
+        if not choice:
+            choice = "0"
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return
+
+    compiler = QSLCompiler(verbose=True)
+
+    if choice == "0":
+        for key, (desc, program) in demos.items():
+            print(f"\n{'─'*60}")
+            print(f"  示例 {key}: {desc}")
+            print(f"{'─'*60}")
+            try:
+                result = compiler.compile_and_run(program)
+                print(f"  结果: {result.summary()}")
+            except Exception as e:
+                print(f"  错误: {e}")
+    elif choice in demos:
+        desc, program = demos[choice]
+        print(f"\n{'─'*60}")
+        print(f"  示例 {choice}: {desc}")
+        print(f"{'─'*60}")
+        try:
+            result = compiler.compile_and_run(program)
+            print(f"  结果: {result.summary()}")
+        except Exception as e:
+            print(f"  错误: {e}")
+    else:
+        print(f"无效选择: {choice}")
+
+
+def run_interactive():
+    print("\n" + "=" * 60)
+    print("  QSL - Quantum Search Language v1.0.0")
+    print("  Quantum Search Language")
+    print("=" * 60)
+    print("\n用法: python -m qsl --demo    运行演示")
+    print("      python -m qsl --help    查看帮助")
+    print()
+
+
+if __name__ == "__main__":
+    main()

qsl_quantum-0.1.0/qsl/backends/__init__.py

@@ -0,0 +1,24 @@
+"""
+QSL 后端模块 - 经典模拟器 和 IBM 量子计算机。
+
+使用:
+    >>> from qsl.backends import get_backend
+    >>> backend = get_backend("simulator")  # 经典模拟
+    >>> backend = get_backend("ibm")        # IBM 量子计算机
+"""
+
+from .base import AbstractBackend
+from .simulator import SimulatorBackend
+from .registry import get_backend, list_backends, register_backend
+
+# 预注册内置后端
+from .registry import _register_builtins
+_register_builtins()
+
+__all__ = [
+    "AbstractBackend",
+    "SimulatorBackend",
+    "get_backend",
+    "list_backends",
+    "register_backend",
+]