qsl-quantum 0.1.0__py3-none-any.whl

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/__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/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",
+]

qsl/backends/base.py

@@ -0,0 +1,105 @@
+"""
+量子后端抽象基类。
+
+所有后端必须实现的统一接口。该接口使得上层编译器无需关心
+具体是在模拟器还是真实量子计算机上运行。
+
+设计原则:
+    - 所有后端实现相同的 run_grover_search() 方法
+    - 每个后端负责自己的初始化、验证和错误处理
+    - 结果统一返回 GroverResult (由 core.grover 定义)
+
+失败模式分析 (接口层):
+    1. n_qubits 超出后端能力: 每个后端有独立的量子比特上限
+    2. Oracle 函数无法直接传输到真实硬件: 需要电路编译
+    3. shots 超出后端限制: 某些后端有最大测量次数限制
+    4. 连接超时: 真实硬件可能有队列等待
+"""
+
+from abc import ABC, abstractmethod
+from typing import Callable, Optional
+
+from ..core.grover import GroverResult
+
+
+class AbstractBackend(ABC):
+    """
+    量子计算后端抽象基类。
+
+    子类必须实现:
+        - run_grover_search()
+        - max_qubits 属性
+        - backend_name 属性
+    """
+
+    def __init__(self, name: str = "abstract", **options):
+        """
+        初始化后端。
+
+        参数:
+            name: 后端名称标识
+            **options: 后端特定选项
+        """
+        self._name = name
+        self._options = options
+
+    @property
+    def name(self) -> str:
+        """后端名称。"""
+        return self._name
+
+    @property
+    @abstractmethod
+    def max_qubits(self) -> int:
+        """该后端支持的最大量子比特数。"""
+        ...
+
+    @abstractmethod
+    def run_grover_search(self,
+                           n_qubits: int,
+                           oracle: Callable[[int], bool],
+                           num_solutions: int,
+                           shots: int,
+                           verbose: bool = False,
+                           **run_options) -> GroverResult:
+        """
+        在后端执行 Grover 搜索。
+
+        参数:
+            n_qubits: 量子比特数
+            oracle: Boolean oracle 函数 f(x) -> bool
+            num_solutions: 解的数量 M
+            shots: 测量次数
+            verbose: 是否输出过程信息
+            **run_options: 后端特定选项
+
+        返回:
+            GroverResult 包含搜索完整结果
+
+        失败模式 (由子类具体处理):
+            - 量子比特数超出上限
+            - Oracle 无法编译到目标硬件
+            - 连接 / 认证失败
+            - 作业超时
+            - 测量结果解析失败
+        """
+        ...
+
+    def validate_request(self, n_qubits: int, shots: int):
+        """
+        验证搜索请求的合法性。
+
+        子类应调用此方法作为 run_grover_search 的第一步。
+
+        失败模式:
+            - n_qubits > max_qubits: 抛出异常
+            - n_qubits < 1: 抛出异常
+            - shots < 1: 抛出异常
+        """
+        from ..utils.validation import validate_n_qubits, validate_shots
+
+        validate_n_qubits(n_qubits, self.max_qubits)
+        validate_shots(shots)
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {self._name}>"