cqlib-tianyan

天衍量子云平台客户端库——支持 Rust、Python 和 C

English · Rust 教程 · Python 教程 · C 教程

---

简介

cqlib-tianyan 是访问天衍量子云平台（qc.zdxlz.com）的客户端库，提供：

• 🔐 认证：API Key 一键登录，凭据自动持久化与刷新
• 🖥️ 后端管理：列举量子计算机，查看拓扑与校准配置
• ⚛️ 任务提交：提交 QCIS 线路，支持批量（自动拆分，单批最多 50 条）
• 📊 结果获取：阻塞等待或非阻塞状态查询
• 🎯 读取误差矫正：逆混淆矩阵方法，默认自动启用（≤ 14 比特）

核心库用 Rust 实现，并提供 Python（PyO3）和 C（cbindgen）两种语言绑定。

---

快速开始

Rust

cargo add cqlib-tianyan

use cqlib_tianyan::TianyanPlatform;
use std::time::Duration;

let platform = TianyanPlatform::login(&std::env::var("TIANYAN_API_KEY")?)?;
let backend  = platform.get_backend("tianyan-287")?;
let task     = backend.run(vec!["H Q1\nH Q8\nCZ Q1 Q8\nH Q8\nM Q1\nM Q8".into()], 1000)?;
let results  = task.wait(Duration::from_secs(120), Duration::from_secs(5))?;

for r in &results {
    println!("计数: {:?}", r.counts());
}

→ 完整 Rust 教程

Python

pip install cqlib-tianyan

import os
from cqlib_tianyan import TianyanPlatform

platform = TianyanPlatform.login(os.environ["TIANYAN_API_KEY"])
backend  = platform.get_backend("tianyan-287")
task     = backend.run(["H Q1\nH Q8\nCZ Q1 Q8\nH Q8\nM Q1\nM Q8"], shots=1000)
results  = task.wait(timeout=120, poll_interval=5)

print(results[0].counts())

→ 完整 Python 教程

C

# 构建库（在 workspace 根目录执行）
cargo build -p binding-c --release

#include "cqlib_tianyan.h"

TianyanPlatformC *p = tianyan_platform_login(getenv("TIANYAN_API_KEY"));
TianyanBackendC  *b = tianyan_platform_get_backend(p, "tianyan-287");

const char *circuits[] = {"H Q1\nH Q8\nCZ Q1 Q8\nH Q8\nM Q1\nM Q8"};
TianyanTaskC     *t = tianyan_backend_run(b, circuits, 1, 1000);
TianyanResultList *r = tianyan_task_wait(t, 120.0, 5.0);

printf("counts: %s\n", tianyan_result_counts_json(r, 0));

tianyan_result_list_free(r);
tianyan_task_free(t);
tianyan_backend_free(b);
tianyan_platform_free(p);

→ 完整 C 教程

---

语言绑定

语言	crate/模块	文档
Rust	crates/cqlib-tianyan	中文 · English
Python	crates/binding-python	中文 · English
C	crates/binding-c	中文 · English

---

项目结构

cqlib-tianyan/
├── crates/
│   ├── cqlib-tianyan/     # 核心 Rust 库
│   ├── binding-python/    # Python 绑定（PyO3）
│   └── binding-c/         # C 绑定（cbindgen）
└── docs/                  # 各语言详细教程

---

构建

本项目使用 Make 编排多语言构建，也可直接使用 Cargo 构建 Rust 部分。

使用 Make（推荐 macOS/Linux）

make all       # 构建所有（Rust + C + Python wheel）
make rust      # 仅构建 Rust（自动排除 Python 绑定）
make python    # 构建 Python wheel（需 maturin）
make c         # 构建 C 绑定并运行测试
make test      # 运行所有测试
make clean     # 清理所有构建产物

使用 Cargo

# 构建 Rust crate（自动排除需 maturin 的 Python 绑定）
cargo build --workspace --exclude binding-python

# 运行测试
cargo test --workspace --exclude binding-python

Windows 平台

Windows 未预装 Make，建议直接使用 Cargo + Maturin：

# 构建 Rust 部分
cargo build --workspace --exclude binding-python

# 构建 Python 绑定（需先安装 maturin: pip install maturin）
cd crates/binding-python
maturin build --release

或使用 Git Bash / WSL 获得 Make 支持。

---

许可证

Apache License 2.0 · Copyright © China Telecom Quantum Group 2026