System 类

System 类是稀疏态模拟器的基本单元,代表一个计算基态。每个 System 存储一个复数振幅 amplitude 和所有寄存器的值 registers。

核心概念

在 PySparQ 中,量子态用稀疏表示:只存储振幅非零的基态。每个基态用一个 System 对象表示:

\[|\psi\rangle = \sum_{i \in \text{non-zero}} \alpha_i |i\rangle\]

其中每个 \(|i\rangle\) 对应一个 System 实例。

一个 System 包含两部分核心数据:

  • **amplitude**(complex):该基态的复数振幅

  • **registers**(list[StateStorage]):各寄存器的值,按寄存器 ID 索引。每个寄存器值以 uint64_t 存储——存储单元在 寄存器类型 中描述

重要

System 不是独立使用的对象。它始终由 SparseState 托管。SparseState 保证其中所有 System 的寄存器值组合唯一——如果两个 System 具有相同的寄存器值,意味着发生了量子干涉,它们的振幅应当相加合并为一个 System。

静态变量:全局寄存器追踪

System 类使用静态(类级)变量追踪所有寄存器的元信息。这意味着:

  • 所有 System 实例共享同一套寄存器元数据

  • 寄存器 ID 在全局范围内分配

  • 程序结束时静态状态不会自动清除

警告

重要:每次运行新程序前,必须调用 System.clear() 清理静态状态,否则会残留上次运行的信息!

静态成员

System 静态变量

变量名

类型

说明

name_register_map

list

寄存器元数据列表,每个元素为 (name, type, size, status) 元组

max_register_count

int

历史最大寄存器数量(统计用)

max_system_size

int

历史最大基态数量(统计用)

reusable_registers

list

可重用的寄存器 ID 列表

temporal_registers

list

临时寄存器栈

实例成员

System 实例成员

成员

类型

说明

amplitude

complex

该基态的复数振幅

registers

list[StateStorage]

各寄存器的值(按寄存器 ID 索引),底层以 uint64_t 存储

寄存器的存储原理

系统中的寄存器托管了 n 个 uint64_t 的存储方式。这使得我们可以将量子态编码为类似 \(|a\rangle|b\rangle|c\rangle\) 的多寄存器形式,而无需管理量子比特是如何编码的。

例如,QRAM 访问 \(|i\rangle|0\rangle \to |i\rangle|d[i]\rangle\) 可以被轻松编码——只需要一个地址寄存器和一个数据寄存器(参见 QRAM 算子)。整个项目的管理层面从量子比特上升到了量子寄存器,几乎所有操作都以量子寄存器为单位。

查询方法

获取寄存器信息

# 获取寄存器 ID
reg_id = ps.System.get_id("counter")

# 获取寄存器大小(比特数)
size = ps.System.size_of("counter")  # 或 ps.System.size_of(reg_id)

# 获取寄存器类型
type_ = ps.System.type_of("counter")  # 返回 StateStorageType 枚举

# 获取寄存器激活状态
active = ps.System.status_of("counter")  # True 表示已激活

# 获取完整元信息
info = ps.System.get_register_info("counter")
# 返回 (name, type, size, status) 元组

# 根据 ID 获取名称
name = ps.System.name_of(reg_id)

返回的 StateStorageType 枚举及各存储类型取值的含义在 寄存器类型 中描述。

统计信息

# 获取量子比特总数
n_qubits = ps.System.get_qubit_count()

# 获取已激活寄存器数量
n_regs = ps.System.get_activated_register_size()

访问基态中的寄存器值

ps.System.clear()
ps.System.add_register("x", ps.UnsignedInteger, 4)
state = ps.SparseState()

# 遍历所有基态
for system in state.basis_states:
    # 访问振幅
    amp = system.amplitude

    # 访问寄存器值(通过 ID)
    x_id = ps.System.get_id("x")
    value = system.get(x_id).value

    # 字符串表示
    print(system)

# 访问最后一个激活的寄存器
last_val = system.last_register()

比较与排序

System 类支持比较运算符,用于排序和去重:

# 相等比较(所有寄存器值和振幅都相同)
if s1 == s2:
    print("相同基态")

# 小于比较(用于排序)
if s1 < s2:
    print("s1 排在 s2 前面")

# 字符串表示
print(str(system))  # 如: "|x=3, y=5⟩ : (0.5+0j)"

最佳实践

  1. 始终在程序开始时调用 ``System.clear()``

    import pysparq as ps
    
    ps.System.clear()  # 第一步!
    
    # 然后创建寄存器...
    ps.System.add_register("a", ps.UnsignedInteger, 4)
    
    # SparseState() 默认创建 |0...0⟩ 初态
    state = ps.SparseState()
    
  2. 不要手动构造 System 列表来创建 SparseState

    SparseState 的默认构造函数已经创建了一个所有寄存器值为 0 的初态。通常不需要手动构造 System 对象。

  3. 使用有意义的寄存器名称

    名称用于调试和 StatePrint 输出,应具有描述性。

API 参考

class pysparq.System

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

property amplitude
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

max_register_count = 0
max_register_map = 0
max_system_size = 0
static name_of(arg0: SupportsInt | SupportsIndex) → str
name_register_map = []
property registers
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

reusable_registers = []
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

temporal_registers = []
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