适配器

Cqlib 通过 cqlib-adapter 适配器库实现与主流量子计算生态的兼容与集成：

• 当前支持：Qiskit 扩展模块
• 开发计划：将逐步集成 Pennylane 等主流量子计算框架

1. 安装 Cqlib-Adapter

推荐使用 pip 包管理器安装适配器库：

pip install cqlib-adapter

提示：安装前请确保已配置 Python 环境（3.10及以上），并将 pip 升级至最新版本。

2. Qiskit 扩展模块

主要功能：

• 支持 QCIS 量子门：兼容天衍平台的原生量子门集，比如 X2P,X2M,Y2P,Y2M,XY2P,XY2M；
• 后端设备集成 ：可无缝对接天衍量子云平台进行任务执行；
• 自动编译优化 ：可智能转换与优化量子线路以适配物理设备执行需求。

2.1 QCIS 量子门

详细说明请参考：QCIS 指令说明

以下为 Qiskit 扩展中支持的 QCIS 原生命令说明：

• X2P: X轴方向旋转 π/2
• X2M: X轴方向旋转 -π/2
• Y2P: Y轴方向旋转 π/2
• Y2M: Y轴方向旋转 -π/2
• XY2P: XY轴方向旋转一个指定角度
• XY2M: XY轴方向旋转一个指定角度

特别说明：尽管 H 门并非天衍物理机的原生指令，但为提升编译效率与兼容性，扩展模块保留了 H 门的表达。在实际运行时，系统将自动将 H 门分解为 Y2P 和 RZ 的组合门操作。

2.2 使用示例

2.2.1 构建量子电路

from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister
from cqlib_adapter.qiskit_ext import X2PGate, X2MGate

# 创建量子寄存器与经典寄存器
qs = QuantumRegister(2)
cs = ClassicalRegister(2)
circuit = QuantumCircuit(qs, cs)

# 构建量子线路
circuit.x(qs[1])           # Pauli-X 门
circuit.h(qs[0])           # Hadamard 门（将自动分解为物理门）
circuit.cx(qs[0], qs[1])   # CNOT 门
circuit.append(X2PGate(), [qs[0]])  # 添加 X2P 门
circuit.append(X2MGate(), [qs[1]])  # 添加 X2M 门
circuit.barrier(qs)
circuit.measure(qs, cs)    #测量操作

circuit.draw()

      ┌───┐     ┌─────┐ ░ ┌─┐   
q0_0: ┤ H ├──■──┤ X2p ├─░─┤M├───
      ├───┤┌─┴─┐├─────┤ ░ └╥┘┌─┐
q0_1: ┤ X ├┤ X ├┤ X2m ├─░──╫─┤M├
      └───┘└───┘└─────┘ ░  ║ └╥┘
c0: 2/═════════════════════╩══╩═
                           0  1 

2.2.2 后端设备接入

from cqlib_adapter.qiskit_ext import TianYanProvider

# 初始化认证
provider = TianYanProvider(token='<your-token>')
# 获取所有可用的后端设备
backends = provider.backends()
backends

[<TianYanQuantumBackend('tianyan176')>,
 <TianYanQuantumBackend('tianyan176-2')>,
 <TianYanQuantumBackend('tianyan24')>,
 <TianYanQuantumBackend('tianyan504')>,
 <TianYanSimulatorBackend('tianyan_sw')>,
 <TianYanSimulatorBackend('tianyan_s')>,
 <TianYanSimulatorBackend('tianyan_tn')>,
 <TianYanSimulatorBackend('tianyan_tnn')>,
 <TianYanSimulatorBackend('tianyan_sa')>,
 <TianYanSimulatorBackend('tianyan_swn')>]

获取指定设备：

# 获取指定后端设备 (如'tianyan176-2')
backend = provider.backend('tianyan176-2')
backend

<TianYanQuantumBackend('tianyan176-2')>

2.2.3 拓扑适配

系统会自动根据后端设备的拓扑结构调整量子线路布局，用户无需手动处理物理比特映射。

from qiskit import transpile

tqc = transpile(circuit, backend=backend)
tqc.draw(idle_wires=False)

global phase: π/2
           ┌─────┐┌─────┐┌───┐    ┌───┐ ┌─────┐ ░    ┌─┐
q0_1 -> 51 ┤ X2p ├┤ X2p ├┤ H ├─■──┤ H ├─┤ X2m ├─░────┤M├
           └┬───┬┘└─────┘└───┘ │ ┌┴───┴┐└─────┘ ░ ┌─┐└╥┘
q0_0 -> 57 ─┤ H ├──────────────■─┤ X2p ├────────░─┤M├─╫─
            └───┘                └─────┘        ░ └╥┘ ║ 
     c0: 2/════════════════════════════════════════╩══╩═
                                                   0  1 

2.2.4 基于 Backend 运行任务

backend.run 接口可自动适配目标设备的拓扑结构，用户无需手动调整比特映射或线路结构。

backend = provider.backend('tianyan_sw')

# 在指定后端运行量子线路
job = backend.run([circuit], shots=3000)

# 获取并输出任务结果
print(f'Job ID: {job.job_id()}')
print(f'Job Result: {job.result().get_counts()}')

Job ID: 1932271557272739841
Job Result: {'10': 1502, '1': 1498}

2.2.5 基于 Sampler 运行任务

from cqlib_adapter.qiskit_ext import TianYanSampler

# 初始化采样器，绑定后端设备
sampler = TianYanSampler(backend=backend)

# 提交量子线路并运行
job = sampler.run([circuit], shots=3000)

