Python API Reference¶

Compile a quantum circuit string to an executable sampling program.

Ordinary compilation runs parse -> trace -> [HIR optimize], then plans and prepares the result as a reusable sampling program.

When normalize_syndromes=True, a noiseless reference shot is executed internally to extract expected detector and observable parities. Detectors and observables are then XOR-normalized so that 0 means 'matches noiseless reference' and 1 means 'error'.

Parameters:

303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351

def compile(
    stim_text: str,
    postselection_mask: list[int] | None = None,
    expected_detectors: list[int] | None = None,
    expected_observables: list[int] | None = None,
    normalize_syndromes: bool = False,
    hir_passes: HirPassManager | None | _DefaultPasses = _DEFAULT_PASSES,
    input_format: Literal["stim", "qasm2"] = "stim",
) -> Program:
    """Compile a quantum circuit string to an executable sampling program.

    Ordinary compilation runs parse -> trace -> [HIR optimize], then plans and
    prepares the result as a reusable sampling program.

    When ``normalize_syndromes=True``, a noiseless reference shot is
    executed internally to extract expected detector and observable
    parities. Detectors and observables are then XOR-normalized so
    that 0 means 'matches noiseless reference' and 1 means 'error'.

    Args:
        stim_text: Circuit text in the format selected by ``input_format``.
        postselection_mask: Optional list of uint8 flags, one per detector.
            Detectors where mask[i] != 0 become post-selection checks
            that abort the shot early if their parity is non-zero.
        expected_detectors: Optional noiseless reference parities for detectors.
        expected_observables: Optional noiseless reference parities for observables.
        normalize_syndromes: If True, auto-compute reference parities from a
            noiseless reference shot (mutually exclusive with explicit parities).
        hir_passes: HirPassManager to run on the HIR before lowering.
            Defaults to ``default_hir_pass_manager()``. Pass ``None`` to skip.
        input_format: ``"stim"`` for Clifft's Stim-compatible syntax or
            ``"qasm2"`` for the supported unitary OpenQASM 2 subset.
    """
    if isinstance(hir_passes, _DefaultPasses):
        hir_passes = default_hir_pass_manager()
    if input_format == "stim":
        compile_core = _compile_core
    elif input_format == "qasm2":
        compile_core = _compile_qasm2_core
    else:
        raise ValueError("input_format must be 'stim' or 'qasm2'")
    return compile_core(
        stim_text,
        postselection_mask if postselection_mask is not None else [],
        expected_detectors if expected_detectors is not None else [],
        expected_observables if expected_observables is not None else [],
        normalize_syndromes,
        hir_passes,
    )

parse(text: str) -> clifft._clifft_core.Circuit parse(text: str, max_ops: int) -> clifft._clifft_core.Circuit

Overloaded function.

1. parse(text: str) -> clifft._clifft_core.Circuit

Parse a quantum circuit from a string.

1. parse(text: str, max_ops: int) -> clifft._clifft_core.Circuit

Parse a quantum circuit from a string with an explicit AST node limit.

parse_file(path: str) -> clifft._clifft_core.Circuit parse_file(path: str, max_ops: int) -> clifft._clifft_core.Circuit

Overloaded function.

1. parse_file(path: str) -> clifft._clifft_core.Circuit

Parse a quantum circuit from a file.

1. parse_file(path: str, max_ops: int) -> clifft._clifft_core.Circuit

Parse a quantum circuit from a file with an explicit AST node limit.

parse_qasm2(text: str) -> clifft._clifft_core.Qasm2Import parse_qasm2(text: str, max_ops: int) -> clifft._clifft_core.Qasm2Import

Overloaded function.

1. parse_qasm2(text: str) -> clifft._clifft_core.Qasm2Import

Parse and lower a unitary OpenQASM 2 circuit.

1. parse_qasm2(text: str, max_ops: int) -> clifft._clifft_core.Qasm2Import

Parse and lower a unitary OpenQASM 2 circuit with an explicit AST node limit.

