一个高性能、双模式、拓扑感知的量子计算模拟核心库。

pip install nexus-quantum-core

Project description
NEXUS QUANTUM DEFENSE - 量子计算核心库

版本: 1.5.0 (拓扑感知API版) 作者: 跳舞的火公子

一份为高性能量子模拟而生的核心库，致力于在纯态模拟的效率与混合态模拟的功能之间取得极致平衡。

alt text

alt text

alt text

📖 简介

quantum_core 是一个功能强大、设计精良的Python量子计算模拟库。它封装了从基础的量子态、量子线路数据结构到高性能并行计算引擎的全套工具，旨在为量子算法研究、量子机器学习和带噪量子系统模拟提供一个稳定、高效且易于扩展的底层框架。

本库的核心设计哲学是 “惰性求值” 与 “双模式模拟引擎” 的结合。在理想情况下（无噪声），它通过惰性求值最大化性能，仅在需要时才执行昂贵的态矢量计算。当引入非相干噪声时，它能无缝、不可逆地切换到功能更全面的密度矩阵模拟模式，从而准确地描述混合态的演化。

✨ 核心特性

🧠 惰性求值与双模式引擎:

态矢量模式 (Statevector): 默认模式，用于纯态模拟。门操作仅被记录在电路中，实际计算被推迟到查询结果时，极大提升了构建复杂线路的效率。

密度矩阵模式 (Density Matrix): 当应用非相干噪声（如量子通道）时，系统会自动、不可逆地切换至此模式，能够精确模拟混合态和退相干过程。

⚡️ 高性能计算后端:

纯Python后端: 无任何第三方依赖，保证了极致的稳定性和跨平台兼容性，是逻辑验证和调试的基石。

CuPy GPU加速: 可选的 CuPy 后端，能够利用NVIDIA GPU进行大规模并行计算，显著加速大型量子系统的模拟。

内置CPU并行计算: 对于大规模纯Python模拟，内置了基于 multiprocessing 的并行计算基础设施，可充分利用多核CPU资源加速特定门操作和酉演化。

🏛️ 稳健的架构设计:

中央算子库 (QuantumOperatorLibrary): 所有量子门的定义（矩阵、分解规则、优化内核）都集中管理，是全系统的“单一事实来源”，确保了行为的一致性和可验证性。

可扩展的噪声模型: 通过抽象基类 NoiseModel 定义了清晰的噪声插件接口，用户可以轻松实现自定义的相干或非相干噪声模型，如硬件噪声、关联噪声等。

拓扑感知API (v1.5.0新增): 核心API run_circuit_on_state 接收 topology 参数，能够与外部编译器（如 nexus_optimizer）无缝集成，实现对真实硬件拓扑的感知优化。

🔋 丰富的功能集与API:

全面的门操作集: 支持所有标准单比特、多比特门，以及高级多控制门（Toffoli, MCX, MCZ等）。

算法构建器 (AlgorithmBuilders): 内置了用于快速构建常用量子算法（如QFT, QPE, Grover）和VQA拟设（Hardware-Efficient Ansatz）的便捷工具。

强大的分析能力: 提供了计算哈密顿量期望值、冯·诺依曼纠缠熵、布洛赫矢量、边际概率等高级分析工具。

⚙️ 安装

本核心库被设计为一个独立的Python文件，不依赖任何难以安装的第三方库（CuPy 除外）。

基础安装 (仅CPU)

只需将 quantum_core.py 文件放置在您的项目目录中，即可直接导入使用。

code Python download content_copy expand_less import quantum_core as nq

本库需要 Python 3.8 或更高版本。

可选：启用GPU加速

为了获得极致的模拟性能，您可以安装 CuPy 库来启用GPU加速。请根据您的CUDA版本选择合适的 CuPy 版本进行安装。

例如，如果您的系统安装了CUDA 11.8，可以使用以下命令：

code Bash download content_copy expand_less pip install cupy-cuda11x

如果您的CUDA版本不同，请参考 CuPy官方安装指南 进行安装。

安装完成后，quantum_core 将在启动时自动检测到 CuPy 并优先使用GPU后端。

🚀 快速上手

下面是一个创建贝尔纠缠态 |Φ+⟩ = (|00⟩ + |11⟩)/√2 并验证其概率分布的简单示例。

code Python download content_copy expand_less import quantum_core as nq import math

1. 创建一个包含2个量子比特的初始量子态 |00⟩
   这是一个惰性对象，此时没有进行任何大规模内存分配。
   print("--- 创建初始量子态 ---") initial_state = nq.create_quantum_state(num_qubits=2) print(f"初始态: {initial_state.num_qubits} qubits, 模式: {initial_state._simulation_mode}")

2. 构建一个用于制备贝尔态的量子线路
   print("\n--- 构建量子线路 ---") bell_circuit = nq.QuantumCircuit(num_qubits=2, description="Bell State Preparation") bell_circuit.h(0) # 在 q0 上应用 Hadamard 门 bell_circuit.cnot(0, 1) # 在 (q0, q1) 上应用 CNOT 门 print(bell_circuit)

