Blueprint

Architecture blueprint + builder entry point.

Provides the declarative schema (ZoneSpec, DeviceLayout, ArchBlueprint) and the high-level build_arch function that turns a blueprint into a validated ArchSpec.

Internally uses ZoneBuilder + ArchBuilder (from .imperative) for correct-by-construction zone assembly. One blueprint zone = one Rust zone (no splitting).

ArchBlueprint dataclass

ArchBlueprint(
    zones: dict[str, ZoneSpec],
    layout: DeviceLayout = DeviceLayout(),
    feed_forward: bool = False,
    atom_reloading: bool = False,
    blockade_radius: float | None = None,
)

High-level architecture definition composed of named zones and layout.

Zones are ordered by insertion order of the zones dict, which determines word ID assignment (contiguous per zone) and vertical layout (top to bottom).

Parameters:

Name	Type	Description	Default
zones	dict[str, ZoneSpec]	Named zones with their specifications.	required
layout	DeviceLayout	Physical layout parameters for word/site placement.	DeviceLayout()
feed_forward	bool	Whether the device supports feed-forward operations.	False
atom_reloading	bool	Whether the device supports atom reloading.	False
blockade_radius	float | None	Rydberg blockade radius (µm) to record on the ArchSpec. When set, this value is passed directly to ArchSpec.from_components and overrides any radius derived from ArchBuilder.set_blockade_radius or zone-level scans.	None

total_words property

total_words: int

Total number of words across all zones.

words_per_zone property

words_per_zone: int

Number of words per zone (all zones have equal grid dimensions).

zone_names property

zone_names: tuple[str, ...]

Zone names in definition order.

ArchResult dataclass

ArchResult(
    arch: ArchSpec,
    zone_grids: dict[str, WordGrid],
    zone_indices: dict[str, int],
)

Result of build_arch(), containing the ArchSpec and metadata.

DeviceLayout dataclass

DeviceLayout(
    sites_per_word: int = 5,
    site_spacing: float = 10.0,
    pair_spacing: float = 10.0,
    row_spacing: float = 20.0,
    zone_gap: float = 20.0,
    x_clearance: float = 3.0,
    y_clearance: float = 3.0,
)

Physical layout parameters for word and site placement.

Words are horizontal rows with interleaved CZ pairs. Within a pair, sites alternate: even word at x=0, 2s, 4s, ... and odd word at x=s, 3s, 5s, ... where s = site_spacing (blockade radius).

Parameters:

Name	Type	Description	Default
sites_per_word	int	Number of sites per word.	5
site_spacing	float	Distance between adjacent atoms (micrometers). Also determines the CZ blockade distance between paired sites.	10.0
pair_spacing	float	Horizontal gap between adjacent CZ pairs (micrometers).	10.0
row_spacing	float	Vertical distance between word grid rows (micrometers).	20.0
zone_gap	float	Additional vertical gap between zones (micrometers).	20.0
x_clearance	float	Minimum x-axis clearance (µm) between AOD path waypoints and grid lines.	3.0
y_clearance	float	Minimum y-axis clearance (µm) between AOD path waypoints and grid lines. Separate x/y values are useful when row and column spacings differ substantially.	3.0

ZoneSpec dataclass

ZoneSpec(
    num_rows: int,
    num_cols: int,
    entangling: bool = False,
    measurement: bool = True,
    word_topology: WordTopology | None = None,
    site_topology: SiteTopology | None = None,
)

Specification for a single zone in a multi-zone architecture.

Words are arranged in a 2D grid (num_rows x num_cols). Horizontally adjacent word pairs form CZ entangling pairs in entangling zones.

Parameters:

Name	Type	Description	Default
num_rows	int	Number of rows in the word grid. Must be >= 1.	required
num_cols	int	Number of columns in the word grid. Must be >= 2 and even.	required
entangling	bool	Whether this zone supports CZ entangling gates.	False
measurement	bool	Whether this zone supports measurement.	True

num_words property

num_words: int

Total number of words in this zone.

build_arch

build_arch(
    blueprint: ArchBlueprint,
    connections: (
        dict[tuple[str, str], InterZoneTopology] | None
    ) = None,
) -> ArchResult

Build an ArchSpec from a blueprint and inter-zone connections.

One blueprint zone maps to one Rust zone. Entangling pairs are metadata on the zone, not a reason to split into sub-zones.

Parameters:

Name	Type	Description	Default
blueprint	ArchBlueprint	Architecture blueprint with zones and layout.	required
connections	dict[tuple[str, str], InterZoneTopology] | None	Inter-zone connectivity. Keys are (zone_a, zone_b) name pairs, values are InterZoneTopology instances.	None

Returns:

Type	Description
ArchResult	ArchResult with the validated ArchSpec and metadata.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/arch/build/blueprint.py