parse_qasm2_file(path: str) -> clifft._clifft_core.Qasm2Import parse_qasm2_file(path: str, max_ops: int) -> clifft._clifft_core.Qasm2Import

Overloaded function.

1. parse_qasm2_file(path: str) -> clifft._clifft_core.Qasm2Import

Parse and lower a unitary OpenQASM 2 circuit file.

1. parse_qasm2_file(path: str, max_ops: int) -> clifft._clifft_core.Qasm2Import

Parse and lower a unitary OpenQASM 2 file with an explicit AST node limit.

trace(circuit: clifft._clifft_core.Circuit) -> clifft._clifft_core.HirModule

Trace a parsed circuit through the Clifford front-end to produce the Heisenberg IR. Single-qubit rotations within 1e-12 half-turns of a Clifford angle are canonicalized.

lower(hir: clifft._clifft_core.HirModule, postselection_mask: collections.abc.Sequence[int] = [], expected_detectors: collections.abc.Sequence[int] = [], expected_observables: collections.abc.Sequence[int] = []) -> clifft._clifft_core.Program

Lower a Heisenberg IR module to an executable sampling program.

Parameters:

sample(program: Program, shots: int, seed: int | None = None, threads: int | typing.Literal['auto'] = 1, thread_layout: tuple[int, int] | None = None, intra_shot_min_active_width: int | None = None, batch_size: int | typing.Literal['auto', 'tune'] = 'auto', *, tuning_budget_seconds: float | None = None) -> clifft.SampleResult

Run a compiled program and return a SampleResult.

Raises ValueError for post-selected programs because fixed-row output cannot represent discarded shots. Use sample_survivors() instead.

If seed is None (default), uses hardware entropy. threads is a positive total worker budget or 'auto' to use the implementation-reported hardware concurrency; it defaults to 1. Automatic scheduling uses either cross-shot or intra-shot workers. thread_layout=(shot_workers, intra_shot_workers) overrides that choice and ignores threads; intra-shot counts above 1 require OpenMP support. intra_shot_min_active_width overrides the default threshold of 18 for an explicit layout. batch_size='auto' uses the conservative plan policy; 1 forces scalar execution, and a positive integer requests a packed lane-capacity limit. Seeded results replay within one batching configuration, but individual rows may differ between scalar and packed modes or different capacities.

batch_size='tune' calibrates before running all requested shots. tuning_budget_seconds is a soft calibration deadline, defaulting to 0.25 seconds. Trials are extra work and are excluded from returned rows and counts. The selected configuration and timings are in result.batch_tuning. Timing-based selection need not replay for a fixed seed; pin a numeric batch_size for debugging.

Returns a SampleResult with .measurements, .detectors, .observables attributes. Supports tuple unpacking: m, d, o = clifft.sample(prog, shots)

sample_survivors(program: Program, shots: int, seed: int | None = None, keep_records: bool = False, threads: int | typing.Literal['auto'] = 1, thread_layout: tuple[int, int] | None = None, intra_shot_min_active_width: int | None = None, batch_size: int | typing.Literal['auto', 'tune'] = 'auto', *, tuning_budget_seconds: float | None = None) -> clifft.SampleResult

Sample shots and return results only for surviving (non-discarded) shots.

If seed is None (default), uses hardware entropy. threads is a positive total worker budget or 'auto' to use the implementation-reported hardware concurrency; it defaults to 1. thread_layout=(shot_workers, intra_shot_workers) overrides automatic scheduling. intra_shot_min_active_width overrides the default threshold of 18 for an explicit layout. batch_size='auto' uses the conservative plan policy and remains scalar when the program has postselection; 1 forces scalar execution, and a positive integer requests a packed lane-capacity limit.

batch_size='tune' calibrates before running all requested shots. tuning_budget_seconds is a soft calibration deadline, defaulting to 0.25 seconds. Trials are extra work and are excluded from returned rows and counts. The selected configuration and timings are in result.batch_tuning. Timing-based selection need not replay for a fixed seed; pin a numeric batch_size for debugging.