3. 在初始态上执行线路，得到一个新的演化后状态
   此操作遵循函数式编程的不可变性原则，原始的 initial_state 不会被修改。
   此时，计算仍然是惰性的。
   print("\n--- 执行线路 (惰性) ---") final_state = nq.run_circuit_on_state(initial_state, bell_circuit) print(f"最终态: {final_state.num_qubits} qubits, 模式: {final_state._simulation_mode}") print(f"最终态内部线路指令数: {len(final_state.circuit.instructions)}")

4. 获取测量概率分布
   这是第一个需要实际计算结果的操作，它将触发内部的“展开计算”。
   print("\n--- 获取结果 (触发计算) ---") probabilities = nq.get_measurement_probabilities(final_state)

5. 验证结果
   print(f"\n测量概率: {probabilities}") expected_probs = [0.5, 0.0, 0.0, 0.5] assert all(math.isclose(p_actual, p_expected, abs_tol=1e-9) for p_actual, p_expected in zip(probabilities, expected_probs)) print("✅ 验证成功！最终态为贝尔态 |Φ+⟩。") 核心概念与架构 🧠 惰性求值与双模式引擎

这是本库的核心设计。

惰性求值: 在 statevector 模式下，对 QuantumState 对象应用门操作（如 state.h(0)) 不会立即计算新的态矢量。相反，它仅将指令记录到内部的 QuantumCircuit 中。这使得构建包含数千个门的复杂线路几乎是零成本的。只有当您请求一个需要完整状态的结果时（例如 get_measurement_probabilities()），系统才会一次性地、高效地执行所有累积的指令来计算最终的态矢量。

双模式引擎:

statevector 模式: 默认模式，使用一个 (2^N,) 的复数向量来表示纯态。计算效率高，内存占用相对较小。

density_matrix 模式: 当您应用一个非相干噪声通道（例如 apply_quantum_channel）时，系统会自动将态矢量 |ψ⟩ 转换为密度矩阵 ρ = |ψ⟩⟨ψ|，并将模式不可逆地切换为 density_matrix。此后，所有操作都将在一个 (2^N, 2^N) 的密度矩阵上进行，这虽然计算成本更高，但能够精确地模拟混合态和退相干过程。

code Python download content_copy expand_less

演示模式切换
state = nq.create_quantum_state(1) print(f"初始模式: {state._simulation_mode}") # -> statevector

应用一个非相干噪声通道
state.apply_quantum_channel( channel_type='depolarizing', target_qubits=[0], params={'probability': 0.1} )

print(f"应用噪声后的模式: {state._simulation_mode}") # -> density_matrix 🏛️ 量子算子库 (QuantumOperatorLibrary)

QuantumOperatorLibrary 是本库的基石。它是一个中央注册中心，存储了所有内置量子门的完整定义 (OperatorDefinition)。每个定义都包含：

数学表示: 固定的酉矩阵（如 X 门）或用于生成酉矩阵的函数（如 RX(θ)）。

分解规则: 对于复合门（如 SWAP），定义了如何将其分解为更基础的门。

优化内核: 指向 _StateVectorEntity 或 _DensityMatrixEntity 内部专门优化的、无需构建全局矩阵即可执行操作的高性能函数。

这种设计确保了全系统对门操作的解释和执行是统一、可验证且高效的。

⚡️ 并行计算

本库内置了基于 multiprocessing 的CPU并行计算框架，可用于加速大规模（通常 > 12量子比特）的纯Python模拟。

启用并行计算: 您必须在脚本的主执行块 (if name == 'main':) 中显式启用并行模式。

code Python download content_copy expand_less import quantum_core as nq import sys

if name == 'main': # 启用并行计算，自动检测CPU核心数 nq.enable_parallelism()

try:

# 在这里运行您的大规模模拟
state = nq.create_quantum_state(14)
state.h(0) # 这个操作在展开时可能会被并行化

# ... 更多操作 ...

# 触发计算
probs = nq.get_measurement_probabilities(state)
print("大规模模拟完成。")

finally:

# 在程序结束前优雅地关闭并行池
nq.disable_parallelism()

📚 公共 API 参考

以下是 quantum_core 提供的核心公共API函数。

create_quantum_state(num_qubits)

创建一个处于 |0...0⟩ 态的初始惰性量子态。

参数 类型 描述 num_qubits int 要创建的量子态的比特数。

返回: 一个新的 QuantumState 实例。

run_circuit_on_state(state, circuit, noise_model, topology)

在一个量子态上执行一个量子线路，返回一个表示演化后状态的新量子态实例。

参数 类型 描述 默认值 state QuantumState 初始量子态。 circuit QuantumCircuit 要执行的量子线路。 noise_model Optional[NoiseModel] 可选的噪声模型。 None topology Optional[Dict] 可选的硬件拓扑图。 None

