qiskit

Qiskit

使用当前 Qiskit 2.x API 构建电路、准备兼容硬件指令集架构（ISA）的电路，并通过 V2 原语执行。

此技能已于 2026-07-23 根据 PyPI 版本 qiskit==2.5.0、qiskit-ibm-runtime==0.48.0 和 qiskit-aer==0.17.2 验证。更改版本固定项或记录新发布的行为前，请先查看 references/sources.md。

选择合适的路径

目标	推荐接口
精确的本地采样	qiskit.primitives.StatevectorSampler
精确的本地期望值	qiskit.primitives.StatevectorEstimator
高性能或含噪模拟	Qiskit Aer
IBM QPU 采样	qiskit_ibm_runtime.SamplerV2
IBM QPU 期望值与缓解	qiskit_ibm_runtime.EstimatorV2
不支持原生原语的后端	BackendSamplerV2 或 BackendEstimatorV2
开放系统或主方程动力学	优先选择 QuTiP
可微分量子机器学习	除非需要 Qiskit 集成，否则优先选择 PennyLane

安装

创建隔离环境，只安装所需的组件：

uv venv --python 3.13
source .venv/bin/activate

# Core SDK plus plotting support
uv pip install "qiskit[visualization]==2.5.0"

# Add only when needed
uv pip install "qiskit-ibm-runtime==0.48.0"
uv pip install "qiskit-aer==0.17.2"

不要安装 qiskit-terra；它已被 qiskit 发行版取代。Qiskit Runtime、Aer、Nature、Machine Learning、Optimization 和 Algorithms 都是独立发行版。

有关 IBM 账户设置、适用于 CI 的凭据处理、可选软件包和环境修复，请阅读 references/setup.md。

核心工作流

每个面向硬件的工作负载都遵循以下顺序：

1. 映射问题，将其转换为电路；对于 Estimator，还要转换为一个或多个可观测量。
2. 优化参数化电路，使其适用于所选后端。
3. 将布局应用到每个可观测量。
4. 通过使用 Primitive Unified Blocs（PUB）的 V2 原语执行 ISA 电路。
5. 分析寄存器相关的结果、元数据、不确定性和资源使用情况。

不要在每次优化器迭代中绑定并重新编译参数化电路。先编译一次参数化电路，再在 PUB 中传入参数数组。

快速本地采样

from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()  # creates the classical register named "meas"

sampler = StatevectorSampler(seed=7)
pub_result = sampler.run([circuit], shots=1024).result()[0]
counts = pub_result.data.meas.get_counts()
print(counts)

Sampler V2 会保留 shots 和经典寄存器结构。请使用寄存器的实际名称访问它；measure_all() 使用 meas。

快速本地估计

import numpy as np
from qiskit import QuantumCircuit
from qiskit.circuit import Parameter
from qiskit.primitives import StatevectorEstimator
from qiskit.quantum_info import SparsePauliOp

theta = Parameter("theta")
circuit = QuantumCircuit(2)
circuit.ry(theta, 0)
circuit.cx(0, 1)

observable = SparsePauliOp.from_list([("ZZ", 1.0), ("XX", 0.5)])
parameter_values = [[0.0], [np.pi / 4], [np.pi / 2]]

estimator = StatevectorEstimator(seed=7)
pub = (circuit, observable, parameter_values)
pub_result = estimator.run([pub]).result()[0]
print(pub_result.data.evs)

Estimator 电路不应包含最终测量。PUB 数组会进行广播；构造大型扫描前，请确认电路参数顺序。

IBM QPU 采样

此示例假设已按照 references/setup.md 中的说明安全保存凭据。它不会嵌入或打印 API 密钥。

from qiskit import QuantumCircuit
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler

service = QiskitRuntimeService()
backend = service.least_busy(
    operational=True,
    simulator=False,
    min_num_qubits=2,
)

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()

pass_manager = generate_preset_pass_manager(
    backend=backend,
    optimization_level=1,
    seed_transpiler=7,
)
isa_circuit = pass_manager.run(circuit)

sampler = Sampler(mode=backend)
job = sampler.run([isa_circuit], shots=1024)
print("job_id:", job.job_id())
counts = job.result()[0].data.meas.get_counts()

等待结果前，请先保存作业 ID，以便稍后检索作业。

IBM QPU 估计

Runtime Estimator 同时需要 ISA 电路，以及通过转译器布局映射的可观测量：

from qiskit import QuantumCircuit
from qiskit.quantum_info import SparsePauliOp
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_ibm_runtime import EstimatorV2 as Estimator

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
observable = SparsePauliOp.from_list([("ZZ", 1.0)])