Returns a SampleResult. Survivor metadata is always populated via .total_shots, .passed_shots, .discards, .logical_errors, and .observable_ones. Per-shot record arrays (.measurements, .detectors, .observables, .exp_vals) are only filled when keep_records=True; otherwise they are empty (rows=0).

sample_k(program: Program, shots: int, k: int, seed: int | None = None, threads: int | typing.Literal['auto'] = 1, thread_layout: tuple[int, int] | None = None, intra_shot_min_active_width: int | None = None, batch_size: int | typing.Literal['auto', 'tune'] = 'auto', *, tuning_budget_seconds: float | None = None) -> clifft.SampleResult

Sample with exactly k forced faults per shot (importance sampling).

Sites are drawn from the exact conditional Poisson-Binomial distribution. Results are conditioned on K=k and must be combined across strata with P(K=k) weights for correct error rate estimation. Raises ValueError for post-selected programs because fixed-row output cannot represent discarded shots. Use sample_k_survivors() instead.

For post-selected circuits, weight numerator and denominator separately via sample_k_survivors(): p_fail = sum(P(K=k)errors_k/shots_k) / sum(P(K=k)passed_k/shots_k).

Raises ValueError if the k-fault stratum has zero probability mass (e.g. k exceeds the number of non-zero-probability sites).

When all site probabilities are equal, an O(k) Fisher-Yates sampler is used automatically. threads is a positive total worker budget or 'auto' to use the implementation-reported hardware concurrency; it defaults to 1. thread_layout=(shot_workers, intra_shot_workers) overrides automatic scheduling. intra_shot_min_active_width overrides the default threshold of 18 for an explicit layout. batch_size='auto' uses the conservative plan policy; 1 forces scalar execution, and a positive integer requests a packed lane-capacity limit.

batch_size='tune' calibrates before running all requested shots. tuning_budget_seconds is a soft calibration deadline, defaulting to 0.25 seconds. Trials are extra work and are excluded from returned rows and counts. The selected configuration and timings are in result.batch_tuning. Timing-based selection need not replay for a fixed seed; pin a numeric batch_size for debugging.

Returns a SampleResult with .measurements, .detectors, .observables attributes. Supports tuple unpacking: m, d, o = clifft.sample_k(prog, shots, k)

sample_k_survivors(program: Program, shots: int, k: int, seed: int | None = None, keep_records: bool = False, threads: int | typing.Literal['auto'] = 1, thread_layout: tuple[int, int] | None = None, intra_shot_min_active_width: int | None = None, batch_size: int | typing.Literal['auto', 'tune'] = 'auto', *, tuning_budget_seconds: float | None = None) -> clifft.SampleResult

Sample survivors with exactly k forced faults per shot.

Results are conditioned on K=k. To estimate the overall logical error rate across strata, weight numerator and denominator separately to account for k-dependent survival probability: p_fail = sum(P(K=k)logical_errors_k/shots_k) / sum(P(K=k)passed_k/shots_k)

Raises ValueError if the k-fault stratum has zero probability mass. threads is a positive total worker budget or 'auto' to use the implementation-reported hardware concurrency; it defaults to 1. thread_layout=(shot_workers, intra_shot_workers) overrides automatic scheduling. intra_shot_min_active_width overrides the default threshold of 18 for an explicit layout. batch_size='auto' uses the conservative plan policy and remains scalar when the program has postselection; 1 forces scalar execution, and a positive integer requests a packed lane-capacity limit.

batch_size='tune' calibrates before running all requested shots. tuning_budget_seconds is a soft calibration deadline, defaulting to 0.25 seconds. Trials are extra work and are excluded from returned rows and counts. The selected configuration and timings are in result.batch_tuning. Timing-based selection need not replay for a fixed seed; pin a numeric batch_size for debugging.

Returns a SampleResult. Survivor metadata is always populated via .total_shots, .passed_shots, .discards, .logical_errors, and .observable_ones. Per-shot record arrays (.measurements, .detectors, .observables, .exp_vals) are only filled when keep_records=True; otherwise they are empty (rows=0).

Return whether this Clifft installation contains the HIP extension.

