Python API 参考¶
PySparQ 通过 pysparq 模块将所有量子操作暴露为 Python 类和函数。
核心类¶
概念介绍见 System 类 与 SparseState 类。
- class pysparq._core.System¶
基类:
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.
示例
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¶
基类:
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.
示例
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 文档(所有类、函数和方法),请参见 模块索引。