# 获取并输出任务结果
print(f'Job ID: {job.job_id()}')
print(f'Job Result: {job.result()}')

# 默认经典寄存器命名为 c0
# cs = ClassicalRegister(2)
print(f'Counts: {job.result()[0].data.c0.get_counts()}')

    Job ID: 05547ce8-6f48-4d94-a39c-3aa5d5c8c771
    Job Result: PrimitiveResult([SamplerPubResult(data=DataBin(c0=BitArray(<shape=(), num_shots=3000, num_bits=2>)), metadata={'shots': 3000, 'circuit_metadata': {}})], metadata={'version': 2})
    Counts: {'10': 1468, '01': 1532}

2.3 Qiskit 生态兼容

通过 Cqlib-adapter， 用户可以在 Qiskit 生态系统中（如 qiskit-machine-learning）无缝使用天衍量子计算云平台的算力资源。以下以建构一个简单的 神经网络分类器应用 为示例，演示如何调用天衍后端完成训练任务。

2.3.1 数据准备与可视化

import matplotlib.pyplot as plt
import numpy as np
from IPython.display import clear_output

from qiskit.circuit.library import RealAmplitudes
from qiskit_machine_learning.optimizers import COBYLA
from qiskit_machine_learning.utils import algorithm_globals
from qiskit_machine_learning.algorithms.classifiers import NeuralNetworkClassifier
from qiskit_machine_learning.neural_networks import SamplerQNN
from qiskit_machine_learning.circuit.library import QNNCircuit

algorithm_globals.random_seed = 42

# 生成二分类数据集
num_inputs = 2
num_samples = 20
X = 2 * algorithm_globals.random.random([num_samples, num_inputs]) - 1

# 标签转换：y ∈ {0,1} → y ∈ {-1,+1}
y01 = 1 * (np.sum(X, axis=1) >= 0)  # in { 0,  1}
y = 2 * y01 - 1  # in {-1, +1}
y_one_hot = np.zeros((num_samples, 2))
for i in range(num_samples):
    y_one_hot[i, y01[i]] = 1

# 可视化数据分布
for x, y_target in zip(X, y):
    if y_target == 1:
        plt.plot(x[0], x[1], "bo")
    else:
        plt.plot(x[0], x[1], "go")
plt.plot([-1, 1], [1, -1], "--", color="black")
plt.show()

2.3.2 量子神经网络构建

构建量子特征映射和可训练线路，集成 Qiskit 神经网络模块。

qc = QNNCircuit(ansatz=RealAmplitudes(num_inputs, reps=1))
qc.draw()

     ┌──────────────────────────┐┌──────────────────────────────────────┐
q_0: ┤0                         ├┤0                                     ├
     │  ZZFeatureMap(x[0],x[1]) ││  RealAmplitudes(θ[0],θ[1],θ[2],θ[3]) │
q_1: ┤1                         ├┤1                                     ├
     └──────────────────────────┘└──────────────────────────────────────┘

2.3.3 指定后端设备

from cqlib_adapter.qiskit_ext import TianYanProvider, TianYanSampler

# 初始化并指定后端量子设备
provider = TianYanProvider(token='<your-token>')
sampler = TianYanSampler(provider.backend('tianyan_sw'))

2.3.4 模型训练与优化

from qiskit.primitives import StatevectorSampler as Sampler

# 定义奇偶函数，将比特串映射为 0 或 1
def parity(x):
    return "{:b}".format(x).count("1") % 2

output_shape = 2  # 对应分类任务的输出维度（即奇偶映射的两种可能结果）

# 构建量子神经网络 SamplerQNN
sampler_qnn = SamplerQNN(
    circuit=qc,
    interpret=parity,
    output_shape=output_shape,
    sampler=sampler,
)

    No gradient function provided, creating a gradient function. If your Sampler requires transpilation, please provide a pass manager.

# 回调函数：在调用 .fit() 时动态绘制目标函数值变化图
def callback_graph(weights, obj_func_eval):
    clear_output(wait=True)
    objective_func_vals.append(obj_func_eval)
    plt.title("Objective function value against iteration")
    plt.xlabel("Iteration")
    plt.ylabel("Objective function value")
    plt.plot(range(len(objective_func_vals)), objective_func_vals)
    plt.show()


# 配置分类器，设置优化器和回调函数
sampler_classifier = NeuralNetworkClassifier(
    neural_network=sampler_qnn, optimizer=COBYLA(maxiter=30), callback=callback_graph
)

2.3.5 开始训练

# 初始化用于回调函数的目标函数值记录数组
objective_func_vals = []

# 设置绘图尺寸
plt.rcParams["figure.figsize"] = (12, 6)

# 拟合分类器
sampler_classifier.fit(X, y01)

# 恢复默认绘图尺寸
plt.rcParams["figure.figsize"] = (6, 4)

# 评估分类器性能
sampler_classifier.score(X, y01)

0.8

2.3.6 模型评估

# 执行模型预测
y_predict = sampler_classifier.predict(X)

# 结果可视化：红圈标出分类错误的样本
for x, y_target, y_p in zip(X, y01, y_predict):
    if y_target == 1:
        plt.plot(x[0], x[1], "bo")
    else:
        plt.plot(x[0], x[1], "go")
    if y_target != y_p:
        plt.scatter(x[0], x[1], s=200, facecolors="none", edgecolors="r", linewidths=2)

# 绘制参考分界线
plt.plot([-1, 1], [1, -1], "--", color="black")
plt.show()

---