bloqade.lanes.arch.build.imperative.ZoneBuilder

← Module overview

classZoneBuilder¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder

Build a single zone with its words, grid, and buses.

Signature

class ZoneBuilder(name: str, grid: _RustGrid, word_shape: tuple[int, int], *, x_clearance: float, y_clearance: float)

Public import paths

• from bloqade.lanes.arch import ZoneBuilder
• from bloqade.lanes.arch.build import ZoneBuilder
• from bloqade.lanes.arch.build.blueprint import ZoneBuilder

All indices are zone-local. Words are placed on the zone’s grid and validated for shape and overlap. Buses are validated for AOD Cartesian product compliance.

Parameters

Name	Type	Description
name	str	Human-readable zone name (stored in Rust Zone).
grid	_RustGrid	Coordinate grid for this zone. Every x- and y-position must be representable at 1 nm precision (i.e., at most 3 decimal places when given in µm).
word_shape	tuple[int, int]	(num_x_sites, num_y_sites) — uniform shape for all words in this zone. sites_per_word = product of shape.
x_clearance	float	Minimum physical distance (> 0, µm) from grid lines that path waypoints must maintain on the x-axis. Must be representable at 1 nm precision.
y_clearance	float	Same as ``x_clearance``, applied to the y-axis. Allowing separate values is useful when row and column spacings differ substantially (e.g., tight intra-pair x spacing but wide row spacing).

methodfrom_positions¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.from_positions

Signature

def from_positions(name: str, x_coordinates: Sequence[float | int], y_coordinates: Sequence[float | int], word_shape: tuple[int, int], *, x_clearance: float, y_clearance: float) -> ZoneBuilder

Build a zone from explicit x/y coordinate arrays.

Convenience constructor that builds the coordinate grid from x_coordinates and y_coordinates (via Grid.from_positions) and forwards the remaining arguments to the default constructor.

Parameters

Name	Type	Description
name	str	Human-readable zone name (stored in Rust Zone).
x_coordinates	Sequence[float | int]	X-coordinates of the grid points (at least one). Every position must be representable at 1 nm precision.
y_coordinates	Sequence[float | int]	Y-coordinates of the grid points (at least one).
word_shape	tuple[int, int]	(num_x_sites, num_y_sites) — uniform shape for all words in this zone.
x_clearance	float	Minimum x-axis clearance (> 0, µm) from grid lines that path waypoints must maintain.
y_clearance	float	Same as ``x_clearance``, applied to the y-axis.

Returns

ZoneBuilderZoneBuilder: The constructed zone.

source

propertyname¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.name

name: str

Zone name.

source

propertyword_shape¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.word_shape

word_shape: tuple[int, int]

(num_x_sites, num_y_sites) for each word.

source

propertysites_per_word¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.sites_per_word

sites_per_word: int

Total sites per word (product of word_shape).

source

propertyx_clearance¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.x_clearance

x_clearance: float

Minimum x-axis clearance (µm) from grid lines for waypoints.

source

propertyy_clearance¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.y_clearance

y_clearance: float

Minimum y-axis clearance (µm) from grid lines for waypoints.

source

propertynum_words¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.num_words

num_words: int

Number of words added so far.

source

methodadd_word¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.add_word

Signature

def add_word(x_sites: slice | Sequence[int], y_sites: slice | Sequence[int], *, has_site_bus: bool = True) -> int

Add a word occupying the given grid positions.

The number of x-indices and y-indices must match word_shape. Grid positions must not overlap with any existing word.

Parameters

Name	Type	Default	Description
x_sites	slice | Sequence[int]	required	Grid x-indices for the word's sites.
y_sites	slice | Sequence[int]	required	Grid y-indices for the word's sites.
has_site_bus	bool	True	Whether this word participates in site-bus transport. Feeds the zone-level ``words_with_site_buses`` list on the final ``ArchSpec`` — only words with ``has_site_bus=True`` are eligible to have site buses applied to them. Defaults to ``True``, which preserves the historical "all words opt-in" behavior. Set to ``False`` on storage words that shouldn't participate in site-level routing.

