Metadata-Version: 2.4
Name: qsl-quantum
Version: 0.6.0
Summary: QSL - Quantum Search Language: Full-stack quantum computing framework with simulator, algorithms (QFT/Shor/QAOA/VQE), QML, hardware backends (IBM/AWS), AI scientist, and self-evolving meta-system
Home-page: https://gitee.com/song_jack/qsl
Author: Song Ziming
Author-email: Song Ziming <15011462616@163.com>
License: MIT
Project-URL: Homepage, https://github.com/qsl-quantum/qsl
Project-URL: Repository, https://github.com/qsl-quantum/qsl
Project-URL: Issues, https://github.com/qsl-quantum/qsl/issues
Project-URL: Documentation, https://github.com/qsl-quantum/qsl#readme
Project-URL: Changelog, https://github.com/qsl-quantum/qsl/blob/main/CHANGELOG.md
Keywords: quantum-computing,quantum-circuit,qiskit-alternative,grover,shor,qaoa,vqe,qasm,llm-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
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
Requires-Dist: numpy>=1.20
Provides-Extra: algorithms
Requires-Dist: scipy>=1.7.0; extra == "algorithms"
Provides-Extra: qml
Requires-Dist: torch>=1.10; extra == "qml"
Requires-Dist: scikit-learn>=1.0; extra == "qml"
Requires-Dist: scipy>=1.7.0; extra == "qml"
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: aws
Requires-Dist: boto3>=1.28; extra == "aws"
Requires-Dist: amazon-braket-sdk>=1.50; extra == "aws"
Provides-Extra: ai
Requires-Dist: openai>=1.0; extra == "ai"
Requires-Dist: langchain>=0.1; extra == "ai"
Requires-Dist: langchain-openai>=0.1; extra == "ai"
Requires-Dist: pydantic>=2.0; extra == "ai"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: llm
Requires-Dist: openai>=1.0; extra == "llm"
Provides-Extra: cross
Requires-Dist: qiskit>=1.0; extra == "cross"
Requires-Dist: cirq>=1.0; extra == "cross"
Provides-Extra: meta
Requires-Dist: tensorboard>=2.10; extra == "meta"
Requires-Dist: deap>=1.3; extra == "meta"
Requires-Dist: ray>=2.0; extra == "meta"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Provides-Extra: full
Requires-Dist: scipy>=1.7.0; extra == "full"
Requires-Dist: torch>=1.10; extra == "full"
Requires-Dist: scikit-learn>=1.0; extra == "full"
Requires-Dist: matplotlib>=3.5; extra == "full"
Requires-Dist: qiskit>=1.0.0; extra == "full"
Requires-Dist: qiskit-aer>=0.14.0; extra == "full"
Requires-Dist: qiskit-ibm-runtime>=0.20.0; extra == "full"
Requires-Dist: boto3>=1.28; extra == "full"
Requires-Dist: amazon-braket-sdk>=1.50; extra == "full"
Requires-Dist: openai>=1.0; extra == "full"
Requires-Dist: langchain>=0.1; extra == "full"
Requires-Dist: langchain-openai>=0.1; extra == "full"
Requires-Dist: pydantic>=2.0; extra == "full"
Requires-Dist: tensorboard>=2.10; extra == "full"
Requires-Dist: deap>=1.3; extra == "full"
Requires-Dist: ray>=2.0; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<div align="center">

# 🚀 QSL — Quantum Search Language v0.6.0

**用一句话描述你想解决什么问题，剩下的交给量子计算。**

<p align="center">
  <a href="#-安装"><img src="https://img.shields.io/badge/Python-3.9+-3776AB?logo=python&logoColor=white" alt="Python"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-4CC61E" alt="License"></a>
  <img src="https://img.shields.io/badge/tests-398%20passed-00C851" alt="Tests">
  <img src="https://img.shields.io/badge/version-0.6.0-268BD2" alt="Version">
  <a href="https://pypi.org/project/qsl-quantum/"><img src="https://img.shields.io/badge/pypi-qsl--quantum-FFD43B?logo=pypi&logoColor=black" alt="PyPI"></a>
</p>

</div>

---

## ✨ 特性总览

一个 **全栈量子计算框架**，从声明式量子搜索到AI驱动的量子科学家：