34
35
36

def is_built() -> bool:
    """Return whether this Clifft installation contains the HIP extension."""
    return _NATIVE_SPEC is not None

Return whether the extension loaded and can see an AMD GPU.

39
40
41

def is_available() -> bool:
    """Return whether the extension loaded and can see an AMD GPU."""
    return _native is not None and bool(_native.is_available())

Describe the optional extension and any devices visible to HIP.

44
45
46
47
48
49
50

def backend_info() -> str:
    """Describe the optional extension and any devices visible to HIP."""
    if _NATIVE_SPEC is None:
        return "HIP backend not built; rebuild Clifft with CLIFFT_ENABLE_HIP=ON"
    if _native is None:
        return f"HIP extension failed to load: {_native_error}"
    return cast(str, _native.backend_info())

Compile Stim text through the shared HIR and SamplingPlan pipeline.

141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

def compile(
    stim_text: str,
    postselection_mask: list[int] | None = None,
    expected_detectors: list[int] | None = None,
    expected_observables: list[int] | None = None,
    normalize_syndromes: bool = False,
    hir_passes: HirPassManager | None | _DefaultPasses = _DEFAULT_PASSES,
) -> Program:
    """Compile Stim text through the shared HIR and SamplingPlan pipeline."""
    if isinstance(hir_passes, _DefaultPasses):
        hir_passes = default_hir_pass_manager()
    prepared = _prepare_hir_for_lowering(
        stim_text,
        expected_detectors if expected_detectors is not None else [],
        expected_observables if expected_observables is not None else [],
        normalize_syndromes,
        hir_passes,
    )
    hir = cast(HirModule, prepared[0])
    detectors = cast(list[int], prepared[1])
    observables = cast(list[int], prepared[2])
    return lower(hir, postselection_mask, detectors, observables)

Return whether this Clifft installation contains the CUDA extension.

35
36
37

def is_built() -> bool:
    """Return whether this Clifft installation contains the CUDA extension."""
    return _NATIVE_SPEC is not None

Return whether the extension loaded and can see an NVIDIA GPU.

40
41
42

def is_available() -> bool:
    """Return whether the extension loaded and can see an NVIDIA GPU."""
    return _native is not None and bool(_native.is_available())

Describe the optional extension and any devices visible to CUDA.

45
46
47
48
49
50
51

def backend_info() -> str:
    """Describe the optional extension and any devices visible to CUDA."""
    if _NATIVE_SPEC is None:
        return "CUDA backend not built; rebuild Clifft with CLIFFT_ENABLE_CUDA=ON"
    if _native is None:
        return f"CUDA extension failed to load: {_native_error}"
    return cast(str, _native.backend_info())

Compile Stim text through the shared HIR and SamplingPlan pipeline.

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

def compile(
    stim_text: str,
    postselection_mask: list[int] | None = None,
    expected_detectors: list[int] | None = None,
    expected_observables: list[int] | None = None,
    normalize_syndromes: bool = False,
    hir_passes: HirPassManager | None | _DefaultPasses = _DEFAULT_PASSES,
) -> Program:
    """Compile Stim text through the shared HIR and SamplingPlan pipeline."""
    if isinstance(hir_passes, _DefaultPasses):
        hir_passes = default_hir_pass_manager()
    prepared = _prepare_hir_for_lowering(
        stim_text,
        expected_detectors if expected_detectors is not None else [],
        expected_observables if expected_observables is not None else [],
        normalize_syndromes,
        hir_passes,
    )
    hir = cast(HirModule, prepared[0])
    detectors = cast(list[int], prepared[1])
    observables = cast(list[int], prepared[2])
    return lower(hir, postselection_mask, detectors, observables)

Report the execution tier automatic selection picks on the current device.

192
193
194
195

def selected_tier(program: Program, precision: Precision = "fp64") -> Tier:
    """Report the execution tier automatic selection picks on the current device."""
    native = _require_native()
    return _tier_name(native.selected_tier(program._native, _precision_value(precision)))

Sample circuit under model for shots shots.

