Metadata-Version: 2.4
Name: cascaqit
Version: 0.1.9
Summary: CAS Cold Atom Quantum Computing SDK for Neutral Atom Quantum Computers
Author-email: CAS Team <zyxtomcat@gmail.com>
License: Apache License 2.0
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: juliacall>=0.9.14
Requires-Dist: numpy<2.1,>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: scipy<1.15,>=1.14
Requires-Dist: pandas>=2.1.0
Requires-Dist: bokeh>=3.2.2
Requires-Dist: tabulate>=0.9.0
Requires-Dist: requests-sigv4>=0.1.6
Requires-Dist: amazon-braket-sdk>=1.78.0
Requires-Dist: plotext>=5.2.8
Requires-Dist: beartype>=0.15.0
Requires-Dist: simplejson>=3.19.1
Requires-Dist: plum-dispatch>=2.2.2
Requires-Dist: numba<0.61,>=0.60

> [!IMPORTANT]
>
> CASCAQit 是一个面向**中性原子量子计算**的 Python SDK，由中科酷原（CAS Cold Atom）开发。
>
> SDK 以**模拟量子计算**（Analog Quantum Computing）为核心，提供原子排列、Rydberg 控制波形、模拟器和硬件执行链路；同时补充了**数字量子编程**（Digital Quantum Computing）能力，可用量子门线路构造 Bell/GHZ、Grover、QFT、VQE、QAOA 等程序，并通过本地 statevector 模拟器运行。
>
> 当前数字模块主要面向本地模拟和算法开发；真实硬件执行仍以模拟量子程序为主。


# 欢迎使用 CASCAQit -- 中科酷原量子计算开发套件

## 什么是 CASCAQit？

CASCAQit (CAS Cold Atom Quantum Interface Toolkit) 是一个专为 CAS 中性原子量子计算机设计的 Python SDK。它提供了编写、模拟和执行**模拟量子程序**（Analog Quantum Programs）的完整工具链，并提供面向门模型算法开发的**数字量子线路**（Digital Quantum Circuits）能力。

**模拟量子计算 vs 数字量子计算**：
- **模拟模式**：通过控制含时哈密顿量（Rabi 振幅、失谐、相位）实现连续时间演化，适合中性原子 Rydberg 系统、模拟退火和多体动力学任务
- **数字模式**：通过量子门电路（H、X、CX、RZ 等）实现离散操作，适合通用量子算法、参数化线路和经典-量子混合优化实验

CASCAQit 仍以中性原子模拟量子计算为核心，同时提供数字线路构造、statevector 模拟、测量、参数绑定、VQE/QAOA 优化和示例文档，方便用户在同一个 SDK 中学习和验证两类量子编程模型。

### 核心特性

- **灵活的原子几何结构定义**：支持多种布拉维晶格和自定义原子排列
- **强大的波形构建系统**：支持分段线性、分段常数、多项式和自定义函数波形
- **多后端支持**：Python 模拟器、中科酷原的汉原一号硬件直接连接
- **完整的参数扫描**：内置变量系统和批处理功能
- **交互式可视化**：程序和结果的实时可视化
- **数字量子线路**：支持常用量子门、参数化旋转门、Z/X/Y 基测量、中途测量和条件门模拟
- **变分算法工具**：提供 `ParameterSpec`、`VQE`、`QAOAAnsatz` 等数字量子优化组件
- **数字示例体系**：覆盖 Hello Quantum、量子隐形传态、Grover、QFT/QPE、VQE 和 QAOA Max-Cut

## 安装

```bash
pip install cascaqit
```

**支持 Python 版本**: 3.11, 3.12

## 快速开始：模拟量子程序

### 1. 定义原子几何结构

```python
from cascaqit.quantum.atom_arrangement import Square, Honeycomb, Kagome

# 创建 3x3 方格，晶格间距 6.0 μm
geometry = Square(3, lattice_spacing=6.0)

# 可视化几何结构
geometry.show()
```