| 层级 | 模块 | 功能 |
|:----:|:-----|:-----|
| **1️⃣** | **量子门 & 算法** | 50+ 量子门 · QFT · **Shor 量子相位估计** · **QAOA** · **VQE (parameter-shift)** |
| **2️⃣** | **量子机器学习** | **向量化 QuantumLayer** · QNN · 量子核 · QSVM · **可微 QGAN (Straight-Through)** |
| **3️⃣** | **后端 & 编译器** | 高性能模拟器 · IBM/AWS 真机 · 门融合 · 布局映射 · 零噪声外推 |
| **4️⃣** | **AI 量子科学家** | 自然语言→量子程序 · 自主智能体 · 假设检验 · 自动发现 |
| **5️⃣** | **元系统 & 网络** | 遗传电路搜索 · 量子定理证明 (Grover) · 分布式节点 · 量子区块链 |

---

## 🆕 0.6.0 新特性

- **QuantumCircuit 电路层**：参数化门 · `decompose()` 受控门递归分解 · `transpile()` 多级优化 · `control()` / `power()` / `inverse()` 电路变换 · 40+ 标准门
- **OpenQASM 互通**：QASM 2.0 导入导出 · QASM 3.0 导出
- **跨框架转换器**：`to_qiskit()` / `from_qiskit()` / `to_cirq()`
- **matplotlib 可视化**：电路图 · Bloch 球 · 城市图 · Q 球 · 直方图
- **噪声模拟**：`NoiseModel` + `execute_density()` 密度矩阵含噪演化 · cupy GPU 后端开关 · `expectation()` 免采样期望值
- **LLMProvider 多模型**：OpenAI / DeepSeek / Kimi / 通义 / Ollama · 规则路由表 + 中文参数抽取 + 缺参追问
- **自动验证器**：智能体结果自动验证 · 失败自动重规划 · 结构化 AgentReport
- **10 个中文演示**：覆盖 Grover / Shor / VQE / QAOA / QML 端到端示例

AI 功能开箱即用（零 SDK 时自动回退规则引擎），推荐 DeepSeek 或 Kimi：

```bash
# 任选其一设置 API Key
export DEEPSEEK_API_KEY="sk-..."      # DeepSeek
export MOONSHOT_API_KEY="sk-..."      # Kimi (Moonshot)

# 显式指定提供商（可选，默认自动探测）
export QSL_LLM=deepseek               # 或 kimi / openai / qwen / ollama
export QSL_LLM_MODEL=deepseek-chat    # 可选，覆盖默认模型
```

> 详见 [CHANGELOG.md](./CHANGELOG.md)。

---

## 🎯 5 秒上手

```python
from qsl import QSLProgram, compile_and_run

# 声明你想找什么：解一个 3-SAT 问题
program = QSLProgram(
    name="3-SAT",
    n_qubits=3,
    premises=["x0 | ~x1", "x1 | x2", "~x0 | ~x2"],
    shots=10
)
result = compile_and_run(program)
print(result.get_solutions())  # → [3, 4] 即 |011⟩ 和 |100⟩
```

**不需要懂量子力学。** 框架会自动编译最优量子电路并执行。

---

## 📦 核心功能演示

### 🔢 Shor 算法 — 整数因子分解

```python
from qsl import ShorSolver

# 量子相位估计实现周期查找 (支持超过旧12-qubit阈值)
solver = ShorSolver(21, max_control_qubits=12)
factors = solver.factor()
print(f"21 = {' × '.join(map(str, factors))}")  # → 21 = 3 × 7
```

### 🧬 VQE — 分子基态能量计算

```python
from qsl import VQE
import numpy as np

# 计算氢分子 H₂ 基态能量 (parameter-shift 梯度)
vqe = VQE(4, VQE.h2_hamiltonian(), n_layers=2)
energy, ground_state = vqe.optimize(maxiter=100)
print(f"H₂ ground energy: {energy:.4f} Hartree")
```

### 📊 QAOA — 组合优化 (MaxCut / 投资组合)

```python
from qsl import QAOA
import numpy as np

# MaxCut 问题
adj = np.array([[0,1,0],[1,0,1],[0,1,0]])
Q = QAOA.maxcut_cost_matrix(adj)
qaoa = QAOA(3, Q, p=2, encoding="qubo")
params, cost = qaoa.optimize()
bitstring, value = qaoa.get_optimal_bitstring()
```

### 🔍 Grover — 布尔表达式量子搜索