def build_arch(
    blueprint: ArchBlueprint,
    connections: dict[tuple[str, str], InterZoneTopology] | None = None,
) -> ArchResult:
    """Build an ArchSpec from a blueprint and inter-zone connections.

    One blueprint zone maps to one Rust zone. Entangling pairs are
    metadata on the zone, not a reason to split into sub-zones.

    Args:
        blueprint: Architecture blueprint with zones and layout.
        connections: Inter-zone connectivity. Keys are (zone_a, zone_b) name
            pairs, values are InterZoneTopology instances.

    Returns:
        ArchResult with the validated ArchSpec and metadata.
    """
    connections = connections or {}
    layout = blueprint.layout
    n = layout.sites_per_word
    s = layout.site_spacing

    # Validate connections reference valid zones.
    for zone_a, zone_b in connections:
        if zone_a == zone_b:
            raise ValueError(
                f"Self-connection not allowed: '{zone_a}'. "
                "Use word_topology on ZoneSpec for intra-zone connectivity."
            )
        if zone_a not in blueprint.zones:
            raise ValueError(f"Unknown zone '{zone_a}' in connection")
        if zone_b not in blueprint.zones:
            raise ValueError(f"Unknown zone '{zone_b}' in connection")

    # 1. Create word grids (preserves row/col structure for topology generators).
    zone_grids: dict[str, WordGrid] = {}
    word_id_offset = 0
    for zone_name, zone_spec in blueprint.zones.items():
        grid = create_zone_words(
            zone_spec,
            layout,
            word_id_offset=word_id_offset,
        )
        zone_grids[zone_name] = grid
        word_id_offset += zone_spec.num_words

    # 2. Build ZoneBuilders from blueprint zones.
    zone_builders: dict[str, ZoneBuilder] = {}
    y_offset = 0.0

    for zone_name, zone_spec in blueprint.zones.items():
        word_grid = zone_grids[zone_name]
        rust_grid = _build_zone_grid(zone_spec, layout, n, s, y_offset=y_offset)
        # Advance y_offset past this zone's rows + the inter-zone gap.
        zone_height = max(0, zone_spec.num_rows - 1) * layout.row_spacing
        y_offset += zone_height + layout.zone_gap
        word_shape = _word_shape_from_layout(zone_spec, layout)

        zone = ZoneBuilder(
            zone_name,
            rust_grid,
            word_shape,
            x_clearance=layout.x_clearance,
            y_clearance=layout.y_clearance,
        )

        # Place words on the grid using the same index pattern as create_zone_words.
        for row in range(zone_spec.num_rows):
            for col in range(zone_spec.num_cols):
                word = word_grid.word_at(row, col)
                # Extract x and y indices from the word's site positions.
                x_indices = sorted({site[0] for site in word.site_indices})
                y_indices = sorted({site[1] for site in word.site_indices})
                zone.add_word(x_indices, y_indices)

        # Site buses from topology.
        if zone_spec.site_topology is not None:
            for bus in zone_spec.site_topology.generate_site_buses(
                layout.sites_per_word
            ):
                zone.add_site_bus(list(bus.src), list(bus.dst))

        # Intra-zone word buses from topology.
        if zone_spec.word_topology is not None:
            for bus in zone_spec.word_topology.generate_word_buses(word_grid):
                # Topology generators use global word IDs; convert to zone-local.
                offset = word_grid.word_id_offset
                zone.add_word_bus(
                    src=[w - offset for w in bus.src],
                    dst=[w - offset for w in bus.dst],
                )

        # Entangling pairs.
        if zone_spec.entangling:
            offset = word_grid.word_id_offset
            pairs = list(word_grid.cz_pairs())
            zone.add_entangling_pairs(
                [a - offset for a, _ in pairs],
                [b - offset for _, b in pairs],
            )

        zone_builders[zone_name] = zone

    # 3. Compose zones into ArchBuilder.
    arch_builder = ArchBuilder()
    zone_indices: dict[str, int] = {}

    for zone_name, zone in zone_builders.items():
        zid = arch_builder.add_zone(zone)
        zone_indices[zone_name] = zid

    # 4. Inter-zone connections → zone_buses.
    for (zone_a_name, zone_b_name), topology in connections.items():
        grid_a = zone_grids[zone_a_name]
        grid_b = zone_grids[zone_b_name]
        offset_a = grid_a.word_id_offset
        offset_b = grid_b.word_id_offset

        for bus in topology.generate_word_buses(grid_a, grid_b):
            # Convert global word IDs to zone-local for connect().
            src_local = [w - offset_a for w in bus.src]
            dst_local = [w - offset_b for w in bus.dst]
            arch_builder.connect(
                src=(zone_a_name, src_local),
                dst=(zone_b_name, dst_local),
            )

    # 5. Modes.
    all_zone_names = list(blueprint.zones.keys())
    arch_builder.add_mode("all", all_zone_names)

    for name, spec in blueprint.zones.items():
        if spec.measurement:
            arch_builder.add_mode(name, [name])

    # 6. Build and return.
    arch = arch_builder.build(
        feed_forward=blueprint.feed_forward,
        atom_reloading=blueprint.atom_reloading,
        blockade_radius=blueprint.blockade_radius,
    )

    return ArchResult(
        arch=arch,
        zone_grids=zone_grids,
        zone_indices=zone_indices,
    )