Python API Reference

PySparQ exposes all quantum operations as Python classes and functions through the pysparq module.

Core Classes

Concept introductions: The System Class and The SparseState Class.

class pysparq._core.System

Bases: pybind11_object

Quantum system managing named registers.

The System class provides the foundation for register management. It tracks register names, types, and sizes via a global registry shared by all SparseState instances.

Example

system = System() state = SparseState()

registers

Dict mapping register names to their metadata.

amplitude

Amplitude coefficient for this system instance.

static add_register(arg0: str, arg1: pysparq._core.StateStorageType, arg2: SupportsInt | SupportsIndex) → int
static add_register_synchronous(*args, **kwargs)

Overloaded function.

  1. add_register_synchronous(arg0: str, arg1: pysparq._core.StateStorageType, arg2: typing.SupportsInt | typing.SupportsIndex, arg3: pysparq._core.SparseState) -> int

  2. add_register_synchronous(arg0: str, arg1: pysparq._core.StateStorageType, arg2: typing.SupportsInt | typing.SupportsIndex, arg3: collections.abc.Sequence[pysparq._core.System]) -> int

static clear() → None
get(*args, **kwargs)

Overloaded function.

  1. get(self: pysparq._core.System, arg0: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.StateStorage

  2. get(self: pysparq._core.System, arg0: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.StateStorage

static get_activated_register_size() → int
static get_id(arg0: str) → int
static get_qubit_count() → int
static get_register_info(arg0: str) → tuple[str, pysparq._core.StateStorageType, int, bool]
last_register(*args, **kwargs)

Overloaded function.

  1. last_register(self: pysparq._core.System) -> pysparq._core.StateStorage

  2. last_register(self: pysparq._core.System) -> pysparq._core.StateStorage

static name_of(arg0: SupportsInt | SupportsIndex) → str
static remove_register(*args, **kwargs)

Overloaded function.

  1. remove_register(arg0: typing.SupportsInt | typing.SupportsIndex) -> None

  2. remove_register(arg0: str) -> None

static remove_register_synchronous(*args, **kwargs)

Overloaded function.

  1. remove_register_synchronous(arg0: typing.SupportsInt | typing.SupportsIndex, arg1: collections.abc.Sequence[pysparq._core.System]) -> None

  2. remove_register_synchronous(arg0: str, arg1: collections.abc.Sequence[pysparq._core.System]) -> None

  3. remove_register_synchronous(arg0: typing.SupportsInt | typing.SupportsIndex, arg1: pysparq._core.SparseState) -> None

  4. remove_register_synchronous(arg0: str, arg1: pysparq._core.SparseState) -> None

static set_register_type(arg0: str, arg1: pysparq._core.StateStorageType) → None
static size_of(*args, **kwargs)

Overloaded function.

  1. size_of(arg0: str) -> int

  2. size_of(arg0: typing.SupportsInt | typing.SupportsIndex) -> int

static status_of(*args, **kwargs)

Overloaded function.

  1. status_of(arg0: str) -> bool

  2. status_of(arg0: typing.SupportsInt | typing.SupportsIndex) -> bool

to_string(*args, **kwargs)

Overloaded function.

  1. to_string(self: pysparq._core.System) -> str

  2. to_string(self: pysparq._core.System, arg0: typing.SupportsInt | typing.SupportsIndex) -> str

static type_of(*args, **kwargs)

Overloaded function.

  1. type_of(arg0: str) -> pysparq._core.StateStorageType

  2. type_of(arg0: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.StateStorageType

static update_max_size(arg0: SupportsInt | SupportsIndex) → None
class pysparq._core.SparseState

Bases: pybind11_object

Sparse quantum state representation.

Stores only non-zero amplitude entries, making it efficient for states with limited superposition. Works with the global System registry.

Example

state = SparseState() AddRegister(“q”, UnsignedInteger, 4)(state) Hadamard_Int(“q”)(state)

Note

The sparse representation is memory-efficient but may be slower for dense superposition states.

clone(self: pysparq._core.SparseState) → pysparq._core.SparseState

Copy amplitude/register values. The System register namespace remains process-global.

empty(self: pysparq._core.SparseState) → bool
size(self: pysparq._core.SparseState) → int
to_string(self: pysparq._core.SparseState, display: SupportsInt | SupportsIndex = 0, precision: SupportsInt | SupportsIndex = 0) → str

Return a formatted string representation of the state.

Parameters:
  • display – Display mode flags (StatePrintDisplay values).

  • precision – Number of decimal places for floating-point numbers.

Quantum Arithmetic Operators

Detailed usage: Arithmetic Operators.

pysparq._core.Add_UInt_UInt()

Add two unsigned integer registers.

Computes: |a⟩|b⟩|0⟩ → |a⟩|b⟩|a+b⟩ (mod 2^n)

Parameters:
  • input_reg1 – Name/ID of the first input register (addend).

  • input_reg2 – Name/ID of the second input register (addend).

  • output_reg – Name/ID of the output register (accumulates sum).

Example

Add_UInt_UInt(“a”, “b”, “result”)(state) # result = a + b

pysparq._core.Add_UInt_ConstUInt()
pysparq._core.Mult_UInt_ConstUInt()

Quantum Gates

Detailed usage: Basic Quantum Gates, Hadamard Operations, and QFT.

pysparq._core.Hadamard_Int()

Apply Hadamard transform to an integer register.

Creates an equal superposition over all integer values from 0 to 2^n - 1 for the specified number of digits.

Parameters:
  • reg_in – Name/ID of the input register.

  • n_digits – Number of digits (qubits) to apply Hadamard to.

Example

Hadamard_Int(“q”, 4)(state) # Superpose q over 0..15

pysparq._core.Hadamard_Bool()
pysparq._core.QFT()

Quantum Fourier Transform on a register.

Applies the QFT to transform between computational and Fourier bases. Commonly used in phase estimation and Shor’s algorithm.

Parameters:

reg_name – Name of the register to transform (str) or register ID (int).

Example

QFT(“data”)(state) # Apply QFT # … computation … InverseQFT(“data”)(state) # Apply inverse QFT

pysparq._core.InverseQFT()

Inverse Quantum Fourier Transform on a register.

Applies the inverse QFT to transform from Fourier basis back to computational basis.

Parameters:

reg_name – Name of the register (str) or register ID (int).

pysparq._core.X_Bool()
pysparq._core.Y_Bool()
pysparq._core.Z_Bool()

QRAM Operations

Detailed usage: QRAM Operators.

pysparq._core.QRAMLoad()

Load classical data into quantum superposition via QRAM.

Performs the QRAM load operation, creating a superposition where each basis state is entangled with its corresponding data value.

Parameters:
  • qram – QRAMCircuit_qutrit instance containing the memory.

  • addr_reg – Name/ID of the address register.

  • data_reg – Name/ID of the data register.

Example

qram = QRAMCircuit_qutrit(addr_size=3, data_size=4, memory=data) QRAMLoad(qram, “address”, “data”)(state)

Note

Use QRAMLoadFast for optimized execution when address distribution is uniform.

pysparq._core.QRAMLoadFast()
pysparq._core.QRAMCircuit_qutrit()

State Management

Detailed usage: System Operations, Partial Trace, and Dark Magic Operations (Normalize).

pysparq._core.AddRegister()
pysparq._core.RemoveRegister()
pysparq._core.Push()
pysparq._core.Pop()
pysparq._core.Normalize()

Normalize the quantum state.

Ensures the state vector has unit norm by dividing all amplitudes by the total norm. Call after operations that may leave the state unnormalized.

Example

Normalize()(state)

pysparq._core.CheckNormalization()

Complete API Documentation

For the full API documentation (all classes, functions, and methods), see Module Index.