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. The TestRemovable check documented here also guards RemoveRegister against removing entangled registers.
Overview¶
Operator |
Operation |
Modifies the state? |
|---|---|---|
|
Print the quantum state |
No |
|
Check normalization |
No |
|
Detect NaN |
No |
|
Display the normalization value |
No |
|
Test register removability |
No |
|
Detect duplicate keys |
No |
—
State Printing¶
StatePrint (state printing)¶
- pysparq.StatePrint(state: SparseState, mode: int | StatePrintDisplay = 1, precision: int = 0) str[source]¶
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.- Parameters:
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).
- Returns:
A formatted string describing the quantum state.
Example
>>> 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[source]¶
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.
- Parameters:
state – The SparseState to print.
mode – Display mode. Defaults to Detail (1).
precision – Decimal places for floating-point numbers.
Example
>>> 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[source]¶
Return a formatted string representation of a SparseState.
Alias for
StatePrint(state, mode, precision)with Detail mode default.- Parameters:
state – The SparseState to format.
mode – Display mode. Defaults to Detail (1).
precision – Decimal places for floating-point numbers.
- Returns:
A formatted string describing the quantum state.
- class pysparq.StatePrinter(mode: int | StatePrintDisplay = 1, precision: int = 0)[source]¶
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.
- Parameters:
mode – Default display mode. Defaults to Detail (1).
precision – Default decimal precision. Defaults to 0.
Example
>>> 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[source]¶
Format a state using this printer’s mode (or override it).
- Parameters:
state – The SparseState to format.
mode – Optional mode override for this call.
- Returns:
Formatted string representation.
Operation: Returns an information string for all basis states in the SparseState in the specified format.
Parameters:
state— a SparseState instancemode— display mode (optional,Detailby default)precision— floating-point precision (optional)
Display modes:
Mode |
Description |
|---|---|
|
Standard format |
|
Detailed information, including register metadata |
|
Display register values in binary |
|
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)¶
- class pysparq.CheckNormalization¶
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)¶
- class pysparq.ViewNormalization¶
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)¶
- class pysparq.CheckNan¶
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)¶
- class pysparq.TestRemovable¶
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)¶
- class pysparq.CheckDuplicateKey¶
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)
StatePrintDisplay Enum¶
The output modes accepted by StatePrint / pprint (used throughout The SparseState Class):