调试工具

调试工具提供量子态检查、归一化验证、NaN 检测和状态打印等功能。这些工具不改变量子态,用于开发和调试阶段。这里记录的 TestRemovable 检查也保护 RemoveRegister 不会移除纠缠寄存器。

概述

调试工具总览

算子

操作

是否修改态

StatePrint

打印量子态

否

CheckNormalization

检查归一化

否

CheckNan

检测 NaN

否

ViewNormalization

显示归一化值

否

TestRemovable

测试寄存器可移除性

否

CheckDuplicateKey

检测重复键

否

---

状态打印

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 to str(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 StatePrintDisplay for 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 — 浮点精度(可选)

显示模式:

StatePrint 显示模式

模式

说明

Default

标准格式 |reg=val⟩ : (α+βi)

Detail

详细信息,包含寄存器元数据

Binary

以二进制显示寄存器值

Prob

显示概率而非振幅

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 类 中的显示模式表即基于它):

class pysparq.StatePrintDisplay

Members:

Default

Detail

Binary

Prob

Binary = <StatePrintDisplay.Binary: 2>
Default = <StatePrintDisplay.Default: 0>
Detail = <StatePrintDisplay.Detail: 1>
Prob = <StatePrintDisplay.Prob: 4>
StatePrintDisplay.name -> str
property value