返回: 演化后的新 QuantumState 实例。

get_state_data(state, format)

安全地从一个 QuantumState 对象中提取底层的状态数据（态矢量或密度矩阵）。此函数会根据需要触发展开计算。

参数 类型 描述 默认值 state QuantumState 要提取数据的量子态。 format str 返回数据的格式。目前仅支持 'python_list'。 'python_list'

返回: List[complex] (态矢量) 或 List[List[complex]] (密度矩阵)。

get_measurement_probabilities(state)

获取一个量子态所有计算基的测量概率。

参数 类型 描述 state QuantumState 要分析的量子态。

返回: List[float]，一个包含所有测量概率的列表。

calculate_hamiltonian_expectation_value(state, hamiltonian)

计算给定哈密顿量在当前量子态下的期望值。

参数 类型 描述 state QuantumState 要分析的量子态。 hamiltonian List[PauliString] 表示哈密顿量的 PauliString 列表。

返回: float，哈密顿量的期望值。

get_effective_unitary(circuit, backend_choice)

计算给定 QuantumCircuit 对应的全局有效酉矩阵。

参数 类型 描述 默认值 circuit QuantumCircuit 要计算酉矩阵的线路。 backend_choice str 用于计算的后端 ('auto', 'pure_python', 'cupy')。 'auto'

返回: 酉矩阵 (Python list 或 cupy.ndarray)。

🔬 高级用法 使用噪声模型

本库支持通过 NoiseModel 子类来模拟带噪量子计算。

code Python download content_copy expand_less

1. 定义一个模拟真实硬件噪声的校准数据
   fake_calib = { 'qubits': { 0: {'T1': 50e-6, 'T2': 70e-6, 'readout_error': 0.01}, }, 'gates': { 'h': {'duration': 50e-9, 'error_rate': 0.001}, # 50ns H-gate, 0.1% 去极化错误 } }

2. 实例化预置的硬件噪声模型
   noise_model = nq.PrebuiltNoiseModels.HardwareBackend(fake_calib)

3. 创建初始态和线路
   state = nq.create_quantum_state(1) circuit = nq.QuantumCircuit(1) circuit.h(0)

4. 在运行线路时传入噪声模型
   noisy_state = nq.run_circuit_on_state(state, circuit, noise_model=noise_model)

5. 验证状态已变为混合态
   assert noisy_state._simulation_mode == 'density_matrix' purity = nq.calculate_state_purity(noisy_state) # 假设有这样一个API print(f"带噪状态的纯度: {purity:.4f}") # 纯度应小于1 算法构建器

使用 AlgorithmBuilders 可以快速生成复杂算法的线路。

code Python download content_copy expand_less

构建一个3比特的量子傅里叶变换(QFT)线路
qft_circuit = nq.AlgorithmBuilders.build_qft_circuit(num_qubits=3)

print("--- 3-qubit QFT Circuit ---") print(qft_circuit)

构建一个用于VQA的硬件高效拟设
params = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] ansatz = nq.AlgorithmBuilders.build_hardware_efficient_ansatz( num_qubits=2, depth=2, parameters=params, entanglement_type='circular' ) print("\n--- Hardware-Efficient Ansatz ---") print(ansatz) 配置核心库

您可以在运行时通过 configure_quantum_core 函数调整库的行为。

code Python download content_copy expand_less

强制使用纯Python后端，并设置最大量子比特数上限
nq.configure_quantum_core({ "BACKEND_CHOICE": "pure_python", "MAX_QUBITS": 10, "MAX_SYSTEM_RAM_GB_LIMIT": 16 # 手动设置内存上限为16GB }) 🧪 测试

本文件包含一个全面的自测试套件。要运行测试，只需直接执行此脚本：

code Bash download content_copy expand_less python quantum_core.py

测试套件将自动在可用的后端（Pure Python 和/或 CuPy）上运行，并验证所有核心功能、算法构建器和噪声模型的正确性。测试采用“快速失败”策略，任何一个测试失败都会立即中止整个测试流程。

📜 版本历史 v1.5.0 - 拓扑感知API版

API 升级: 公共 API run_circuit_on_state 和相关内部方法现在接收 topology 参数，以实现对量子子程序的拓扑感知优化。

架构重构: 彻底移除了 get_effective_unitary 中的猴子补丁，采用内置的模式感知执行，提高了代码的健壮性和可维护性。

噪声模型扩展: 引入了 CorrelatedNoise 模型，用于模拟串扰等非局部效应。

逻辑修复: 修正了相干噪声的应用逻辑，确保其只作用于旋转门的旋转角度。

内核调度优化: _StateVectorEntity 内部改用调度字典来管理优化内核，提高了代码的可读性和可扩展性。

👤 作者

跳舞的火公子

📄 许可证

本项目采用 MIT 许可证。详情请见 LICENSE 文件。