支持预定义的布拉维晶格：
- `Square` - 方格晶格
- `Honeycomb` - 蜂窝晶格
- `Triangular` - 三角晶格
- `Kagome` - 笼目格
- `Lieb` - Lieb 晶格
- `Chain` - 链式结构
- `Rectangular` - 矩形晶格

### 2. 构建量子程序

```python
from cascaqit.quantum import start, var

# 定义变量
max_rabi = var("max_rabi")
max_detuning = var("max_detuning")

# 构建程序
program = (
    Square(3, lattice_spacing=6.0)
    .rydberg.rabi.amplitude.uniform
    .piecewise_linear(
        durations=[0.4, 3.2, 0.4],
        values=[0.0, max_rabi, max_rabi, 0.0]
    )
    .detuning.uniform
    .piecewise_linear(
        durations=[0.4, 3.2, 0.4],
        values=[-max_detuning, -max_detuning, max_detuning, max_detuning]
    )
    .assign(max_rabi=15.8, max_detuning=16.33)
)

# 可视化程序
program.show()
```

### 3. 执行程序

#### Python 模拟器

```python
results = program.hanyuan1_simulator.python().run(
    shots=1000,              # 测量次数
    blockade_radius=8.0,     # Rydberg 阻塞半径 (μm)
    cache_matrices=True      # 缓存哈密顿量矩阵
)

# 分析结果
report = results.report()
print(report.counts())           # 位串计数
print(report.rydberg_densities())  # Rydberg 密度
report.show()                    # 可视化结果
```

#### 硬件执行

```python
# 汉原1号直接连接
results = program.hanyuan1.device(api_hostname="your_host", qpu_id="your_qpu_id").run_async(100)

# 或使用 Mock 后端测试
results = program.hanyuan1.mock().run_async(100)
```

## 快速开始：数字量子程序

数字量子线路从 `circuit()` 入口开始构造，使用 `.parse_circuit()` 生成 `DigitalRoutine`，再通过本地 Python statevector 模拟器运行。

### 1. Bell 态

```python
from cascaqit.quantum import circuit

routine = (
    circuit(2, name="bell")
    .h(0)
    .cx(0, 1)
    .measure()
    .parse_circuit()
)

result = routine.python_simulator.run(shots=1000, seed=0)

print(result.counts)
print(result.probabilities())
```

典型结果只包含 `"00"` 和 `"11"`，比例约为 50% / 50%。

### 2. 参数化线路

```python
import numpy as np
from cascaqit.quantum import circuit, var

theta = var("theta")

routine = (
    circuit(1)
    .ry(0, theta)
    .measure()
    .args(["theta"])
    .parse_circuit()
)

result = routine.python_simulator.run(
    shots=1000,
    seed=0,
    args=[np.pi / 2],
)

print(result.counts)
```

### 3. QAOA 示例

```python
from cascaqit.quantum.optimizer import QAOAAnsatz, VQE

edges = [(0, 1, 1.0), (1, 2, 1.0), (0, 2, 1.0)]

ansatz = QAOAAnsatz(n_qubits=3, edges=edges, p=1)
routine = ansatz.build()
spec = ansatz.parameter_spec()
observable = ansatz.max_cut_observable()

vqe = VQE(routine, spec, observable, shots=2048)
result = vqe.run(x0=spec.random(seed=0), max_iter=50)

print(result.optimal_value)
print(result.optimal_params)
```

## 核心 API

### 入口点和工厂函数

```python
from cascaqit.quantum import (
    start,                # 程序构建入口点
    circuit,              # 数字量子线路入口点
    var,                  # 创建变量
    cast,                 # 类型转换
    piecewise_linear,      # 分段线性波形
    piecewise_constant,    # 分段常数波形
    linear,               # 线性波形
    constant,             # 恒定波形
    get_capabilities,     # 获取硬件能力
    get_sdk_capabilities, # 获取 SDK 能力边界
    waveform,             # 函数波形装饰器
    save, load,           # 序列化
)

from cascaqit.quantum import RB_C6  # Rydberg C6 系数
```

