Metadata-Version: 2.4
Name: cascaqit-compat
Version: 0.1.1
Summary: Atom Quantum Computing SDK Compatibility Layer — runs on top of CASCAQit
License: Apache-2.0
Requires-Python: <3.14,>=3.10
Requires-Dist: cascaqit>=0.1.7
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: openqasm3>=0.4; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: qiskit<2.0,>=1.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: openqasm
Requires-Dist: openqasm3>=0.4; extra == 'openqasm'
Provides-Extra: qiskit
Requires-Dist: qiskit<2.0,>=1.0; extra == 'qiskit'
Description-Content-Type: text/markdown

# CASCAQit-compat

**面向 CASCAQit 的量子算法兼容层。** 本项目让用户可以用 Qiskit、OpenQASM、Analog DSL 和 Hybrid API 设计量子程序，并通过 CASCAQit 本地后端或汉原一号相关后端完成编译、运行、结果分析和可视化。

[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)

---

## 适合谁使用

| 使用目标 | 推荐入口 | 典型场景 |
|---|---|---|
| 已经熟悉 Qiskit | `atom_qiskit.AtomBackend` | Bell、GHZ、Bernstein-Vazirani、QFT、参数化线路。 |
| 希望用文本描述线路 | `atom_openqasm.OpenQASMFrontend` | QASM2/QASM3 解析、参数化 QASM、parse/dump round-trip。 |
| 设计中性原子模拟程序 | `atom_analog.AnalogProgramBuilder` | Rabi、Ramsey、Rydberg blockade、detuning sweep、Landau-Zener。 |
| 组合 circuit、analog、measure 段 | `atom_hybrid.HybridProgramBuilder` | 按统一 timeline 描述混合程序。 |
| 扫描参数和分析趋势 | `ParameterSweep` / `CompilerAdapter.sweep()` | 角度扫描、detuning 扫描、duration 扫描。 |

如果你只是想确认环境可用，直接运行正式算法示例：

```bash
python examples/algorithms/run_all.py --backend cascaqit
```

该命令会运行 13 个正式 examples，并在 `examples/algorithms/artifacts/` 下生成 `result.json`、`report.md` 和 SVG 可视化结果。

---

## 后端选择

| 后端 | 用途 | 是否可作为正式 examples 验收 |
|---|---|---|
| `CASCAQitBackend` | 默认 CASCAQit 本地编译和执行路径，支持 circuit、analog、hybrid。 | 是 |
| `Hanyuan1AnalogBackend(mode="simulator")` | 汉原一号 analog simulator 工作流。 | 可用于 analog 专项示例 |
| `MockBackend` | 离线 CI、单元测试、调试。 | 否 |
| `DynamicMockBackend` | 离线验证动态线路语义。 | 否，除非真实 CASCAQit 后端提供等价官方能力 |

动态线路、reset、analog 参数绑定和 hybrid 执行模式存在明确边界。正式项目使用前请阅读 [v0.7 后端限制说明](docs/BACKEND_LIMITATIONS_v0_7.md)。

---

## 安装

### 最小安装

```bash
pip install cascaqit-compat
```

最小安装包含运行兼容层所需的基础依赖：

| 依赖 | 版本范围 | 用途 |
|---|---|---|
| Python | `>=3.10,<3.14` | SDK 运行环境 |
| CASCAQit | `>=0.1.7` | 默认数字/模拟后端库 |
| pydantic | `>=2.0` | 与 CASCAQit 保持一致的数据模型依赖 |
| PyYAML | `>=6.0` | YAML device config、Analog/Hybrid 前端 |

### 按需安装前端依赖

```bash
pip install "cascaqit-compat[qiskit]"
pip install "cascaqit-compat[openqasm]"
```

### 开发安装

```bash
pip install -e ".[dev]"
```

`dev` extra 包含 `pytest`、`pytest-cov`、`black`、`ruff`、`mypy`、`qiskit` 和 `openqasm3`。如果要对本地 CASCAQit 源码调试，可以先在 CASCAQit 仓库执行 `pip install -e .`，再安装本仓库。

---

## 5 分钟跑通算法示例

```bash
python examples/algorithms/run_all.py --backend cascaqit
python examples/algorithms/run_all.py --backend cascaqit --group qiskit
python examples/algorithms/run_all.py --backend cascaqit --group openqasm
python examples/algorithms/run_all.py --backend cascaqit --group analog
```

正式 examples 当前包含：

