Python API 参考

PySparQ 通过 pysparq 模块将所有量子操作暴露为 Python 类和函数。

核心类

概念介绍见 System 类 与 SparseState 类。

class pysparq._core.System

基类: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.

示例

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

基类: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.

示例

state = SparseState() AddRegister("q", UnsignedInteger, 4)(state) Hadamard_Int("q")(state)

备注

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.

参数:
  • display -- Display mode flags (StatePrintDisplay values).

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

量子算术算子

详细用法见 算术算子。

pysparq._core.Add_UInt_UInt()

Add two unsigned integer registers.

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

参数:
  • 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).

示例

Add_UInt_UInt("a", "b", "result")(state) # result = a + b

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

量子门

详细用法见 基本量子门、Hadamard 操作 与 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.

参数:
  • reg_in -- Name/ID of the input register.

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

示例

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.

参数:

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

示例

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.

参数:

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

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

QRAM 操作

详细用法见 QRAM 算子。

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.

参数:
  • qram -- QRAMCircuit_qutrit instance containing the memory.

  • addr_reg -- Name/ID of the address register.

  • data_reg -- Name/ID of the data register.

示例

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

备注

Use QRAMLoadFast for optimized execution when address distribution is uniform.

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

状态管理

详细用法见 系统操作、部分追迹 与 黑魔法操作 (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.

示例

Normalize()(state)

pysparq._core.CheckNormalization()

完整 API 文档

完整的 API 文档(所有类、函数和方法),请参见 模块索引。