pass_manager = generate_preset_pass_manager(
    backend=backend,
    optimization_level=1,
    seed_transpiler=7,
)
isa_circuit = pass_manager.run(circuit)
isa_observable = observable.apply_layout(isa_circuit.layout)

estimator = Estimator(
    mode=backend,
    options={"resilience_level": 1},
)
pub_result = estimator.run(
    [(isa_circuit, isa_observable)],
    precision=0.02,
).result()[0]
print(pub_result.data.evs, pub_result.data.stds)

错误缓解不一定能改善每种工作负载，而且会增加成本。请记录完整的选项和结果元数据。

不可妥协的 Qiskit 2.x 规则

• 使用 V2 原语接口和 PUB 输入。不要编写新的 V1 Sampler、Estimator 或 QuantumInstance 代码。
• Runtime 原语接受 ISA 电路；它们不会替你执行布局、路由和基变换。
• 使用 observable.apply_layout(isa_circuit.layout) 将转译器布局应用于 Estimator 可观测量。
• Runtime 原语使用 mode=backend、mode=session 或 mode=batch。
• 使用 EstimatorV2 设置弹性等级并进行期望值缓解。Sampler 的噪声管理选项不同，且没有 Estimator 风格的弹性等级。
• 将 BackendV2.target、backend.operation_names、backend.coupling_map 和后端的直接属性视为硬件约束的依据。不要使用 backend.configuration() 或 BackendProperties。
• 按经典寄存器名称读取 Sampler 输出。位串按最高有效位在前显示；按照惯例，Qiskit 的量子比特 0 是最低有效位。
• 比较编译设置时使用固定的 seed_transpiler。模拟器种子无法保证 QPU 结果具有确定性。
• qiskit.pulse 已在 Qiskit 2.0 中移除。IBM 硬件请使用受支持的分数门；脉冲模型研究请使用 Qiskit Dynamics。
• QPY 是 Qiskit 原生的电路序列化格式。不要对不可信的电路产物使用 Python pickle。

详细的旧版到当前 API 对照请参阅 references/migration.md。

执行模式

根据工作负载类型和账户套餐选择：

• 作业模式：用于一次性任务；使用 mode=backend 实例化原语。
• 批处理模式：用于一起提交的独立作业；Open Plan 套餐可用。
• 会话模式：用于可从后续优先执行中受益的迭代作业；Open Plan 套餐不可用。

from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler

with Batch(backend=backend, max_time="10m") as batch:
    sampler = Sampler(mode=batch)
    jobs = [sampler.run([circuit], shots=1024) for circuit in isa_circuits]

results = [job.result() for job in jobs]

提交后关闭会话和批处理。退出其上下文后，将停止接受新提交，但已接受的作业仍会完成，具体取决于服务限制。

参考索引

只阅读当前任务所需的文件：

主题	参考资料
版本、安装、身份验证、CI	references/setup.md
电路、参数、控制流、QPY	references/circuits.md
V2 PUB、广播、本地和 Runtime 结果	references/primitives.md
Targets、ISA 电路、布局、Pass Manager	references/transpilation.md
IBM 后端、模式、作业、Aer、缓解	references/backends.md
端到端的映射／优化／执行／分析模式	references/patterns.md
算法、插件、Nature、机器学习、优化	references/algorithms.md
电路、结果、状态和后端图表	references/visualization.md
Qiskit 0.x／1.x 和 Runtime 迁移	references/migration.md
测试、可复现性和故障排除	references/testing.md
上游文档、发行说明和版本基线	references/sources.md

随附脚本

在技能目录中运行：

# Installed-package and legacy-environment checks; no network or credential reads
python scripts/check_environment.py

# Runnable V2 local Sampler and Estimator example
python scripts/run_local_primitives.py --shots 1024 --seed 7

# Read-only IBM backend capability inspection; uses saved credentials
python scripts/inspect_runtime.py --min-qubits 5

Runtime 检查脚本会选择或检查后端，但绝不会提交量子作业。

最终检查清单

返回 Qiskit 代码前：

1. 确认软件包版本和 Python 兼容性。
2. 使用 statevector 原语或 Aer 在本地运行。
3. 验证参数顺序、可观测量量子比特数和经典寄存器名称。
4. 针对确切的 BackendV2 target 进行转译，并检查电路深度和双量子比特操作。
5. 将最终布局应用于每个可观测量。
6. 估算 QPU 成本，并选择作业、批处理或会话模式。
7. 保存作业 ID、软件包版本、种子、后端名称、原语选项和结果元数据。
8. 切勿在源代码、日志、笔记本或版本控制中暴露 API 密钥。

相关技能

• cirq：Google 量子计算框架。
• pennylane：硬件无关的量子机器学习框架，支持自动微分。
• pi-agent：使用 Pi 这个极简终端编码工具框架进行构建和使用。