| 分组 | 示例 |
|---|---|
| Qiskit | Bell、GHZ、Bernstein-Vazirani、QFT 3-qubit |
| OpenQASM | Bell QASM2、GHZ QASM2、Parametric RX QASM3、QASM round trip |
| Analog DSL | Rabi、Rydberg blockade、Detuning sweep、Ramsey detuning、Landau-Zener sweep |

每个示例都会输出：

| 文件 | 说明 |
|---|---|
| `result.json` | 机器可读结果、后端、metadata、参数和 mapping 摘要。 |
| `report.md` | 用户可读运行报告。 |
| `*.svg` | circuit、counts、source、IR、atom layout、waveform 或 sweep 图。 |

---

## 最小 Qiskit 示例

```python
from qiskit import QuantumCircuit, transpile
from cascaqit_compat.atom_qiskit import AtomBackend
from cascaqit_compat.atom_core import DeviceConfig
from cascaqit_compat.atom_cascaqit import CASCAQitBackend

cas_backend = CASCAQitBackend(seed=42)
backend = AtomBackend(
    device=DeviceConfig.mock(num_qubits=5),
    compiler_backend=cas_backend,
    execution_backend=cas_backend,
)

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

qc_t = transpile(qc, target=backend.target)
job = backend.run(qc_t, shots=100)
print(job.result().get_counts())
```

更完整的 Qiskit 算法示例见 `examples/algorithms/qiskit/` 和 [算法示例指南](docs/ALGORITHMS_GUIDE.md)。

---

## 最小 OpenQASM 示例

```python
from cascaqit_compat.atom_openqasm import OpenQASMFrontend
from cascaqit_compat.atom_core import AtomProgram, CompilerAdapter, DeviceConfig
from cascaqit_compat.atom_cascaqit import CASCAQitBackend

source = """
OPENQASM 3.0;
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c[0] = measure q[0];
c[1] = measure q[1];
"""

circuit = OpenQASMFrontend().parse(source, name="qasm_bell")
backend = CASCAQitBackend(seed=42)
compile_result = CompilerAdapter(backend=backend).compile(
    AtomProgram(circuit_ir=circuit),
    DeviceConfig.mock(num_qubits=5),
)
job_id = backend.submit(compile_result, shots=100)
print(backend.result(job_id).counts)
```

---

## 最小 Analog DSL 示例

```python
from cascaqit_compat.atom_analog import AnalogProgramBuilder
from cascaqit_compat.atom_core import AtomProgram, CompilerAdapter, DeviceConfig
from cascaqit_compat.atom_cascaqit import CASCAQitBackend

analog = (
    AnalogProgramBuilder()
    .chain(2, spacing=5.0)
    .global_drive(
        omega=AnalogProgramBuilder.constant(1.0, 100.0),
        delta=AnalogProgramBuilder.constant(-1.0, 100.0),
    )
    .build()
)

backend = CASCAQitBackend(seed=42)
compile_result = CompilerAdapter(backend=backend).compile(
    AtomProgram(analog_ir=analog),
    DeviceConfig.mock(num_qubits=5),
)
job_id = backend.submit(compile_result, shots=50)
result = backend.result(job_id)
print(result.counts)
print(result.mapping_info)
```

---

## 文档导航

| 文档 | 适合场景 |
|---|---|
| [快速开始](docs/GETTING_STARTED.md) | 安装、选择后端、跑第一个 Qiskit/OpenQASM/Analog 程序。 |
| [量子算法设计工作流](docs/QUANTUM_ALGORITHM_WORKFLOW.md) | 从算法想法到 CASCAQit 后端运行的完整流程。 |
| [算法示例指南](docs/ALGORITHMS_GUIDE.md) | 查看 13 个正式 examples、运行命令和 artifacts。 |
| [Qiskit 算法 Cookbook](docs/QISKIT_ALGORITHM_COOKBOOK.md) | 用 Qiskit 设计 Bell、GHZ、BV、QFT 和参数化线路。 |
| [OpenQASM 算法 Cookbook](docs/OPENQASM_ALGORITHM_COOKBOOK.md) | 用 QASM2/QASM3 描述线路、参数和 round-trip。 |
| [Analog DSL 算法 Cookbook](docs/ANALOG_ALGORITHM_COOKBOOK.md) | 设计 Rabi、Ramsey、Rydberg blockade 和 sweep 程序。 |
| [结果分析与可视化](docs/RESULT_ANALYSIS_AND_VISUALIZATION.md) | 读取 counts、mapping_info、metadata 和 SVG artifacts。 |
| [故障排查](docs/TROUBLESHOOTING.md) | 处理依赖、后端、参数、动态线路和硬件配置问题。 |
| [API 指南](docs/API_GUIDE.md) | Core IR、frontends、backends、job lifecycle 和错误模型。 |
| [参数化编译与绑定指南](docs/PARAMETER_BINDING_GUIDE.md) | `ParameterExpression`、`parameter_schema`、`param_binds`、sweep。 |
| [动态线路支持边界](docs/DYNAMIC_CIRCUIT_GUIDE.md) | Qiskit/OpenQASM 动态线路子集、mock 路径和真实后端 gating。 |
| [v0.7 后端限制说明](docs/BACKEND_LIMITATIONS_v0_7.md) | dynamic、reset、analog runtime re-lowering、hybrid sequential execution。 |
| [v0.7 验收报告](docs/ACCEPTANCE_REPORT_v0_7.md) | 当前实现状态、测试结果和限制项。 |