### 波形类型

```python
# 基本波形
constant(value=5.0, duration=1.0)           # 恒定值
linear(start=0.0, stop=10.0, duration=2.0)   # 线性变化
poly(coeffs=[0, 1, 0.5], duration=2.0)       # 多项式

# 组合波形
piecewise_linear([0.5, 1.0, 0.5], [0, 5, 8, 0])  # 分段线性
piecewise_constant([0.5, 1.0, 0.5], [2, 5, 3])    # 分段常数

# 自定义函数
@waveform(duration=3.0)
def my_waveform(t):
    return 2.0 * sin(t)

# 波形操作
wf1 + wf2          # 相加
wf1.append(wf2)     # 连接
wf1 * 2.0           # 缩放
-wf1                # 取负
wf1[0:0.5]          # 切片
wf1.sample(0.05, "linear")  # 采样
```

### 变量系统

```python
import numpy as np

# 定义变量
rabi_amp = var("rabi_amplitude")

# 在程序中使用
program = (
    start.add_position((0, 0))
    .rydberg.rabi.amplitude.uniform
    .piecewise_linear(
        durations=[0.3, "run_time", 0.3],
        values=[0.0, rabi_amp, rabi_amp, 0.0]
    )
)

# 单次赋值
program = program.assign(rabi_amplitude=10.0, run_time=2.0)

# 批量赋值（参数扫描）
batch_program = program.batch_assign(
    rabi_amplitude=np.linspace(5.0, 15.0, 20),
    run_time=[1.0, 2.0, 3.0]
)

# 延迟赋值
delayed_program = program.args(["rabi_amplitude"])
results = delayed_program.hanyuan1_simulator.python().run(100, args=(10.0,))
```

### 空间调制

```python
# 均匀调制（默认）
program.uniform.constant(5.0, 1.0)

# 位置调制 - 针对特定原子
program.location([0, 2, 4]).constant(5.0, 1.0)
program.location([0, 2], [0.5, 1.0]).constant(5.0, 1.0)

# 缩放调制 - 为每个原子设置缩放系数
program.scale([0.1, 0.2, 0.3]).constant(5.0, 1.0)
program.scale("scales").constant(5.0, 1.0)  # 使用变量
```

### 数字量子线路

```python
from cascaqit.quantum import circuit, var
from cascaqit.quantum.ir.digital import MeasurementBasis

theta = var("theta")

qc = (
    circuit(3, n_cbits=3, name="digital_demo")
    .h(0)
    .cx(0, 1)
    .ry(2, theta)
    .measure(qubits=[0, 1], bits=[0, 1])
    .measure(qubits=[2], bits=[2], basis=MeasurementBasis.X)
)

routine = qc.args(["theta"]).parse_circuit()
result = routine.python_simulator.run(shots=1000, seed=0, args=[1.0])
```

常用能力：

- 单量子比特门：`h`、`x`、`y`、`z`、`s`、`sdg`、`t`、`tdg`、`sx`、`sxdg`
- 双量子比特门：`cx` / `cnot`、`cy`、`cz`、`swap`
- 三量子比特门：`ccx` / `toffoli`、`cswap` / `fredkin`
- 参数化门：`rx`、`ry`、`rz`、`phase`、`u1`、`u2`、`u3`、`u`、`crx`、`cry`、`crz`、`cphase`、`rxx`、`ryy`、`rzz`
- 测量基：`MeasurementBasis.Z`、`MeasurementBasis.X`、`MeasurementBasis.Y`
- 参数绑定：`.assign(...)`、`.batch_assign(...)`、`.args([...])`
- 实验性动态线路：中途测量和 `.if_clbits(...)` 条件门模拟

## 执行后端

### 模拟量子后端

