Skip to content

Word factory

Word creation helpers for zone-based architectures.

Creates row-words arranged in a 2D grid. CZ pairing between horizontally adjacent words is defined at the zone level via entangling_pairs, not per-word.

Words now contain grid index pairs (x_idx, y_idx). Physical positions are resolved via the zone's Grid at the ArchSpec level. Each word has unique grid indices that map to distinct positions within the zone grid.

WordGrid dataclass 

WordGrid(
    words: tuple[Word, ...],
    num_rows: int,
    num_cols: int,
    word_id_offset: int,
)

2D grid of words within a zone, preserving row/col structure.

all_word_ids property 

all_word_ids: range

All word IDs in this grid (contiguous range).

cz_pairs 

cz_pairs() -> Iterator[tuple[int, int]]

Yield (word_id_a, word_id_b) for all CZ entangling pairs.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/arch/build/word_factory.py 
47
48
49
50
51
def cz_pairs(self) -> Iterator[tuple[int, int]]:
    """Yield (word_id_a, word_id_b) for all CZ entangling pairs."""
    for row in range(self.num_rows):
        for col in range(0, self.num_cols, 2):
            yield (self.word_id_at(row, col), self.word_id_at(row, col + 1))

word_at 

word_at(row: int, col: int) -> Word

Get the word at a given grid position.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/arch/build/word_factory.py 
34
35
36
def word_at(self, row: int, col: int) -> Word:
    """Get the word at a given grid position."""
    return self.words[row * self.num_cols + col]

word_id_at 

word_id_at(row: int, col: int) -> int

Get the global word ID at a given grid position.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/arch/build/word_factory.py 
38
39
40
def word_id_at(self, row: int, col: int) -> int:
    """Get the global word ID at a given grid position."""
    return self.word_id_offset + row * self.num_cols + col

create_zone_words 

create_zone_words(
    zone_spec: ZoneSpec,
    layout: DeviceLayout,
    x_offset: float = 0.0,
    y_offset: float = 0.0,
    word_id_offset: int = 0,
) -> WordGrid

Create all words for a zone in a 2D grid layout.

Each word's sites are represented as grid index pairs (x_idx, y_idx). For interleaved CZ pairs: - Even-column words: sites at x_idx = 0, 2, 4, ... (in the full grid) - Odd-column words: sites at x_idx = 1, 3, 5, ...

Words in different rows use different y_idx values.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/arch/build/word_factory.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def create_zone_words(
    zone_spec: ZoneSpec,
    layout: DeviceLayout,
    x_offset: float = 0.0,
    y_offset: float = 0.0,
    word_id_offset: int = 0,
) -> WordGrid:
    """Create all words for a zone in a 2D grid layout.

    Each word's sites are represented as grid index pairs (x_idx, y_idx).
    For interleaved CZ pairs:
    - Even-column words: sites at x_idx = 0, 2, 4, ... (in the full grid)
    - Odd-column words: sites at x_idx = 1, 3, 5, ...

    Words in different rows use different y_idx values.
    """
    n = layout.sites_per_word
    num_cols = zone_spec.num_cols

    words: list[Word] = []

    for row in range(zone_spec.num_rows):
        for col in range(num_cols):
            pair_idx = col // 2
            is_odd = col % 2
            # Number of x positions per pair: 2*n (interleaved)
            x_base = pair_idx * 2 * n
            if is_odd:
                # Odd column: sites at odd x indices
                sites = tuple((x_base + 2 * i + 1, row) for i in range(n))
            else:
                # Even column: sites at even x indices
                sites = tuple((x_base + 2 * i, row) for i in range(n))
            words.append(Word(sites))

    return WordGrid(
        words=tuple(words),
        num_rows=zone_spec.num_rows,
        num_cols=zone_spec.num_cols,
        word_id_offset=word_id_offset,
    )