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

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)

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 to str(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 StatePrintDisplay for 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 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)

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):

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