---

## 架构

![CASCAQit-compat 架构图](docs/diagrams/architecture.svg)

核心原则：

- `atom_cascaqit` 是唯一导入 `cascaqit` 的子包。
- 其他前端包保持 import-safe，依赖缺失时优雅跳过相关功能或测试。
- 所有入口最终收敛到 `AtomProgram` / `AtomCircuitIR` / `AtomAnalogIR` / `AtomHybridProgram`，再通过 `CompilerAdapter` 和后端执行。

| 子包 | 主要类 | 说明 |
|---|---|---|
| `atom_core` | `AtomCircuitIR`, `AtomAnalogIR`, `AtomHybridProgram` | 核心 IR 和数据模型。 |
| `atom_core` | `ParameterExpression`, `ParameterSweep` | 符号参数和参数扫描。 |
| `atom_core` | `CompilerAdapter`, `ResultModel` | 统一编译入口和结果模型。 |
| `atom_cascaqit` | `CASCAQitBackend`, `Hanyuan1AnalogBackend`, `MockBackend` | CASCAQit 集成和本地/测试后端。 |
| `atom_qiskit` | `AtomBackend`, `AtomJob`, `AtomProvider` | Qiskit BackendV2-compatible 接入。 |
| `atom_openqasm` | `OpenQASMFrontend`, `OpenQASMDumper` | QASM 2/3 解析与导出。 |
| `atom_analog` | `AnalogProgramBuilder`, `AnalogProgramValidator` | Rydberg analog 程序构建和校验。 |
| `atom_hybrid` | `HybridProgramBuilder`, `HybridProgramValidator` | 混合程序构建和 timeline 校验。 |

---

## 硬件对接

真实硬件路径需要显式配置凭据，不要把 provider token、access key、secret key 或机器本地配置文件提交到仓库。

```python
from cascaqit_compat.atom_cascaqit import Hanyuan1AnalogBackend

backend = Hanyuan1AnalogBackend(
    mode="hardware",
    api_config={
        "api_hostname": "YOUR_API_ENDPOINT",
        "qpu_id": "hanyuan1",
        "access_key": "YOUR_ACCESS_KEY",
        "secret_key": "YOUR_SECRET_KEY",
    },
)
```

真实硬件测试默认跳过，必须通过 marker 和环境变量显式开启。

---

## 开发与测试

```bash
# 默认测试
pytest

# 覆盖率
pytest --cov=cascaqit_compat

# 格式化
black cascaqit_compat tests examples

# Lint
ruff check cascaqit_compat tests examples

# 构建包
python -m build
```

集成测试 marker：

| Marker | 默认行为 | 启用方式 |
|---|---|---|
| `requires_cascaqit` | CASCAQit 未安装时跳过 | 安装 CASCAQit 后自动运行 |
| `requires_cascaqit_analog_simulator` | 始终跳过 | `CASCAQIT_RUN_ANALOG_SIMULATOR=1 pytest` |
| `requires_hanyuan1_hardware` | 始终跳过 | `CASCAQIT_RUN_HANYUAN1_HARDWARE=1 pytest`，并提供硬件凭据 |

---

## 项目结构

```text
cascaqit-compat/
├── cascaqit_compat/
│   ├── atom_core/
│   ├── atom_cascaqit/
│   ├── atom_qiskit/
│   ├── atom_openqasm/
│   ├── atom_analog/
│   └── atom_hybrid/
├── docs/
├── examples/
├── tests/
├── pyproject.toml
└── README.md
```

---

## License

Apache License 2.0，详见 [LICENSE](LICENSE)。

## 相关项目

- [CASCAQit](https://github.com/CASColdAtom/CASCAQit)：中科酷原中性原子量子计算 SDK。
- [Qiskit](https://github.com/Qiskit/qiskit)：量子计算软件框架。
- [OpenQASM 3](https://openqasm.com)：开放量子汇编语言规范。
