Skip to content

Task

append_measurements_and_annotations

append_measurements_and_annotations(
    mt: Method,
    m2dets: list[list[int]] | None,
    m2obs: list[list[int]] | None,
) -> None

Append terminal measurement, detector, and observable IR statements to a squin kernel.

The method is mutated in-place.

The annotations are Steane [[7,1,3]], so both matrices must be rectangular with one row per physical qubit: num_qubits * 7. A shape that disagrees is a ValueError rather than a silently mis-indexed annotation.

Parameters:

Name Type Description Default
mt Method

A squin ir.Method whose body returns None.

required
m2dets list[list[int]] | None

Binary matrix of shape (num_qubits * 7, num_detectors). Each column defines a detector by its non-zero row indices.

required
m2obs list[list[int]] | None

Binary matrix of shape (num_qubits * 7, num_observables). Each column defines an observable by its non-zero row indices.

required

Raises:

Type Description
ValueError

If neither matrix is given; if mt allocates no qubits; if either matrix has the wrong number of rows or is ragged; or if mt's terminal measurement already declares a width other than Steane [[7,1,3]]'s seven.

Source code in .venv/lib/python3.12/site-packages/bloqade/gemini/compile/task.py
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
def append_measurements_and_annotations(
    mt: ir.Method,
    m2dets: list[list[int]] | None,
    m2obs: list[list[int]] | None,
) -> None:
    """Append terminal measurement, detector, and observable IR statements to a squin kernel.

    The method is mutated in-place.

    The annotations are Steane [[7,1,3]], so both matrices must be rectangular
    with one row per physical qubit: ``num_qubits * 7``. A shape that disagrees
    is a ``ValueError`` rather than a silently mis-indexed annotation.

    Args:
        mt: A squin ``ir.Method`` whose body returns ``None``.
        m2dets: Binary matrix of shape ``(num_qubits * 7, num_detectors)``.
            Each column defines a detector by its non-zero row indices.
        m2obs: Binary matrix of shape ``(num_qubits * 7, num_observables)``.
            Each column defines an observable by its non-zero row indices.

    Raises:
        ValueError: If neither matrix is given; if ``mt`` allocates no qubits;
            if either matrix has the wrong number of rows or is ragged; or if
            ``mt``'s terminal measurement already declares a width other than
            Steane [[7,1,3]]'s seven.
    """

    if m2dets is None and m2obs is None:
        raise ValueError("At least one of m2dets or m2obs must be provided")

    qubit_ssas = _find_qubit_ssas(mt)
    num_qubits = len(qubit_ssas)
    if num_qubits == 0:
        raise ValueError("No qubit allocations found in the kernel")

    existing_terminal = next(
        (
            s
            for s in mt.callable_region.walk()
            if isinstance(s, TerminalLogicalMeasurement)
        ),
        None,
    )
    # Everything below addresses a measurement as ``divmod(row,
    # STEANE7_PHYSICAL_QUBITS)``, so a statement that already declares some
    # other width would have its records read at the wrong stride -- wrong
    # detectors, or an out-of-range index into a narrower logical measurement.
    # Nothing here honours a non-Steane width, so say so instead.
    if (
        existing_terminal is not None
        and existing_terminal.num_physical_qubits is not None
        and existing_terminal.num_physical_qubits != STEANE7_PHYSICAL_QUBITS
    ):
        raise ValueError(
            "This function inserts Steane [[7,1,3]] annotations, but the "
            "kernel's terminal measurement declares num_physical_qubits="
            f"{existing_terminal.num_physical_qubits}"
        )

    # The annotations below address a measurement as ``divmod(row,
    # STEANE7_PHYSICAL_QUBITS)``, and the terminal measurement is stamped with
    # that same width. Deriving the stride from ``len(m2) // num_qubits``
    # instead would make the matrices a second, unchecked source of the width:
    # a matrix disagreeing with the stamp yields detectors that reference the
    # wrong records, with no error. Validate against the one source instead.
    expected_rows = num_qubits * STEANE7_PHYSICAL_QUBITS
    for name, matrix in (("m2dets", m2dets), ("m2obs", m2obs)):
        if matrix is None:
            continue
        if len(matrix) != expected_rows:
            raise ValueError(
                f"{name} has {len(matrix)} rows, expected {expected_rows}: "
                f"{num_qubits} logical qubit(s) x {STEANE7_PHYSICAL_QUBITS} "
                "physical qubits per Steane [[7,1,3]] qubit"
            )
        # Columns are read as ``row[j]`` for every j in the first row's range,
        # so a ragged matrix either raises IndexError from inside the
        # annotation loop or silently ignores a longer row's extra columns.
        column_counts = {len(row) for row in matrix}
        if len(column_counts) > 1:
            raise ValueError(
                f"{name} is ragged: rows have {sorted(column_counts)} columns. "
                "Every row must define the same number of annotations"
            )

    return_stmt = _find_return_stmt(mt)

    # insert TerminalLogicalMeasurement if not present
    if existing_terminal is not None:
        term_meas = existing_terminal
    else:
        qlist_stmt = _insert_before(ilist.New(qubit_ssas), return_stmt)
        term_meas = _insert_before(
            TerminalLogicalMeasurement(qlist_stmt.result), return_stmt
        )

    # ``InsertQubitCount`` stamps this attribute during ``@logical.kernel``
    # decoration, but a statement inserted here is created afterwards and so is
    # never walked -- it stays ``None``, and ``MeasurementIDAnalysis`` then
    # cannot expand a logical measurement into per-physical-qubit records
    # (every logical qubit degrades to ``AnyMeasureId``, taking the detectors
    # with it). The annotations this function inserts are Steane [[7,1,3]], so
    # the width is known here. A statement that already carries a count keeps
    # it.
    if term_meas.num_physical_qubits is None:
        term_meas.num_physical_qubits = STEANE7_PHYSICAL_QUBITS

    @cache
    def _get_logical_measurement(q_idx: int) -> ir.SSAValue:
        (idx := py.Constant(q_idx)).insert_before(return_stmt)
        (getitem := py.GetItem(term_meas.result, idx.result)).insert_before(return_stmt)
        return getitem.result

    @cache
    def _get_physical_measurement(q_idx: int, m_idx: int) -> ir.SSAValue:
        (idx := py.Constant(m_idx)).insert_before(return_stmt)
        (
            getitem := py.GetItem(_get_logical_measurement(q_idx), idx.result)
        ).insert_before(return_stmt)
        return getitem.result

    # insert detectors
    if m2dets is not None:
        for j in range(len(m2dets[0])):
            indices = [i for i, row in enumerate(m2dets) if row[j]]
            meas_ssas = [
                _get_physical_measurement(*divmod(idx, STEANE7_PHYSICAL_QUBITS))
                for idx in indices
            ]
            meas_list = _insert_before(ilist.New(meas_ssas), return_stmt)

            coord_0 = _insert_before(py.Constant(0.0), return_stmt)
            coord_1 = _insert_before(py.Constant(float(j)), return_stmt)
            coords = _insert_before(
                ilist.New([coord_0.result, coord_1.result]), return_stmt
            )

            _insert_before(SetDetector(meas_list.result, coords.result), return_stmt)

    # insert observables
    if m2obs is not None:
        for j in range(len(m2obs[0])):
            indices = [i for i, row in enumerate(m2obs) if row[j]]
            meas_ssas = [
                _get_physical_measurement(*divmod(idx, STEANE7_PHYSICAL_QUBITS))
                for idx in indices
            ]
            meas_list = _insert_before(ilist.New(meas_ssas), return_stmt)
            _insert_before(SetObservable(meas_list.result), return_stmt)