| 后端 | 路径 | 描述 |
|------|------|------|
| Python | `.hanyuan1_simulator.python()` | 基于 SciPy ODE 求解器 |
| Julia | `.hanyuan1_simulator.julia()` | (开发中) |

### 模拟量子硬件

| 后端 | 路径 | 描述 |
|------|------|------|
| 汉原1号 | `.hanyuan1.device()` | 直接连接汉原1号 QPU |
| Mock | `.hanyuan1.mock()` | 本地模拟后端（用于测试） |

### 数字量子后端

| 后端 | 路径 | 描述 |
|------|------|------|
| Python statevector | `.python_simulator.run()` | 本地纯 Python/Numpy statevector 模拟器 |

数字后端当前主要用于本地算法验证和教学示例。官方数字硬件后端尚未启用。

### 设备字符串

```python
# 也可以使用 device() 方法指定
program.device("hanyuan1.device", api_hostname="your_host", qpu_id="your_qpu_id").run(100)
program.device("hanyuan1.mock").run(100)
program.device("hanyuan1_simulator.python").run(100)
```

## 并行化

对于小规模原子系统，使用 `.parallelize()` 在单次运行中复制程序：

```python
# 创建 24 个独立的程序副本
parallelized_program = program.parallelize(24)

# 结果自动合并
results = parallelized_program.hanyuan1_simulator.python().run(100)
```

## 程序复用

```python
# 构建可复用的脉冲序列
pulse_sequence = (
    start
    .rydberg.rabi.amplitude.uniform
    .piecewise_linear(
        durations=[0.4, 2.0, 0.4],
        values=[0.0, 10.0, 10.0, 0.0]
    )
    .parse_sequence()
)

# 应用到不同的几何结构
from cascaqit.quantum.atom_arrangement import Square, Chain

program1 = Square(3).apply(pulse_sequence)
program2 = Chain(10).apply(pulse_sequence)
```

## 序列化

```python
from cascaqit.quantum import save, load

# 保存到文件
save(results, "results.json")
save(program, "program.json")

# 从文件加载
loaded_results = load("results.json")
loaded_program = load("program.json")
```

## 结果分析

### 模拟量子结果

```python
results = program.hanyuan1_simulator.python().run(100)
report = results.report()

# 位串计数
counts = report.counts()

# 位串数组
bitstrings = report.bitstrings()

# Rydberg 密度
densities = report.rydberg_densities()

# 获取 DataFrame
df = report.dataframe

# 可视化
report.show()
```

### 数字量子结果

```python
result = (
    circuit(2)
    .h(0)
    .cx(0, 1)
    .measure()
    .parse_circuit()
    .python_simulator
    .run(shots=1000, seed=0)
)

# 位串计数
counts = result.counts

# 归一化概率
probabilities = result.probabilities()

# 每次 shot 的结果
memory = result.memory

# 最常见结果
top = result.most_common(2)
```

## 高级特性

### 波形切片和记录

```python
import numpy as np

# 切片波形用于时间扫描
sliced_program = (
    start.add_position((0, 0))
    .rydberg.rabi.amplitude.uniform
    .piecewise_linear(
        durations=[0.5, 3.0, 0.5],
        values=[0.0, 10.0, 10.0, 0.0]
    )
    .slice(start=0, stop="run_time")
    .record("final_value")
    .linear("final_value", 0.0, 0.5)
)

batch = sliced_program.batch_assign(
    run_time=np.linspace(1.0, 3.0, 10)
)
```

### 硬件能力查询

```python
from cascaqit.quantum import get_capabilities

capabilities = get_capabilities()

# 访问硬件参数
max_rabi = capabilities.capabilities.rydberg.global_.rabi_frequency_max
max_detuning = capabilities.capabilities.rydberg.global_.detuning_max
```

### SDK 能力查询

```python
from cascaqit.quantum import get_sdk_capabilities

capabilities = get_sdk_capabilities()

print(capabilities.digital)
print(capabilities.dynamic)
print(capabilities.analog)
```

