AtomRegister¶
from cascaqit import AtomRegister
AtomRegister ¶
AtomRegister(
sites: tuple[RegisterSiteIR, ...],
snapshot_id: str = "register.planned",
lifecycle_stage: RegisterLifecycleStage = "planned",
previous_snapshot_hash: str | None = None,
metadata: dict[str, Any] = dict(),
)
定义二维站点布局及其装载状态。通常用几何构造方法；直接构造时，sites 是 RegisterSiteIR 元组，另外可提供快照标识、生命周期阶段、前一快照哈希和元数据。所有位置、间距和原点都以 um 为单位。
几何构造方法返回新 AtomRegister。规则阵列依次使用 q0、q1 等站点和原子标识。几何中可以保留空位、缺陷或装载失败站点；只有有原子的目标站点进入逻辑态顺序。with_site_status() 返回新快照，不修改原阵列。
见实验控制与原子阵列生命周期。阵列构造不执行物理实验；目标支持的最小间距和最大站点数需在程序校验时检查。
line ¶
line(
*,
count: int,
spacing: float,
origin: tuple[float, float] = (0.0, 0.0),
) -> AtomRegister
创建 count 个沿 x 轴排列的站点，从 origin 开始，相邻间距为 spacing。count 应为正整数；间距必须是有限正数，错误类型或无效间距分别触发 TypeError 或 ValueError。
square ¶
square(
*,
side: int,
spacing: float,
origin: tuple[float, float] = (0.0, 0.0),
) -> AtomRegister
创建边长为 side 个站点的正方形，共 side ** 2 个站点。按行排列，行内 x 增加，行间 y 增加；spacing 为两个方向的间距。
rectangular ¶
rectangular(
*,
rows: int,
columns: int,
spacing_x: float,
spacing_y: float | None = None,
origin: tuple[float, float] = (0.0, 0.0),
) -> AtomRegister
创建 rows * columns 个站点，按行编号。x 间距为 spacing_x，y 间距为 spacing_y，后者省略时使用 x 间距。行列数应为正整数，间距须为有限正数。
triangular ¶
triangular(
*,
rows: int,
spacing: float,
origin: tuple[float, float] = (0.0, 0.0),
) -> AtomRegister
创建逐行增加站点的布局，第 1 行一个，第 2 行两个，共 rows * (rows + 1) / 2 个。行内间距为 spacing，行间距为 sqrt(3) * spacing / 2。当前实现各行的首点 x 坐标均为 origin[0]；若研究需要错行的等边三角晶格，应用 custom() 明确给出坐标。
custom ¶
custom(
positions: tuple[tuple[float, float], ...],
*,
site_ids: tuple[str, ...] | None = None,
atom_ids: tuple[str, ...] | None = None,
target_site_ids: frozenset[str] | None = None,
) -> AtomRegister
用非空 positions 显式指定坐标。可选的 site_ids 与 atom_ids 应与坐标等长；默认站点名称为 q0、q1 等，原子名称随站点名称。target_site_ids=None 将全部站点设为目标，显式空集合则没有目标。空坐标、身份长度不一致或未知目标 ID 会抛出 ValueError。
with_site_status ¶
with_site_status(
site_id: str,
*,
status: RegisterSiteStatus,
lifecycle_stage: RegisterLifecycleStage,
snapshot_id: str,
atom_id: str | None = None,
metadata: dict[str, Any] | None = None,
) -> AtomRegister
更新一个 site_id 的 status，返回下一快照，并记录前一快照的哈希。必须显式提供 lifecycle_stage 与 snapshot_id。状态包括 filled、vacant、defect、loading_failed；空位和装载失败站点不能传 atom_id。未知站点或不合法的生命周期转换会失败。此方法记录声明的状态变化，不控制实际装载设备。
返回 AtomRegisterIR，保留站点、快照、生命周期和前一快照引用。它将布局交给程序与校验器；不会重新排列站点或执行模拟。