On a leaked or lost site, M, MX, MY, MR, MRX, and MRY sample the classifier without regard to measurement basis. A model that can leak or lose sites requires a classifier when the circuit measures a physical site. Parity measurements (MPP) and EXP_VAL probes are not supported with such models.

HERALD_LEAKAGE_EVENT and HERALD_LOSS_EVENT append nondestructive status checks to the ordinary measurement record. They take no arguments; use READOUT_NOISE to model probe errors. They require no classifier and leave their entries in the classifier heralds sidecar zero.

LEAKAGE_INTERACTION and LOSS_INTERACTION apply conditional partner effects without adding records. Model-generated interactions precede the gate's level-transition hooks. Explicit annotations evaluate status at their own expanded position and compose with generated effects.

Continuations are compiled with the default optimization passes that preserve measurement-record order and instrument-prefix stability, omitting StatevectorSqueezePass. Reordering can change the placement of internal collapse outcomes relative to later records. This API does not currently accept custom pass managers.

Parameters:

Returns:

Raises:

389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452

def sample(
    circuit: Circuit | str,
    model: Model,
    shots: int,
    seed: int | None = None,
    max_active_width: int | None = None,
    threads: int | Literal["auto"] = 1,
) -> NonComputationalSample:
    """Sample ``circuit`` under ``model`` for ``shots`` shots.

    On a leaked or lost site, ``M``, ``MX``, ``MY``, ``MR``, ``MRX``, and
    ``MRY`` sample the classifier without regard to measurement basis. A model
    that can leak or lose sites requires a classifier when the circuit
    measures a physical site. Parity measurements (``MPP``) and ``EXP_VAL``
    probes are not supported with such models.

    ``HERALD_LEAKAGE_EVENT`` and ``HERALD_LOSS_EVENT`` append nondestructive
    status checks to the ordinary measurement record. They take no arguments;
    use ``READOUT_NOISE`` to model probe errors. They require no classifier and
    leave their entries in the classifier ``heralds`` sidecar zero.

    ``LEAKAGE_INTERACTION`` and ``LOSS_INTERACTION`` apply conditional partner
    effects without adding records. Model-generated interactions precede the
    gate's level-transition hooks. Explicit annotations evaluate status at their
    own expanded position and compose with generated effects.

    Continuations are compiled with the default optimization passes that
    preserve measurement-record order and instrument-prefix stability, omitting
    [StatevectorSqueezePass][clifft.StatevectorSqueezePass]. Reordering can
    change the placement of internal collapse outcomes relative to later
    records. This API does not currently accept custom pass managers.

    Args:
        circuit: Parsed ``clifft.Circuit`` or Stim-format circuit string.
        model: Leakage and loss model.
        shots: Number of trajectories to sample.
        seed: Seed for reproducible sampling. The same seed and arguments
            produce identical results. When ``None``, each call uses fresh OS
            entropy.
        max_active_width: Optional cap on the peak active width of every compiled
            continuation. The check is conservative because a continuation
            may contain branches that the current shot will not take.
        threads: Number of cross-shot workers. Defaults to 1. Pass ``"auto"``
            to use the implementation-reported hardware concurrency. Seeded
            results are identical for every worker count.

    Returns:
        [NonComputationalSample][clifft.noncomp.NonComputationalSample]
        containing measurement, detector, observable, herald, and final-status
        arrays.

    Raises:
        ValueError: If a model or circuit contract is violated, an annotation
            is malformed, or a continuation exceeds ``max_active_width``.
    """
    return _sample_with(
        circuit,
        model,
        shots,
        seed,
        max_active_width,
        threads,
        _clifft_core._sample_noncomputational,
    )

Exact Born probabilities of computational-basis bitstrings.

Requires a unitary program (no measurements, feedback, noise, detectors, observables, or post-selection). For circuits with measurements, use :func:record_probabilities instead.

bit_order="big" maps the first character or array column to qubit 0. bit_order="little" maps the last character or array column to qubit 0.

Pass return_log=True to get natural-log probabilities. Zero probabilities map to -inf in log output.

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