该接口用于查看 SDK 层面的能力边界，例如数字线路是否支持 reset、支持哪些测量基、动态线路当前处于什么状态等。

### 数字示例

数字示例位于 `examples/digital/`：

| 示例 | 内容 |
|------|------|
| `01_hello_quantum/` | 基础量子门、Bell 态、GHZ 态 |
| `02_quantum_teleportation/` | 量子隐形传态 |
| `03_grover_search/` | Grover 搜索 |
| `04_qft_and_phase_estimation/` | QFT 与量子相位估计 |
| `05_vqe_ground_state/` | VQE 求解基态能量 |
| `06_qaoa_maxcut/` | QAOA 求解 Max-Cut |

运行示例：

```bash
cd examples/digital
python 01_hello_quantum/hello_quantum.py
```

### 使用 rydberg_h 快速创建程序

```python
from cascaqit.quantum import rydberg_h, piecewise_linear

# 快速创建 Rydberg 程序
program = rydberg_h(
    atoms_positions=Square(3),
    amplitude=piecewise_linear([0.4, 3.2, 0.4], [0, 10, 10, 0]),
    detuning=piecewise_linear([0.4, 3.2, 0.4], [-20, -20, 20, 20]),
    static_params={},
    batch_params=[],
    args=[]
)
```

## 项目结构

```
cascaqit/
├── src/cascaqit/quantum/
│   ├── __init__.py              # 用户 API 入口
│   ├── factory.py               # 工厂函数
│   ├── atom_arrangement.py      # 原子排列定义
│   ├── constants.py             # 物理常数
│   ├── serialize.py             # 序列化
│   ├── migrate.py               # 版本迁移
│   ├── constructor/             # 构建器
│   │   ├── digital/             # 数字线路构建器
│   │   ├── start.py             # 程序入口
│   │   ├── field.py             # 字段 (Rabi, Detuning, Phase)
│   │   ├── waveform.py          # 波形定义
│   │   ├── spatial.py           # 空间调制
│   │   ├── pragmas.py           # 编译指令
│   │   └── executor/            # 执行后端路由
│   ├── ir/                      # 中间表示
│   │   ├── scalar.py            # 标量表达式
│   │   ├── control/             # 控制流 (波形、序列)
│   │   ├── location/            # 位置 (布拉维晶格)
│   │   ├── digital/             # 数字线路 IR (gate, measurement, condition)
│   │   └── analog_circuit.py    # 模拟电路
│   ├── compiler/                # 编译器
│   │   ├── analysis/            # 分析器
│   │   ├── rewrite/             # 重写器
│   │   ├── codegen/             # 代码生成
│   │   └── passes/              # 编译 pass
│   ├── dispatch/                # 任务分发
│   ├── simulator/               # 模拟器
│   │   └── digital/             # 数字 statevector 模拟器
│   ├── optimizer/               # VQE/QAOA 等数字量子优化工具
│   ├── job/                     # 任务管理
│   └── visualization/           # 可视化
├── tests/                       # 测试
├── docs/                        # 文档
└── examples/                    # 示例
```

## 文档

- **快速入门**: [快速入门指南](docs/home/quick_start.md)
- **架构设计**: [架构设计文档](docs/architecture.md)
- **编程指南**: [编程指南](docs/programming_guide.md)
- **数字量子编程指南**: [数字量子编程指南](docs/digital_programming_guide.md)
- **数字示例设计**: [数字示例设计文档](docs/digital-examples-design.md)
- **示例集合**: [示例目录](examples/README.md)
- **API 参考**: [API 参考](docs/reference/overview.md)
- **硬件能力**: [硬件参考](docs/reference/hardware-capabilities.md)

## 依赖项

### 核心依赖

- `numpy>=2.1.0`
- `scipy>=1.0.0`
- `pydantic>=2.0`
- `bokeh>=3.2.2`
- `pandas>=2.1.0`
- `juliacall>=0.9.14`
- `beartype>=0.15.0`
