Debugging Tools¶

Debugging tools provide quantum-state inspection, normalization checking, NaN detection, state printing, and similar utilities. These tools do not modify the quantum state; they are intended for the development and debugging stages.

Overview ¶

Debugging tools overview¶
Operator	Operation	Modifies the state?
`StatePrint`	Print the quantum state	No
`CheckNormalization`	Check normalization	No
`CheckNan`	Detect NaN	No
`ViewNormalization`	Display the normalization value	No
`TestRemovable`	Test register removability	No
`CheckDuplicateKey`	Detect duplicate keys	No

—

State Printing ¶

StatePrint (state printing)¶

Operation: Returns an information string for all basis states in the SparseState in the specified format.

Parameters:

state — a SparseState instance
mode — display mode (optional, Detail by default)
precision — floating-point precision (optional)

Display modes:

StatePrint display modes¶
Mode	Description
`Default`	Standard format `\|reg=val⟩ : (α+βi)`
`Detail`	Detailed information, including register metadata
`Binary`	Display register values in binary
`Prob`	Display probabilities instead of amplitudes

import pysparq as ps

# Print to stdout (Detail mode)
ps.pprint(state)
# Output:
# 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>
# ...

# Return a string (Detail mode)
ps.StatePrint(state)
# Returns the same Detail-format string

# Probability format (returns a string)
ps.StatePrint(state, mode=ps.StatePrintDisplay.Prob)
# Output:
# StatePrint (mode=Prob)
# 0.250000+0.000000i (p = 0.0625) |0>|0>
# ...

# High precision
ps.StatePrint(state, mode=ps.StatePrintDisplay.Default, precision=15)

# Binary format
ps.StatePrint(state, mode=ps.StatePrintDisplay.Binary)
# Register values displayed in binary

—

Normalization Checking ¶

CheckNormalization (normalization check)¶

Operation: Asserts that the normalization value \(\sum_i |\alpha_i|^2\) of the SparseState is close to 1. Raises an exception if the deviation exceeds the threshold.

Parameters: threshold — allowed deviation threshold (optional, 1e-6 by default).

# Strict check
ps.CheckNormalization(1e-10)(state)

# Lenient check
ps.CheckNormalization(1e-3)(state)

ViewNormalization (display the normalization value)¶

Operation: Computes and prints the normalization value \(\sum_i |\alpha_i|^2\) of the SparseState without raising an exception.

Parameters: None.

ps.ViewNormalization()(state)
# Output: Norm = 0.9999999...

—

Data Integrity Checks ¶

CheckNan (NaN detection)¶

Operation: Iterates over all basis states and checks whether any amplitude contains NaN values. Raises an exception if NaN is found.

Parameters: None.

Purpose: After extensive arithmetic, some amplitudes may become NaN due to numerical overflow or division by zero. This operator detects such problems early.

ps.CheckNan()(state)

TestRemovable (register removability test)¶

Operation: Tests whether the specified register can be safely removed from the SparseState (i.e. whether the register is entangled with the other registers).

Parameters: reg — target register (name or ID).

Returns: The result is reported through an internal assertion.

# Test whether "ancilla" can be safely removed
ps.TestRemovable("ancilla")(state)

CheckDuplicateKey (duplicate key detection)¶

Operation: Checks whether the SparseState contains basis states with duplicate keys. Normally no duplicates should exist.

Parameters: None.

Purpose: If you suspect that a non-unitary operation introduced duplicate keys, use this operator to detect them.

ps.CheckDuplicateKey()(state)

中文版 ===

调试工具¶

调试工具提供量子态检查、归一化验证、NaN 检测和状态打印等功能。这些工具不改变量子态，用于开发和调试阶段。

概述 ¶

调试工具总览¶
算子	操作	是否修改态
`StatePrint`	打印量子态	否
`CheckNormalization`	检查归一化	否
`CheckNan`	检测 NaN	否
`ViewNormalization`	显示归一化值	否
`TestRemovable`	测试寄存器可移除性	否
`CheckDuplicateKey`	检测重复键	否

—

状态打印 ¶

StatePrint（状态打印）¶

操作: 以指定格式返回 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（归一化检查）¶

操作: 断言 SparseState 的归一化值 \(\sum_i |\alpha_i|^2\) 接近 1。如果偏离超过阈值，抛出异常。

参数: threshold — 允许的偏差阈值（可选，默认 1e-6）。

# 严格检查
ps.CheckNormalization(1e-10)(state)

# 宽松检查
ps.CheckNormalization(1e-3)(state)

ViewNormalization（显示归一化值）¶

操作: 计算并打印 SparseState 的归一化值 \(\sum_i |\alpha_i|^2\)，不抛出异常。

参数: 无。

ps.ViewNormalization()(state)
# 输出: Norm = 0.9999999...

—

数据完整性检查 ¶

CheckNan（NaN 检测）¶

操作: 遍历所有基态，检查振幅是否包含 NaN 值。如果发现 NaN，抛出异常。

参数: 无。

用途: 经过大量算术运算后，某些振幅可能因数值溢出或除零变为 NaN。此算子用于早期发现这类问题。

ps.CheckNan()(state)

TestRemovable（寄存器可移除性测试）¶

操作: 测试指定寄存器是否可以从 SparseState 中安全移除（即该寄存器是否与其他寄存器纠缠）。

参数: reg — 目标寄存器（名称或 ID）。

返回: 通过内部断言报告结果。

# 测试 "ancilla" 是否可以安全移除
ps.TestRemovable("ancilla")(state)

CheckDuplicateKey（重复键检测）¶

操作: 检查 SparseState 中是否存在键值重复的基态。正常情况下不应存在重复。

参数: 无。

用途: 如果怀疑某个非幺正操作引入了重复键，可用此算子检测。

ps.CheckDuplicateKey()(state)