Returns

intZone-local word index.

Raises

Type	Description
ValueError	Shape mismatch or grid position overlap.
IndexError	Indices out of range for this zone's grid.

source

methodadd_site_bus¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.add_site_bus

def add_site_bus(src: Sequence[int], dst: Sequence[int]) -> None

Add a site bus (intra-word movement).

src/dst are site indices within word_shape (0..sites_per_word). Must have equal length. Validates that src and dst positions each form a valid AOD Cartesian product on the word grid.

Parameters

Name	Type	Description
src	Sequence[int]
dst	Sequence[int]

source

methodadd_word_bus¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.add_word_bus

def add_word_bus(src: Sequence[int], dst: Sequence[int]) -> None

Add a word bus (intra-zone movement).

src/dst are zone-local word indices. Must have equal length. Validates that src and dst word positions each form a valid AOD Cartesian product on the zone grid.

Parameters

Name	Type	Description
src	Sequence[int]
dst	Sequence[int]

source

methodadd_entangling_pairs¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.add_entangling_pairs

Signature

def add_entangling_pairs(words_a: Sequence[int], words_b: Sequence[int]) -> None

Mark paired zone-local words as CZ pairs.

words_a[i] is paired with words_b[i]. The two sequences must have the same length.

For most users, prefer set_blockade_radius — it derives the pair list directly from geometry and validates the word layout against the CZ-pairing convention.

Any blockade_radius previously recorded on this zone (via set_blockade_radius) is cleared, since a manual append means the pair list is no longer purely radius-derived.

Parameters

Name	Type	Description
words_a	Sequence[int]
words_b	Sequence[int]

source

propertyblockade_radius¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.blockade_radius

blockade_radius: float | None

Rydberg blockade radius (µm) used to derive entangling pairs, or None.

source

methodset_blockade_radius¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.set_blockade_radius

def set_blockade_radius(radius: float) -> None

Derive entangling word pairs from the Rydberg blockade radius.

Scans every pair of distinct words in the zone and classifies each under the matching-site-index CZ convention:

• All matching-index site distances <= radius and all non-matching-index site distances > radius: valid CZ pair.
• Some matching-index distances within radius, some outside: ValueError (partial blockade — the word layout doesn’t cleanly map onto the CZ-pairing convention).
• Any non-matching-index site distance within radius (regardless of whether the matching-index distances also fall within): ValueError (crossed-index — two words are arranged such that site i of one word sits next to site j != i of the other, violating the exclusivity the convention requires).
• All distances outside radius: words ignore each other, no pair recorded.

After classification, every word must appear in at most one valid pair; multiple partners raise ValueError.

This call overwrites _entangling_pairs with the scan result and stores the radius on the zone. To have it flow into the final ArchSpec.blockade_radius, either call ArchBuilder.set_blockade_radius (which applies to every zone and records the value at builder scope) or, for a single zone already set via ZoneBuilder.set_blockade_radius, ArchBuilder.build() will pick up a consistent zone-level radius automatically.

Parameters

Name	Type	Description
radius	float	Blockade radius in micrometers. Must be positive and representable at 1 nm precision.

Raises

Type	Description
ValueError	if the layout is inconsistent with the radius (partial blockade / crossed-index / multi-partner) or if ``radius`` is not positive / nm-precise.

source

propertywords¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.words

words: _WordGridQuery

Query word indices by grid region for intra-zone use.

Returns a plain list[int] of zone-local word indices whose sites intersect the queried region — suitable for passing directly to add_word_bus / add_entangling_pairs.

For cross-zone references (e.g. ArchBuilder.connect), index the zone itself (zone[region]) to get a name-qualified (name, list[int]) tuple.

source

propertysites¶source

bloqade.lanes.arch.build.imperative.ZoneBuilder.sites

sites: _SiteGridQuery

Query site indices within the word shape.

source