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_objectQuantum 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.
add_register_synchronous(arg0: str, arg1: pysparq._core.StateStorageType, arg2: typing.SupportsInt | typing.SupportsIndex, arg3: pysparq._core.SparseState) -> int
add_register_synchronous(arg0: str, arg1: pysparq._core.StateStorageType, arg2: typing.SupportsInt | typing.SupportsIndex, arg3: collections.abc.Sequence[pysparq._core.System]) -> int
- get(*args, **kwargs)¶
Overloaded function.
get(self: pysparq._core.System, arg0: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.StateStorage
get(self: pysparq._core.System, arg0: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.StateStorage
- last_register(*args, **kwargs)¶
Overloaded function.
last_register(self: pysparq._core.System) -> pysparq._core.StateStorage
last_register(self: pysparq._core.System) -> pysparq._core.StateStorage
- static name_of(arg0: SupportsInt | SupportsIndex) str¶
- static remove_register(*args, **kwargs)¶
Overloaded function.
remove_register(arg0: typing.SupportsInt | typing.SupportsIndex) -> None
remove_register(arg0: str) -> None
- static remove_register_synchronous(*args, **kwargs)¶
Overloaded function.
remove_register_synchronous(arg0: typing.SupportsInt | typing.SupportsIndex, arg1: collections.abc.Sequence[pysparq._core.System]) -> None
remove_register_synchronous(arg0: str, arg1: collections.abc.Sequence[pysparq._core.System]) -> None
remove_register_synchronous(arg0: typing.SupportsInt | typing.SupportsIndex, arg1: pysparq._core.SparseState) -> None
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.
size_of(arg0: str) -> int
size_of(arg0: typing.SupportsInt | typing.SupportsIndex) -> int
- static status_of(*args, **kwargs)¶
Overloaded function.
status_of(arg0: str) -> bool
status_of(arg0: typing.SupportsInt | typing.SupportsIndex) -> bool
- to_string(*args, **kwargs)¶
Overloaded function.
to_string(self: pysparq._core.System) -> str
to_string(self: pysparq._core.System, arg0: typing.SupportsInt | typing.SupportsIndex) -> str
- static type_of(*args, **kwargs)¶
Overloaded function.
type_of(arg0: str) -> pysparq._core.StateStorageType
type_of(arg0: typing.SupportsInt | typing.SupportsIndex) -> pysparq._core.StateStorageType
- static update_max_size(arg0: SupportsInt | SupportsIndex) None¶
- class pysparq._core.SparseState¶
Bases:
pybind11_objectSparse 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.