科学计算【免费下载链接】qiskitQiskit is an open-source SDK for working with quantum computers at the level of extended quantum circuits, operators, and primitives.项目地址https://gitcode.com/gh_mirrors/qi/qiskit点击查看免费下载导读本文围绕 Qiskit 仓库中 docs/cdoc/qk-circuit-library.rst 这一 C API 文档展开系统讲解 Qiskit C APIqiskit.h中“Circuit Library电路库”这一功能域包括两种核心数据类型QkPauliProductRotation与QkPauliProductMeasurement的内存布局与所有权语义以及QkCircuitLibrary函数组中 IQP、NLocal、Quantum Volume、Suzuki-Trotter 等常用高阶电路构造入口。读完本文你将掌握如何在纯 C 程序中直接构造和解析基于 Pauli 乘积的电路指令、如何调用电路库生成模型电路并能结合仓库源码crates/cext/src/circuit_library 与 test/c/test_pbc.c理解其底层实现与测试验证方式。一、Circuit Library 在 Qiskit C API 中的定位Qiskit C API 是 Qiskit 面向编译型语言提供的底层接口直接暴露内部 Rust 数据模型CircuitData、Param、PackedOperation等的稳定 ABI。根据 docs/cdoc/index.rst 的说明它有两种预期使用模式独立共享库模式在不依赖 Python 运行时的编译型语言如 C/C中创建和操作 Qiskit 对象Python 扩展模式编译QISKIT_PYTHON_EXTENSION宏后在 Python 扩展模块中直接与 Rust 对象交互避免经过 Python 层以换取性能。Circuit Library电路库正是该 C API 的一个独立功能域文档开篇给出的定义是The Qiskit circuit library contains functions and higher-level building blocks for building commonly used quantum circuits.即电路库提供构建常用量子电路的函数与高层积木。在 Python 侧这对应qiskit.circuit.library模块而在 C API 侧它收敛为两类内容Data types数据类型QkPauliProductRotationPauli 乘积旋转与QkPauliProductMeasurementPauli 乘积测量Functions函数组QkCircuitLibraryDoxygen 组涵盖 IQP、NLocal、Quantum Volume、Suzuki-Trotter 以及 Pauli 乘积数据的释放等入口。整个 C API 的头文件由 crates/bindgen/include/qiskit.h 统一暴露其中qiskit/types.h、qiskit/funcs.h由 cbindgen 自动生成而qiskit/funcs_py.h则由 Qiskit 的pyext生成Python 扩展模式下使用。二、核心数据类型Pauli 乘积旋转与测量2.1 ZX 格式用两个布尔数组表示 PauliC API 文档中QkPauliProductRotation与QkPauliProductMeasurement两个结构体共享同一种 Pauli 编码方式——ZX 格式。从源码 crates/cext/src/circuit_library/pbc.rs 的注释可以看到A Pauli product rotation implements a rotation of anangleabout an axis defined by a Pauli product onlenqubits. The Pauli here is represented in ZX format with two Boolean arrays representing the Z and X components.也就是说一个长度为len的 Pauli 字符串被拆成两条等长的布尔数组Pauli 算符Z 分量X 分量I恒等falsefalseXfalsetrueYtruetrueZtruefalse例如测试 test/c/test_pbc.c 中的check_paulis辅助函数就按上述规则校验PX → (xtrue, zfalse)、PY → (xtrue, ztrue)、PZ → (xfalse, ztrue)。这种编码把一个 Pauli 乘积压缩为两个长度len的bool数组非常适合 C 层直接以裸指针传递。2.2 QkPauliProductRotation绕 Pauli 轴旋转Rust 侧定义pbc.rs字段如下字段类型含义zbool*长度len的 Z 分量数组xbool*长度len的 X 分量数组lensize_tPauli 项数作用量子比特数angleQkParam*旋转角度Param可为常量或参数表达式语义上QkPauliProductRotation实现的是绕某个 Pauli 乘积所定义轴、角度为angle的旋转即exp(-i θ P / 2)其中P是 Pauli 乘积。C 文档示例circuit.rs构造一个 IXYZ 旋转并追加到电路// build a IXYZ Pauli rotation bool x[4] {false, true, true, false}; bool z[4] {false, false, true, true}; QkParam *angle qk_param_from_double(1.0); QkPauliProductRotation rotation {x, z, 4, angle}; // append it to a circuit QkCircuit *circuit qk_circuit_new(10, 1); uint32_t qubits[4] {0, 1, 2, 3}; qk_circuit_pauli_product_rotation(circuit, rotation, qubits); // do something with the circuit... and then free it qk_param_free(angle); qk_circuit_free(circuit);2.3 QkPauliProductMeasurement向 Pauli 本征空间投影QkPauliProductMeasurement实现的是向指定 Pauli 乘积本征空间的投影测量pbc.rs字段类型含义zbool*长度len的 Z 分量数组xbool*长度len的 X 分量数组lensize_tPauli 项数flip_outcomebool是否带有负号翻转测量结果flip_outcome字段对应 Rust 内部neg标志circuit.rs 中neg: c_data.flip_outcome表示测量对应的 Pauli 乘积前带有负号需要翻转经典结果。C 文档示例构造一个 XZ 测量// build a XZ Pauli measurement bool x[2] {true, false}; bool z[2] {false, true}; QkPauliProductMeasurement measure {x, z, 2, false}; // append it to a circuit QkCircuit *circuit qk_circuit_new(10, 1); uint32_t qubits[2] {0, 2}; uint32_t clbit 0; qk_circuit_pauli_product_measurement(circuit, measure, qubits, clbit); // do something with the circuit... and then free it qk_circuit_free(circuit);注意该测量在qk_circuit_new(10, 1)下仅占用 1 个 clbitclbit参数为单个uint32_t多个测量需自行管理经典比特编号。2.4 内存所有权规则谁分配、谁释放这两个结构体虽然名为“数据类型”但其内部z、x数组和angle指针的所有权语义是使用中最大的坑。文档明确区分两种来源Rust 分配的数据通过qk_circuit_inst_pauli_product_rotation/qk_circuit_inst_pauli_product_measurement从电路指令中拷贝出的数据其内部内存由 Rust 侧Box::into_raw泄漏给 C 使用见 circuit.rs必须调用对应清理函数释放qk_pauli_product_rotation_clear(inst)qk_pauli_product_measurement_clear(inst)C 自己分配的数据如上面示例中用栈数组构造的结构体内部指针由 C 管理不能调用*_clear只需自行释放angleqk_param_free(angle)。pbc.rs 的注释以代码对比方式给出了这对规则// C-allocated data: do NOT call qk_pauli_product_rotation_clear(rotation)! bool z[4] {false, false, true, true}; bool x[4] {false, true, true, false}; QkParam *angle qk_param_from_double(1.0); QkPauliProductRotation rotation {z, x, 4, angle}; qk_param_free(angle);qk_pauli_product_rotation_clear的实现pbc.rs会通过Box::from_raw归还x、z切片与angle的堆内存并把所有字段重置为null/0防止二次释放。2.5 指令类型与读取校验在电路内部PPR/PPM 对应OperationRef::PauliProductRotation与OperationRef::PauliProductMeasurementcircuit.rs 与 circuit.rs。读取指令数据前文档建议先用qk_circuit_instruction_kind验证指令类型等于QkOperationKind_PauliProductRotation或..._PauliProductMeasurement若索引指向其他类型qk_circuit_inst_*会返回QkExitCode_InvalidOperationKind而不写入数据。三、在电路上追加与读取 Pauli 乘积指令QkCircuitLibrary之外的追加/读取入口实际属于QkCircuit组但它们是 Circuit Library 数据类型的主要消费者文档示例大量使用。四个关键函数全部位于 crates/cext/src/circuit.rs函数作用位置qk_circuit_pauli_product_rotation向电路追加一个 PPRcircuit.rs#L1779qk_circuit_inst_pauli_product_rotation按索引取出 PPR 数据circuit.rs#L1836qk_circuit_pauli_product_measurement向电路追加一个 PPMcircuit.rs#L1901qk_circuit_inst_pauli_product_measurement按索引取出 PPM 数据circuit.rs#L19593.1 追加操作的底层实现从源码看qk_circuit_pauli_product_rotation的实现circuit.rs#L1789-L1807做了三件事把 C 传入的z/x裸指针读取为 Rust[bool]切片并to_vec()拷贝克隆angle作为参数Parameters::Params(smallvec![angle.clone()])通过PackedOperation::from_pauli_based(Box::new(PauliBased::PauliProductRotation(...)))打包后push_packed_operation压入电路。由于是拷贝语义C 侧在调用后即可自由释放自己的数组这也解释了为什么取出时反过来需要*_clear手动归还 Rust 泄漏出来的内存。3.2 一个完整的“追加—读取—校验”流程结合 test/c/test_pbc.c 的check_pauli_rotation测试辅助函数一个典型的使用闭环如下// 1) 追加见上文示例 qk_circuit_pauli_product_rotation(circuit, rotation, qubits); // 2) 按索引读取先确认类型再取数据 assert(qk_circuit_operation_kind(circuit, index) QkOperationKind_PauliProductRotation); QkPauliProductRotation inst; qk_circuit_inst_pauli_product_rotation(circuit, index, inst); // 3) 校验角度、Pauli 分量与 qubits ... double angle qk_param_as_real(inst.angle); QkCircuitInstruction ci; qk_circuit_get_instruction(circuit, index, ci); // ... 对比 ci.qubits[i] 与 inst.x / inst.z ... // 4) 释放读取所得数据由 Rust 分配必须 clear qk_circuit_instruction_clear(ci); qk_pauli_product_rotation_clear(inst);四、QkCircuitLibrary 函数组高阶电路构造入口QkCircuitLibraryDoxygen 组是电路库的“Functions”主体。在仓库源码中凡标注ingroup QkCircuitLibrary的extern C函数都属于该组分散在 crates/cext/src/circuit_library 目录下。它们生成的电路统一返回QkCircuit*即 RustCircuitData的泄漏指针调用者必须用qk_circuit_free释放。函数生成电路源码位置qk_circuit_library_iqp瞬时量子多项式IQP电路iqp.rs#L48qk_circuit_library_random_iqp随机 IQP 电路iqp.rs#L106qk_circuit_library_n_localNLocal 变分电路n_local.rs#L175qk_circuit_library_n_local_settings_defaultNLocal 默认配置n_local.rs#L274qk_circuit_library_quantum_volumeQuantum Volume 模型电路quantum_volume.rs#L46qk_circuit_library_suzuki_trotterSuzuki-Trotter 演化电路suzuki_trotter.rs#L46qk_pauli_product_rotation_clear/qk_pauli_product_measurement_clearPauli 乘积数据清理pbc.rs#L714.1 IQPqk_circuit_library_iqpQkCircuit *qc qk_circuit_library_iqp(num_qubits, interactions, check_input);interactions行主序的n×n个int64_t交互矩阵n num_qubits对角元设置 T 类相位幂次上三角编码两量子比特 CPhase 交互iqp.rs#L22-L24check_input true时校验矩阵对称性非对称返回NULLnum_qubits 0时返回空电路num_qubits 0但interactions NULL时返回NULL。qk_circuit_library_random_iqp(num_qubits, seed)则在内部生成随机对称整数矩阵seed 0时从系统熵源取随机种子iqp.rs#L106-L110。4.2 NLocalqk_circuit_library_n_local与QkNLocalSettingsNLocal 电路由交替的旋转层与纠缠层构成旋转层中参数化电路块“堆叠”作用于各量子比特纠缠层则按某种纠缠策略连接块每层重复reps次默认末尾追加一个旋转层n_local.rs#L96-L130。size_t num_qubits 2; QkGate rotation_blocks[1] {QkGate_H}; QkGate entanglement_blocks[1] {QkGate_CRX}; QkNLocalSettings settings qk_circuit_library_n_local_settings_default(); settings.reps 2; // 默认是 QkEntanglementStrategy_Full这里改用 Linear settings.entanglement_strategy QkEntanglementStrategy_Linear; QkCircuit *qc qk_circuit_library_n_local(num_qubits, rotation_blocks, 1, entanglement_blocks, 1, settings); qk_circuit_free(qc);QkNLocalSettings字段n_local.rs#L38-L51及默认值n_local.rs#L53-L63字段默认值说明entanglement_strategyFull纠缠策略见下表reps3旋转层与纠缠层的重复次数parameter_prefixNULL映射为θ生成参数的默认前缀需指向以\0结尾的 UTF-8 字符串insert_barriersfalse是否在层间插入 barrierskip_final_rotation_layerfalse是否跳过末尾的旋转层QkEntanglementStrategy枚举n_local.rs#L67-L94提供 6 种策略枚举值含义Full每个量子比特与其余所有比特纠缠Linear相邻i与i1两两纠缠ReverseLinear反向线性纠缠Circular线性纠缠外加首尾比特的“长”纠缠Pairwise两层先偶数对、后奇数对Scashifted-circular-alternating首尾长纠缠逐块平移4.3 Quantum Volumeqk_circuit_library_quantum_volumeQkCircuit *qc qk_circuit_library_quantum_volume(10, 10, -1);生成用于测量 Quantum Volume 指标的随机模型电路由多层 Haar 随机 SU(4) 元素构成作用于随机二划分的量子比特对quantum_volume.rs#L17-L44。seed 0表示从系统熵取随机种子。该函数默认多线程线程池大小等于 CPU 数可通过环境变量RAYON_NUM_THREADS调整例如RAYON_NUM_THREADS4限制为 4 线程。4.4 Suzuki-Trotterqk_circuit_library_suzuki_trotter基于高阶 Suzuki-Trotter 乘积公式从可观测量的 Pauli 项和生成演化电路suzuki_trotter.rs#L18-L52QkObs *obs qk_obs_zero(1); QkBitTerm op1_bits[1] {QkBitTerm_X}; QkObsTerm term1 {(QkComplex64){1.0, 0.0}, 1, op1_bits, (uint32_t[1]){0}, 1}; qk_obs_add_term(obs, term1); // ... 继续添加 Y 项 ... QkCircuit *qc qk_circuit_library_suzuki_trotter(obs, /*order*/2, /*reps*/1, /*time*/0.1, /*preserve_order*/true, /*insert_barriers*/false); qk_obs_free(obs); qk_circuit_free(qc);参数语义order为乘积公式阶数高阶基于递归见源码引用的 Berry 等人的文献reps为时间步数time为演化时间preserve_orderfalse允许重排算符项以获得更浅的电路单项目标时无影响insert_barriers控制项演化间是否插入 barrier。4.5 与 transpiler 的配合转换为 Pauli 旋转QkPauliProductRotation/QkPauliProductMeasurement并非只能手工构造还可以由标准门电路自动转换得到。C API 提供了两个独立 pass 入口convert_to_pauli_rotations.rsqk_transpiler_pass_standalone_convert_to_pauli_rotations(circuit)把电路中少于 4 量子比特的标准门就地转换为pauli_product_rotation序列、测量转换为pauli_product_measurement指令。注意电路包含非标准门时该 pass 会 panic文档建议的工作流是先转译到标准基尽量保留 RXX 等旋转门再调用本 passconvert_to_pauli_rotations.rs#L21-L25qk_transpiler_pass_standalone_litinski_transformation(circuit, false)Litinski 变换同样产出 PPR/PPMlitinski_transformation.rs 的文档注释与 test/c/test_pbc.c#L26-L57 的测试均可印证。测试 test/c/test_pbc.c#L62-L108 验证了转换后的门统计4 量子比特、含 2 次测量的电路经convert_to_pauli_rotations后得到 13 个pauli_product_rotation与 2 个pauli_product_measurement指令。五、Python 侧的对称实现原理对照C API 的电路库并非凭空存在它与 Rust 驱动的 Python 实现共享同一批核心算法。Python 扩展模块在 crates/circuit_library/src/lib.rs 中注册了pauli_evolution、pauli_feature_map、get_entangler_map、iqp、random_iqp、quantum_volume、n_local与Block等入口。其中pauli_evolutionpauli_evolution.rs的实现可以直观说明 PPR 类指令背后的量子线路原理Pauli 演化被实现为基变换到 Pauli-Z 基 → CX 链 → 最后一个量子比特上的单比特 Rz 旋转 → 反算 CX 链 → 逆基变换。例如演化 Pauli 串XIYZ的电路草图源码注释中原样给出0: ┤ H ├──────┤ X ├┤ Rz(2) ├┤ X ├┤ H ├──────── 1: ─────────────┼─────────────┼─────────────── 2: ┤ √X ├┤ X ├──■─────────────■──┤ X ├┤ √Xdg ├ 3: ────────■───────────────────────■──────────其 Python 侧签名pauli_evolution.rs#L54为pauli_evolution(num_qubits, sparse_paulis, insert_barriersfalse, do_fountainfalse)其中sparse_paulis元素形如(XIYZ, [0,1,2,3], 2)——Pauli 串 量子比特索引 RZ 旋转角。源码中还处理了两个值得注意的边界全恒等 Pauli 串如ii会被累加为全局相位并乘以-0.5因子pauli_evolution.rs#L73-L110do_fountaintrue时 CX 采用“喷泉”形状每个 CX 以顶层比特为目标false时采用相邻比特“链”状传播。理解这条 Python/Rust 实现有助于把握 C API 中 PPR 结构体的语义来源angle对应演化时间旋转角z/x数组对应 Pauli 串的 ZX 编码。六、使用前提与边界条件头文件与宏使用前#include qiskit.h。若作为 Python 扩展的一部分使用必须在 include 之前定义QISKIT_PYTHON_EXTENSION此时全部 API 符号将解析为查表函数指针并在每个编译单元调用一次qk_import()通常在PyInit_*内否则运行时可能空指针崩溃。详见 docs/cdoc/config.rst。接口实验性docs/cdoc/index.rst明确说明该 C API 仍属实验性质接口可能在 minor 版本之间变化。内存纪律qk_circuit_library_*返回的电路必须qk_circuit_free从电路读出的 PPR/PPM 数据必须qk_*_clearC 自建的结构体则不能调用*_clear。混淆所有权会导致重复释放或内存泄漏。Pass 限制convert_to_pauli_rotations遇到非标准门会 panic需要先转译到标准基。测试佐证仓库的 C 测试 test/c/test_pbc.c 覆盖了 Litinski 变换与 PPR 转换后的门统计、PPR/PPM 的角度/Pauli/量子比特/经典比特逐项校验可作为自行实现时的参考基线C API 整体测试入口见 test/c 目录与 test/c/CMakeLists.txt。结语Qiskit C API 的 Circuit Library 域以两个紧凑的 ZX 编码结构体承载了 Pauli 乘积旋转与测量以一组qk_circuit_library_*函数覆盖了 IQP、NLocal、Quantum Volume、Suzuki-Trotter 等常用高阶电路构造并与 transpiler 的 Pauli 转换 pass 无缝衔接。掌握其内存所有权规则与 ZX 编码约定即可在纯 C 工程或 Python 扩展中稳定、高效地使用这套面向编译型语言的量子电路积木。赞分享科学计算【免费下载链接】qiskitQiskit is an open-source SDK for working with quantum computers at the level of extended quantum circuits, operators, and primitives.项目地址https://gitcode.com/gh_mirrors/qi/qiskit点击查看免费下载相关推荐快速上手Skywork-Reward-V2-Qwen3-8B5分钟学会对话评分快速上手Skywork Reward V2 Qwen3 8B5分钟学会对话评分 Skywork Reward V2 Qwen3 8B是一款强大的对话评分模型Maths-CS-AI-Compendium 向量乘积全解内积、点积、余弦相似度、叉积与三重积Maths CS AI Compendium 向量乘积全解内积、点积、余弦相似度、叉积与三重积 本文是 maths cs ai compendium 开源教材文档教程知识库CANN ops-math 算子指南aclnnCumprod 与 aclnnInplaceCumprod 累积乘积接口原理与调用实战CANN ops math 算子指南aclnnCumprod 与 aclnnInplaceCumprod 累积乘积接口原理与调用实战 本指南以 CANN op算子库人工智能CANN上一篇Stasis核心功能详解控制器、布局与模板渲染完全指南下一篇OpenCore Legacy Patcher深度解析让旧Mac焕发新生的技术革命创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考