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(),
)
Define a two-dimensional site layout and its loading state. Prefer geometry constructors. Direct construction takes a tuple of RegisterSiteIR objects in sites, with optional snapshot identity, lifecycle stage, previous-snapshot hash and metadata. Coordinates, spacing and origin are in um.
Geometry constructors return a new AtomRegister. Regular layouts assign site and atom IDs q0, q1, and so on. Geometry may retain vacant, defective or loading-failed sites; only filled target sites enter the logical state order. with_site_status() returns a new snapshot without modifying the original register.
See Experiment control and register lifecycle. Constructing a register does not perform a physical experiment. Program validation must still check target limits such as minimum spacing and maximum site count.
line ¶
line(
*,
count: int,
spacing: float,
origin: tuple[float, float] = (0.0, 0.0),
) -> AtomRegister
Create count sites along x, starting at origin with separation spacing. Supply a positive integer count and finite positive spacing. Wrong spacing types raise TypeError; invalid spacing values raise ValueError.
square ¶
square(
*,
side: int,
spacing: float,
origin: tuple[float, float] = (0.0, 0.0),
) -> AtomRegister
Create a square with side sites along each edge and side ** 2 sites in total. Sites are ordered by row: x increases within a row and y increases between rows. spacing applies to both directions.
rectangular ¶
rectangular(
*,
rows: int,
columns: int,
spacing_x: float,
spacing_y: float | None = None,
origin: tuple[float, float] = (0.0, 0.0),
) -> AtomRegister
Create rows * columns sites in row order. Use spacing_x horizontally and spacing_y vertically; omitting the latter uses the horizontal spacing. Row and column counts should be positive integers; spacing must be finite and positive.
triangular ¶
triangular(
*,
rows: int,
spacing: float,
origin: tuple[float, float] = (0.0, 0.0),
) -> AtomRegister
Create rows containing one, two, then successively more sites, for rows * (rows + 1) / 2 sites in total. Horizontal spacing is spacing; vertical spacing is sqrt(3) * spacing / 2. In the current implementation every row starts at x = origin[0]. If your experiment needs a staggered equilateral triangular lattice, specify its coordinates explicitly with 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
Supply a nonempty sequence of positions. Optional site_ids and atom_ids should have matching lengths. Default site names are q0, q1, and so on, with atom names following site names. target_site_ids=None marks all sites as targets; an explicit empty set marks none. Empty positions, mismatched identity lengths or unknown target IDs raise 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
Change one site_id to status, returning the next snapshot and retaining the previous snapshot's hash. Supply lifecycle_stage and snapshot_id explicitly. Status values include filled, vacant, defect and loading_failed; vacant and loading-failed sites cannot receive an atom_id. Unknown sites or invalid lifecycle transitions fail. This records a declared state transition without controlling loading hardware.
Return AtomRegisterIR retaining sites, snapshot identity, lifecycle and previous-snapshot reference. This passes the layout to programs and validators without reordering sites or running simulation.