compile_task

compile_task(
    logical_kernel: Method | Callable[..., Any],
    m2dets: list[list[int]] | None = None,
    m2obs: list[list[int]] | None = None,
)

Compile a logical kernel into physical move artifacts.

Handles CUDAQ kernel detection/conversion, squin kernel validation, squin-to-move compilation, architecture spec generation, and post-processing extraction.

Parameters:

Name Type Description Default
logical_kernel Method | Callable[..., Any]

A squin ir.Method or a CUDA-Q kernel to compile.

required
m2dets list[list[int]] | None

Binary measurement-to-detector matrix. For CUDA-Q kernels, defaults to Steane [[7,1,3]] detectors if None.

None
m2obs list[list[int]] | None

Binary measurement-to-observable matrix. For CUDA-Q kernels, defaults to Steane [[7,1,3]] observables if None.

None

Returns:

Type Description

A tuple of ``(logical_squin_kernel, physical_arch_spec,

physical_move_kernel, post_processing)``.

Source code in .venv/lib/python3.12/site-packages/bloqade/gemini/compile/task.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
def compile_task(
    logical_kernel: ir.Method | Callable[..., Any],
    m2dets: list[list[int]] | None = None,
    m2obs: list[list[int]] | None = None,
):
    """Compile a logical kernel into physical move artifacts.

    Handles CUDAQ kernel detection/conversion, squin kernel validation,
    squin-to-move compilation, architecture spec generation, and
    post-processing extraction.

    Args:
        logical_kernel: A squin ``ir.Method`` or a CUDA-Q kernel to compile.
        m2dets: Binary measurement-to-detector matrix. For CUDA-Q kernels,
            defaults to Steane [[7,1,3]] detectors if ``None``.
        m2obs: Binary measurement-to-observable matrix. For CUDA-Q kernels,
            defaults to Steane [[7,1,3]] observables if ``None``.

    Returns:
        A tuple of ``(logical_squin_kernel, physical_arch_spec,
        physical_move_kernel, post_processing)``.

    """
    if is_cudaq_kernel(logical_kernel):
        logical_squin_kernel: ir.Method = cudaq_to_squin(logical_kernel)

        if m2dets is None and m2obs is None:
            num_qubits = len(_find_qubit_ssas(logical_squin_kernel))
            m2dets = steane7_m2dets(num_qubits)
            m2obs = steane7_m2obs(num_qubits)

        append_measurements_and_annotations(logical_squin_kernel, m2dets, m2obs)
    elif isinstance(logical_kernel, ir.Method):
        # Compilation and annotation rewrites are in-place. Work on an owned
        # copy so creating a task never changes a caller-owned kernel.
        logical_squin_kernel = logical_kernel.similar()
        if m2dets is not None or m2obs is not None:
            append_measurements_and_annotations(logical_squin_kernel, m2dets, m2obs)
    else:
        raise ValueError(f"Unknown kernel type {type(logical_kernel)}")

    run_squin_kernel_validation(logical_squin_kernel).raise_if_invalid()

    physical_arch_spec = physical.get_arch_spec()
    physical_move_kernel = LogicalPipeline(transversal_rewrite=True).emit(
        logical_squin_kernel
    )
    post_processing = build_post_processing(logical_squin_kernel)

    return (
        logical_squin_kernel,
        physical_arch_spec,
        physical_move_kernel,
        post_processing,
    )

