调试工具¶
调试工具提供量子态检查、归一化验证、NaN 检测和状态打印等功能。这些工具不改变量子态,用于开发和调试阶段。这里记录的 TestRemovable 检查也保护 RemoveRegister 不会移除纠缠寄存器。
概述¶
算子 |
操作 |
是否修改态 |
|---|---|---|
|
打印量子态 |
否 |
|
检查归一化 |
否 |
|
检测 NaN |
否 |
|
显示归一化值 |
否 |
|
测试寄存器可移除性 |
否 |
|
检测重复键 |
否 |
---
状态打印¶
StatePrint(状态打印)¶
- pysparq.StatePrint(state: SparseState, mode: int | StatePrintDisplay = 1, precision: int = 0) str[源代码]¶
Return a formatted string representation of a SparseState.
This is the primary way to convert a SparseState to a string.
ps.StatePrint(state)is equivalent tostr(state)but allows explicit control over display mode and precision.- 参数:
state -- The SparseState to format.
mode -- Display mode (int or StatePrintDisplay enum). Defaults to Detail (1) — shows register names and types. See
StatePrintDisplayfor available modes.precision -- Number of decimal places for floating-point numbers. Defaults to 0 (uses the state's default).
- 返回:
A formatted string describing the quantum state.
示例
>>> ps.System.clear() >>> ps.AddRegister("q", ps.UnsignedInteger, 2)(ps.SparseState()) >>> ps.Init_Unsafe("q", 1)(ps.SparseState()) >>> state = ps.SparseState() >>> ps.Hadamard_Int("q", 2)(state) >>> ps.StatePrint(state) # Detail mode (default) >>> ps.StatePrint(state, mode=ps.StatePrintDisplay.Default) >>> ps.StatePrint(state, mode=ps.StatePrintDisplay.Binary) >>> ps.StatePrint(state, mode=ps.StatePrintDisplay.Prob)
- pysparq.pprint(state: SparseState, mode: int | StatePrintDisplay = 1, precision: int = 0) None[源代码]¶
Print a SparseState to stdout in the specified display mode.
This function prints directly to standard output, which is captured correctly by Jupyter and IPython notebooks.
- 参数:
state -- The SparseState to print.
mode -- Display mode. Defaults to Detail (1).
precision -- Decimal places for floating-point numbers.
示例
>>> ps.System.clear() >>> ps.AddRegister("q", ps.UnsignedInteger, 2)(ps.SparseState()) >>> state = ps.SparseState() >>> ps.Hadamard_Int("q", 2)(state) >>> ps.pprint(state) # prints to stdout in Detail mode >>> ps.pprint(state, mode=ps.StatePrintDisplay.Prob) # Prob mode
- pysparq.to_string(state: SparseState, mode: int | StatePrintDisplay = 1, precision: int = 0) str[源代码]¶
Return a formatted string representation of a SparseState.
Alias for
StatePrint(state, mode, precision)with Detail mode default.- 参数:
state -- The SparseState to format.
mode -- Display mode. Defaults to Detail (1).
precision -- Decimal places for floating-point numbers.
- 返回:
A formatted string describing the quantum state.
- class pysparq.StatePrinter(mode: int | StatePrintDisplay = 1, precision: int = 0)[源代码]¶
Reusable state formatter with configurable default mode.
Provides a stateful formatter that holds a persistent mode and precision setting. Useful when printing many states in the same format.
- 参数:
mode -- Default display mode. Defaults to Detail (1).
precision -- Default decimal precision. Defaults to 0.
示例
>>> printer = StatePrinter(ps.StatePrintDisplay.Prob) >>> printer(state1) # uses Prob mode >>> printer(state2) # uses Prob mode >>> printer(state3, mode=ps.StatePrintDisplay.Binary) # override
- __call__(state: SparseState, mode: int | StatePrintDisplay | None = None) str[源代码]¶
Format a state using this printer's mode (or override it).
- 参数:
state -- The SparseState to format.
mode -- Optional mode override for this call.
- 返回:
Formatted string representation.
操作: 以指定格式返回 SparseState 中所有基态的信息字符串。
参数:
state— SparseState 实例mode— 显示模式(可选,默认Detail)precision— 浮点精度(可选)
显示模式:
模式 |
说明 |
|---|---|
|
标准格式 |
|
详细信息,包含寄存器元数据 |
|
以二进制显示寄存器值 |
|
显示概率而非振幅 |
import pysparq as ps
# 打印到 stdout(Detail 模式)
ps.pprint(state)
# 输出:
# StatePrint (mode=Detail)
# |(0)addr : UInt4 | |(1)data : UInt8 |
# 0.250000+0.000000i addr=|0> data=|0>
# 0.250000+0.000000i addr=|1> data=|2>
# ...
# 返回字符串(Detail 模式)
ps.StatePrint(state)
# 返回相同的 Detail 格式字符串
# 概率格式(返回字符串)
ps.StatePrint(state, mode=ps.StatePrintDisplay.Prob)
# 输出:
# StatePrint (mode=Prob)
# 0.250000+0.000000i (p = 0.0625) |0>|0>
# ...
# 高精度
ps.StatePrint(state, mode=ps.StatePrintDisplay.Default, precision=15)
# 二进制格式
ps.StatePrint(state, mode=ps.StatePrintDisplay.Binary)
# 寄存器值以二进制显示
---
归一化检查¶
CheckNormalization(归一化检查)¶
- class pysparq.CheckNormalization¶
操作: 断言 SparseState 的归一化值 \(\sum_i |\alpha_i|^2\) 接近 1。如果偏离超过阈值,抛出异常。
参数: threshold — 允许的偏差阈值(可选,默认 1e-6)。
# 严格检查
ps.CheckNormalization(1e-10)(state)
# 宽松检查
ps.CheckNormalization(1e-3)(state)
ViewNormalization(显示归一化值)¶
- class pysparq.ViewNormalization¶
操作: 计算并打印 SparseState 的归一化值 \(\sum_i |\alpha_i|^2\),不抛出异常。
参数: 无。
ps.ViewNormalization()(state)
# 输出: Norm = 0.9999999...
---
数据完整性检查¶
CheckNan(NaN 检测)¶
- class pysparq.CheckNan¶
操作: 遍历所有基态,检查振幅是否包含 NaN 值。如果发现 NaN,抛出异常。
参数: 无。
用途: 经过大量算术运算后,某些振幅可能因数值溢出或除零变为 NaN。此算子用于早期发现这类问题。
ps.CheckNan()(state)
TestRemovable(寄存器可移除性测试)¶
- class pysparq.TestRemovable¶
操作: 测试指定寄存器是否可以从 SparseState 中安全移除(即该寄存器是否与其他寄存器纠缠)。
参数: reg — 目标寄存器(名称或 ID)。
返回: 通过内部断言报告结果。
# 测试 "ancilla" 是否可以安全移除
ps.TestRemovable("ancilla")(state)
CheckDuplicateKey(重复键检测)¶
- class pysparq.CheckDuplicateKey¶
操作: 检查 SparseState 中是否存在键值重复的基态。正常情况下不应存在重复。
参数: 无。
用途: 如果怀疑某个非幺正操作引入了重复键,可用此算子检测。
ps.CheckDuplicateKey()(state)
StatePrintDisplay 枚举¶
StatePrint / pprint 接受的输出模式枚举(SparseState 类 中的显示模式表即基于它):