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; 随意使用、修改、分发。