def basis_probabilities(
    program: Program,
    bitstrings: BasisBitstrings,
    *,
    bit_order: str = "big",
    return_log: bool = False,
) -> npt.NDArray[np.float64]:
    """Exact Born probabilities of computational-basis bitstrings.

    Requires a unitary program (no measurements, feedback, noise, detectors,
    observables, or post-selection). For circuits with measurements, use
    :func:`record_probabilities` instead.

    ``bit_order="big"`` maps the first character or array column to qubit 0.
    ``bit_order="little"`` maps the last character or array column to qubit 0.

    Pass ``return_log=True`` to get natural-log probabilities. Zero
    probabilities map to ``-inf`` in log output.
    """
    probs = cast(
        npt.NDArray[np.float64],
        _basis_probabilities_from_bitmasks(
            program, _basis_masks_from_bitstrings(program, bitstrings, bit_order)
        ),
    )
    if return_log:
        # TODO: move logspace accumulation into the C++ amplitude walk so
        # very-rare-bitstring queries don't lose precision through the
        # linear->log conversion. Current path is symmetric with
        # record_probabilities() at the API surface but does not give the
        # precision benefit; that benefit only kicks in once the underlying
        # |amplitude|^2 sum is itself tracked in logspace.
        with np.errstate(divide="ignore"):
            return np.log(probs)
    return probs

Exact joint probabilities of measurement records under sample().

Requires at least one measurement. For a purely unitary program with no measurements, use :func:basis_probabilities instead.

records is one of: a single record string (e.g. "010"), a sequence of record strings, or a 2D bool / uint8 array of shape (num_records, program.num_measurements). Each record is interpreted in measurement order -- position i is the i-th entry sample().measurements would emit.

Records the program cannot emit are reported as 0.0 (or -inf when return_log=True). For deep circuits whose probabilities underflow float64, pass return_log=True so the log-domain values survive.

252
253
254
255
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

def record_probabilities(
    program: Program,
    records: MeasurementRecords,
    *,
    return_log: bool = False,
) -> npt.NDArray[np.float64]:
    """Exact joint probabilities of measurement records under ``sample()``.

    Requires at least one measurement. For a purely unitary program with no
    measurements, use :func:`basis_probabilities` instead.

    ``records`` is one of: a single record string (e.g. ``"010"``), a
    sequence of record strings, or a 2D ``bool`` / ``uint8`` array of
    shape ``(num_records, program.num_measurements)``. Each record is
    interpreted in measurement order -- position ``i`` is the i-th entry
    sample().measurements would emit.

    Records the program cannot emit are reported as ``0.0`` (or ``-inf``
    when ``return_log=True``). For deep circuits whose probabilities
    underflow float64, pass ``return_log=True`` so the log-domain values
    survive.
    """
    # Reject zero-measurement programs up front so a user who passes a real
    # record string against a unitary program gets the right hint rather
    # than the wrapper's record-length mismatch error.
    if program.num_measurements == 0:
        raise ValueError(
            "record_probabilities() requires a program with at least one "
            "measurement; use clifft.basis_probabilities() for unitary circuits."
        )
    record_array = _records_from_outcomes(program, records)
    log_probs = cast(
        npt.NDArray[np.float64],
        _record_probabilities_from_records(program, record_array),
    )
    # C++ marks unreachable records with the finite sentinel
    # numpy.finfo(float64).min (-DBL_MAX). Translate it back to the
    # Pythonic -inf for log output, and rely on the natural underflow
    # to 0.0 under np.exp for the linear case.
    if return_log:
        return np.where(log_probs == np.finfo(np.float64).min, -np.inf, log_probs)
    return np.exp(log_probs)

get_statevector(program: clifft._clifft_core.Program) -> numpy.ndarray[dtype=complex128, order='C']

Return a dense representative of a compiled pure-unitary program's final state.

The result is normalized and defined only up to global phase. Relative amplitudes and phases are preserved, but the global phase may vary across equivalent source circuits, compiler pass configurations, or Clifft versions.