cascaqit 0.1.2
CAS Cold Atom Quantum Computing SDK for Neutral Atom Quantum Computers
License: Apache License 2.0
Requires Python: <3.14,>=3.10

> [!IMPORTANT]
>
> CASCAQit 是一个专为**中性原子模拟量子计算**（Analog Quantum Computing）设计的量子计算 SDK，由中科酷原（CAS Cold Atom）开发。
>
> **与数字量子计算的区别**：CASCAQit 使用**模拟模式**（通过控制哈密顿量参数实现连续时间演化），而非传统的**数字模式**（基于量子门电路的离散操作）。
>
> 该 SDK 提供了编写、模拟和执行模拟量子程序的完整工具链。


# 欢迎使用 CASCAQit -- 中科酷原模拟量子计算 SDK

## 什么是 CASCAQit？

CASCAQit (CAS Cold Atom Quantum Interface Toolkit) 是一个专为 CAS 中性原子量子计算机设计的 Python SDK。它提供了编写、模拟和执行**模拟量子程序**（Analog Quantum Programs）的完整工具链。

**模拟量子计算 vs 数字量子计算**：
- **模拟模式**（CASCAQit）：通过控制含时哈密顿量（Rabi 振幅、失谐、相位）实现连续时间演化
- **数字模式**（传统量子计算）：通过量子门电路（单/双量子比特门）实现离散操作

CASCAQit 专注于模拟量子计算模式，利用中性原子的里德伯阻塞效应实现多体纠缠。

### 核心特性

- **灵活的原子几何结构定义**：支持多种布拉维晶格和自定义原子排列
- **强大的波形构建系统**：支持分段线性、分段常数、多项式和自定义函数波形
- **多后端支持**：Python 模拟器、AWS Braket 云服务和 CAS 硬件直接连接
- **完整的参数扫描**：内置变量系统和批处理功能
- **交互式可视化**：程序和结果的实时可视化

## 安装

```bash
pip install cascaqit
```

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

## 快速开始

### 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.cas_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
# AWS Braket (Aquila)
hardware_results = program.braket.aquila().run_async(100)

# CAS 直接连接
results = program.cas.aquila().run_async(100)
```

## 核心 API

### 入口点和工厂函数

```python
from cascaqit.quantum import (
    start,                # 程序构建入口点
    var,                  # 创建变量
    cast,                 # 类型转换
    piecewise_linear,      # 分段线性波形
    piecewise_constant,    # 分段常数波形
    linear,               # 线性波形
    constant,             # 恒定波形
    get_capabilities,     # 获取硬件能力
    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.cas_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 | `.cas_simulator.python()` | 基于 SciPy ODE 求解器 |
| Julia | `.cas_simulator.julia()` | (开发中) |

### 硬件

| 后端 | 路径 | 描述 |
|------|------|------|
| CAS Aquila | `.cas.aquila()` | 直接连接 CAS Aquila QPU |
| Braket Aquila | `.braket.aquila()` | 通过 AWS Braket 访问 |
| Braket 模拟器 | `.braket.local_emulator()` | AWS Braket 本地模拟器 |

### 设备字符串

```python
# 也可以使用 device() 方法指定
program.device("cas.aquila").run(100)
program.device("braket.aquila").run(100)
program.device("braket.local_emulator").run(100)
program.device("cascaqit.python").run(100)
```

## 并行化

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

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

# 结果自动合并
results = parallelized_program.cas_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.cas_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
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
```

### 使用 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/             # 构建器
│   │   ├── start.py             # 程序入口
│   │   ├── field.py             # 字段 (Rabi, Detuning, Phase)
│   │   ├── waveform.py          # 波形定义
│   │   ├── spatial.py           # 空间调制
│   │   ├── pragmas.py           # 编译指令
│   │   └── executor/            # 执行后端路由
│   ├── ir/                      # 中间表示
│   │   ├── scalar.py            # 标量表达式
│   │   ├── control/             # 控制流 (波形、序列)
│   │   ├── location/            # 位置 (布拉维晶格)
│   │   └── analog_circuit.py    # 模拟电路
│   ├── compiler/                # 编译器
│   │   ├── analysis/            # 分析器
│   │   ├── rewrite/             # 重写器
│   │   ├── codegen/             # 代码生成
│   │   └── passes/              # 编译 pass
│   ├── dispatch/                # 任务分发
│   ├── simulator/               # 模拟器
│   ├── job/                     # 任务管理
│   └── visualization/           # 可视化
├── tests/                       # 测试
├── docs/                        # 文档
└── examples/                    # 示例
```

## 文档

- **快速入门**: [快速入门指南](docs/home/quick_start.md)
- **架构设计**: [架构设计文档](docs/architecture.md)
- **编程指南**: [编程指南](docs/programming_guide.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`
- `amazon-braket-sdk>=1.78.0`
- `juliacall>=0.9.14`
- `beartype>=0.15.0`