内置仿真机

Cqlib 针对不同场景提供了两类内置仿真机，均支持多种形式的模拟输出，便于用户进行量子算法验证与测试。

返回数据接口说明。

接口	描述
statevector	返回量子线路的最终状态向量（忽略测量门）。
probs	基于状态向量计算得到的概率分布（忽略测量门）。
measure	根据测量比特和顺序获取的测量概率分布。
sample	根据测量比特和顺序采样得到的实验数据。

1. 状态向量仿真机

Cqlib内置的状态向量仿真机基于全振幅模拟方法，集成并行计算和内存优化技术，能够高效模拟中等规模量子线路，适用于量子算法在本地环境下的快速验证。

from cqlib import Circuit
from cqlib.simulator import StatevectorSimulator

circuit = Circuit(3)
for i in range(3):
    circuit.h(i)
    circuit.cx(i, (i + 1) % 3)
circuit.measure(0)
circuit.measure(2)

sim = StatevectorSimulator(circuit)
print(f"Statevector: {sim.statevector()}\n"
      f"Probabilities: {sim.probs()}\n")

# 根据测量门，获得 Q2 和 Q0 的测量分布和采样数据
print(f"Measure: {sim.measure()}\n"
      f"Sample: {sim.sample(shots=1000)}\n")

    Statevector: {'000': (0.3535533905932737+0j), '001': (0.3535533905932737+0j), '010': (0.3535533905932737+0j), '011': (-0.3535533905932737+0j), '100': (0.3535533905932737+0j), '101': (0.3535533905932737+0j), '110': (0.3535533905932737+0j), '111': (-0.3535533905932737+0j)}
    Probabilities: {'000': 0.12499999999999994, '001': 0.12499999999999994, '010': 0.12499999999999994, '011': 0.12499999999999994, '100': 0.12499999999999994, '101': 0.12499999999999994, '110': 0.12499999999999994, '111': 0.12499999999999994}
    
    Measure: {'00': 0.2499999999999999, '01': 0.2499999999999999, '10': 0.2499999999999999, '11': 0.2499999999999999}
    Sample: {'10': 249, '11': 267, '01': 256, '00': 228}

2. 基于 Torch 的仿真机

Cqlib 还内置了一款基于 PyTorch 的量子仿真后端，利用 PyTorch 的张量运算和自动微分特性，支持 GPU 加速和梯度计算，适用于全振幅模拟与变分量子算法的端到端训练流程。

2.1 计算概率

SimpleSimulator 与状态向量仿真机类似，支持相同的四种输出形式：

from cqlib import Circuit
from cqlib.simulator import SimpleSimulator

circuit = Circuit(3)
for i in range(3):
    circuit.h(i)
    circuit.cx(i, (i + 1) % 3)
circuit.measure(0)
circuit.measure(2)

sim = SimpleSimulator(circuit)
print(f"Statevector: {sim.statevector()}\n"
      f"Probabilities: {sim.probs()}\n")

# 根据测量门，获取 Q2 和 Q0 的测量分布和采样数据
print(f"Measure: {sim.measure()}\n"
      f"Sample: {sim.sample(shots=2000)}\n")

    Statevector: {'000': tensor(0.3536+0.j, dtype=torch.complex128), '001': tensor(0.3536+0.j, dtype=torch.complex128), '010': tensor(0.3536+0.j, dtype=torch.complex128), '011': tensor(-0.3536+0.j, dtype=torch.complex128), '100': tensor(0.3536+0.j, dtype=torch.complex128), '101': tensor(0.3536+0.j, dtype=torch.complex128), '110': tensor(0.3536+0.j, dtype=torch.complex128), '111': tensor(-0.3536+0.j, dtype=torch.complex128)}
    Probabilities: {'000': tensor(0.1250, dtype=torch.float64), '001': tensor(0.1250, dtype=torch.float64), '010': tensor(0.1250, dtype=torch.float64), '011': tensor(0.1250, dtype=torch.float64), '100': tensor(0.1250, dtype=torch.float64), '101': tensor(0.1250, dtype=torch.float64), '110': tensor(0.1250, dtype=torch.float64), '111': tensor(0.1250, dtype=torch.float64)}
    
    Measure: {'00': tensor(0.2500, dtype=torch.float64), '01': tensor(0.2500, dtype=torch.float64), '10': tensor(0.2500, dtype=torch.float64), '11': tensor(0.2500, dtype=torch.float64)}
    Sample: {'11': 526, '01': 467, '00': 506, '10': 501}

2.2 梯度计算

SimpleSimulator 深度融合 PyTorch 的计算图机制，支持量子线路的端到端自动微分能力，可高效执行含参数化量子门的正向模拟与反向梯度传播，适用于变分量子算法的训练任务。

import torch

from cqlib import Circuit, Parameter
from cqlib.simulator import SimpleSimulator

ps = [Parameter(f"p{i}") for i in range(3)]
circuit = Circuit(3, ps)
for i in range(3):
    circuit.h(i)
    circuit.rx(i, ps[i])
circuit.measure(0)
circuit.measure(2)

params = torch.tensor([0.1, 0.2, 0.3], requires_grad=True)
circuit.assign_parameters(params, cache_params=True)
sim = SimpleSimulator(circuit)
probs = sim.measure(dict_format=False)
print(f"Probabilities: {probs}\n")

probs[0].backward()
print(f"Gradients: {params.grad}\n")

Probabilities: tensor([0.2500, 0.2500, 0.2500, 0.2500], dtype=torch.float64,
       grad_fn=<IndexBackward0>)

Gradients: tensor([8.6736e-18, 3.4694e-18, 6.9389e-18])

注意：为了启动梯度计算，在调用 assign_parameters 时需要特别设置 cache_params = True ，以确保模拟过程中参数绑定的可微性。

---