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 进行过验证。

用途与接口选择

资料提供了一张按目标选择接口的对照表：本地精确采样使用 qiskit.primitives.StatevectorSampler；本地精确期望值使用 qiskit.primitives.StatevectorEstimator；高性能或含噪模拟使用 Qiskit Aer；IBM QPU 采样使用 qiskit_ibm_runtime.SamplerV2；IBM QPU 期望值与误差缓解使用 qiskit_ibm_runtime.EstimatorV2；不支持原生原语的后端使用 BackendSamplerV2 或 BackendEstimatorV2；开放系统或主方程动力学建议使用 QuTiP；可微量子机器学习建议使用 PennyLane，除非需要 Qiskit 集成。

安装方式

资料建议创建隔离环境并仅安装所需组件，示例命令为：uv venv --python 3.13；source .venv/bin/activate；uv pip install "qiskit[visualization]==2.5.0"；按需安装 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。

核心工作流

资料给出的面向硬件的标准流程为：将问题映射为线路，若使用 Estimator 还需一个或多个可观测量；针对所选后端对参数化线路优化一次；将布局应用到每个可观测量；通过 V2 原语使用 Primitive Unified Blocs（PUB）执行 ISA 线路；分析寄存器感知的结果、元数据、不确定度与资源使用。资料强调不要在每次优化器迭代中绑定并重新转译参数化线路，而应转译一次后通过 PUB 传入参数数组。

本地采样与估计示例

本地采样示例使用 QuantumCircuit 构建 2 量子比特线路（h、cx、measure_all），用 StatevectorSampler(seed=7) 运行并读取 pub_result.data.meas.get_counts()。资料说明 Sampler V2 保留 shots 与经典寄存器结构，需按实际寄存器名访问，measure_all() 使用 meas。

本地估计示例使用 Parameter、SparsePauliOp.from_list([("ZZ", 1.0), ("XX", 0.5)]) 和 StatevectorEstimator(seed=7)，通过 PUB 元组 (circuit, observable, parameter_values) 运行并读取 pub_result.data.evs。资料提示 Estimator 线路不应包含最终测量，PUB 数组会广播，构建大规模扫描前需确认线路参数顺序。

IBM QPU 执行

IBM QPU 采样示例通过 QiskitRuntimeService() 获取服务，用 service.least_busy(operational=True, simulator=False, min_num_qubits=2) 选择后端，用 generate_preset_pass_manager 生成 ISA 线路，再用 Sampler(mode=backend) 运行并读取 job.result()[0].data.meas.get_counts()。资料建议在等待结果前保存 job ID 以便后续检索。

IBM QPU 估计示例要求同时提供 ISA 线路和经转译器布局映射的可观测量，使用 observable.apply_layout(isa_circuit.layout)，并通过 Estimator(mode=backend, options={"resilience_level": 1}) 运行，读取 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 用于 resilience level 与期望值缓解，Sampler 有不同的噪声管理选项且没有 Estimator 式 resilience level；以 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。

执行模式

资料按工作负载形态与账户计划给出选择：Job 模式用于一次性工作，以 mode=backend 实例化原语；Batch 模式用于一起提交的独立作业，Open Plan 可用；Session 模式用于受益于优先后续执行的迭代作业，Open Plan 不可用。示例使用 Batch(backend=backend, max_time="10m") 与 Sampler(mode=batch) 提交多个线路。资料提示提交后关闭 session 和 batch，退出其上下文会停止新提交但允许已接受的作业完成，受服务限制约束。

参考文档与脚本

资料列出按任务读取的参考文件：setup.md（版本、安装、认证、CI）、circuits.md（线路、参数、控制流、QPY）、primitives.md（V2 PUB、广播、本地与 Runtime 结果）、transpilation.md（目标、ISA 线路、布局、pass manager）、backends.md（IBM 后端、模式、作业、Aer、缓解）、patterns.md（端到端 map/optimize/execute/analyze 模式）、algorithms.md（算法、插件、Nature、ML、Optimization）、visualization.md（线路、结果、状态与后端绘图）、migration.md（Qiskit 0.x/1.x 与 Runtime 迁移）、testing.md（测试、可复现性与故障排查）、sources.md（上游文档、发布说明与版本基线）。

捆绑脚本包括：python scripts/check_environment.py（已安装包与遗留环境检查，无网络或凭据读取）；python scripts/run_local_primitives.py --shots 1024 --seed 7（可运行的 V2 本地 Sampler 与 Estimator 示例）；python scripts/inspect_runtime.py --min-qubits 5（只读 IBM 后端能力检查，使用已保存凭据）。资料说明 Runtime 检查脚本只选择或检查后端，从不提交量子作业。

最终检查清单

资料要求在返回 Qiskit 代码前确认：包版本与 Python 兼容性；用 statevector 原语或 Aer 本地运行；验证参数顺序、可观测量量子比特数与经典寄存器名；针对确切的 BackendV2 目标转译并检查深度与双量子比特操作；将最终布局应用到每个可观测量；估算 QPU 成本并选择 job、batch 或 session 模式；保存 job ID、包版本、种子、后端名、原语选项与结果元数据；绝不在源码、日志、笔记本或版本控制中暴露 API 密钥。

技能介绍