```python
from qsl import GroverSearch, solve_sat
from qsl.core.parser import parse_bool

# 直接从布尔表达式构建量子 Oracle (无经典枚举!)
expr = parse_bool("x0 & x1 & ~x2")
grover = GroverSearch(n_qubits=4, verbose=False)
result = grover.search_expressions([expr], num_solutions=1)
```

### 🤖 量子机器学习层

```python
from qsl import QuantumLayer
import torch

# 完全向量化的 PyTorch 层 (无 Python for 循环)
layer = QuantumLayer(n_qubits=4, n_features=4, encoding="angle")
x = torch.randn(8, 4)  # batch of 8
out = layer(x)          # shape: (8, 4) — 可端到端训练
```

---

## 🛠 安装

```bash
# 核心 (仅依赖 numpy, ~100KB)
pip install qsl-quantum

# 量子算法 (scipy)
pip install qsl-quantum[algorithms]

# 量子机器学习 (torch, scikit-learn)
pip install qsl-quantum[qml]

# 真实量子硬件
pip install qsl-quantum[ibm]      # IBM Quantum
pip install qsl-quantum[aws]      # AWS Braket

# 全部依赖
pip install qsl-quantum[full]
```

> ⚠️ 导入时会提示未安装 SDK 的后端不可用，本地模拟器始终可用。

---

## 📁 项目结构

```
qsl/
├── core/           量子态 · 布尔解析器 · Grover (真正量子Oracle)
├── compiler/       DSL · 编译器 · 门融合/交换 · 错误缓解
├── backends/       模拟器 · IBM · AWS Braket · 自动选择
├── algorithms/     QFT · Shor (量子相位估计) · QAOA · VQE (parameter-shift)
├── qml/            QuantumLayer (向量化) · QNN · QSVM · QGAN (可微)
├── ai/             LLM 翻译器 · 量子智能体 · 假设检验
├── pipelines/      药物发现 · 密码分析 · 投资组合优化 (真正QAOA)
├── meta/           遗传电路搜索 · 量子定理证明 (Grover)
├── network/        分布式节点 · 量子区块链
└── utils/          异常体系 · 输入验证
tests/              398 个单元测试
```

---

## ✅ 运行测试

```bash
pip install -e ".[dev]"
pytest tests/ -v
# ======= 398 passed in ~9s =======
```

---

## 🔬 v0.5.0 重大修复 (相比 v0.4.1)

| 问题 | 修复 |
|:-----|:-----|
| Grover Oracle 经典全枚举 2ⁿ 态 | ✅ 从布尔表达式直接构建量子电路 |
| Shor >12 qubit 退回经典 | ✅ 正确量子相位估计 + 逆QFT |
| QuantumLayer Python for 循环 | ✅ 全部改为 numpy/torch 批量运算 |
| QGAN torch.bernoulli 不可微 | ✅ Straight-Through Estimator |
| DensityMatrix 转 list-of-lists | ✅ 全程保持 numpy ndarray |
| 药物发现随机哈密顿量 | ✅ 支持 OpenFermion+PySCF 真实计算 |
| IBM 后端经典枚举Oracle | ✅ 量子Oracle电路构建 |
| 投资组合经典线性求解 | ✅ 逐点运行QAOA生成前沿 |
| VQE 有限差分梯度 O(n_params×2ⁿ) | ✅ Parameter-shift 规则 |
| 定理证明器经典枚举 | ✅ Grover 量子搜索证明空间 |
| QFT apply/matrix 不一致 | ✅ 受控相位门逻辑修正 |
| DensityMatrix amplitude damping 仅作用于 qubit 0 | ✅ 所有qubit循环施加 |
| QAOA Ising/QUBO 编码不匹配 | ✅ 统一变量转换 |
| QuantumLayer CNOT 优先级bug | ✅ 运算符逻辑修正 |
| 解析器不支持下划线开头变量 | ✅ `_` 标识符支持 |
| kron 遮蔽 numpy.kron | ✅ 重命名为 kronecker_prod |
| VQE 非H₂分子静默替换 | ✅ 明确报错提示 |
| IBM JobStatus 路径问题 | ✅ try/except 兼容Qiskit 1.0+ |

---

## 👤 作者

宋梓铭 · [Gitee](https://gitee.com/song-jack/qsl) · 15011462616@163.com

---

## 📄 许可证

MIT License — 可自由使用、修改、分发。