run_squin_kernel_validation

run_squin_kernel_validation(mt: Method)

Run validation checks on a Squin kernel method.

Parameters:

Name Type Description Default
mt Method

The Squin kernel method to validate.

required

Returns:

Name Type Description
ValidationResult

A validation result object containing the validation errors, if they exist

Note: To trigger an error run run_squin_kernel_validation(mt).raise_if_invalid().

Source code in .venv/lib/python3.12/site-packages/bloqade/gemini/compile/task.py
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def run_squin_kernel_validation(mt: ir.Method):
    """
    Run validation checks on a Squin kernel method.

    Args:
        mt (ir.Method): The Squin kernel method to validate.

    Returns:
        ValidationResult: A validation result object containing the
            validation errors, if they exist

    Note: To trigger an error run `run_squin_kernel_validation(mt).raise_if_invalid()`.

    """
    validator = ValidationSuite(
        [
            GeminiLogicalValidation,
            GeminiTerminalMeasurementValidation,
            FlatKernelNoCloningValidation,
            # NOTE: not redundant with the `@logical.kernel` decorator. A method
            # reaching `compile_task` need never have been decorated -- the
            # CUDA-Q path builds one by conversion -- so this is the only place
            # the no-arguments contract is checked on that route.
            GeminiLogicalArgumentValidation,
        ]
    )
    return validator.validate(mt)