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'.

Reference sampling removes stochastic and readout noise without checking determinism. Coherent error rotations remain; for these errors, supply expected parities from the intended ideal circuit instead.

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
352
353
354
355

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'.

    Reference sampling removes stochastic and readout noise without checking
    determinism. Coherent error rotations remain; for these errors, supply
    expected parities from the intended ideal circuit instead.

    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, postselection_mask: collections.abc.Sequence[int] = [], expected_detectors: collections.abc.Sequence[int] = [], expected_observables: collections.abc.Sequence[int] = [], normalize_syndromes: bool = False) -> 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. Optional postselection_mask, expected_detectors, expected_observables, and normalize_syndromes settings are recorded on the returned HirModule for HIR optimization passes and lower().

lower(hir: clifft._clifft_core.HirModule, postselection_mask: collections.abc.Sequence[int] | None = None, expected_detectors: collections.abc.Sequence[int] | None = None, expected_observables: collections.abc.Sequence[int] | None = None) -> 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; 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; 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
163

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,
        postselection_mask if postselection_mask is not None else [],
    )
    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
190

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,
        postselection_mask if postselection_mask is not None else [],
    )
    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.

193
194
195
196

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)))

Prepare and sample a circuit under a five-level leakage/loss model.

Equivalent to compile followed by NonComputationalProgram.sample. Each call repeats preparation; reuse a compiled program to amortize it. Existing positional arguments retain their meaning. Detailed final status is opt-in: add final_status=True when consuming that output.

On an inactive site, M/MX/MY and their reset variants sample the classifier independently of basis. A model capable of leakage/loss requires a classifier for physical measurements and does not support MPP. EXP_VAL is unsupported. Status probes append ordinary records without classifier heralds. Feedback consumes reported bits; detectors and observables retain raw parities without reference normalization.

Returns:

Raises:

540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582

def sample(
    circuit: Circuit | str,
    model: Model,
    shots: int,
    seed: int | None = None,
    max_active_width: int | None = None,
    threads: int | Literal["auto"] = 1,
    *,
    final_status: bool = False,
    execution: Literal["auto", "fixed", "trajectory"] = "auto",
    batch_size: int | Literal["auto"] = "auto",
    collect_stats: bool = False,
) -> NonComputationalSample:
    """Prepare and sample a circuit under a five-level leakage/loss model.

    Equivalent to [compile][clifft.noncomp.compile] followed by
    [NonComputationalProgram.sample][clifft.noncomp.NonComputationalProgram.sample].
    Each call repeats preparation; reuse a compiled program to amortize it.
    Existing positional arguments retain their meaning. Detailed final status
    is opt-in: add ``final_status=True`` when consuming that output.

    On an inactive site, M/MX/MY and their reset variants sample the classifier
    independently of basis. A model capable of leakage/loss requires a
    classifier for physical measurements and does not support MPP.
    EXP_VAL is unsupported. Status probes append ordinary records without
    classifier heralds. Feedback consumes reported bits; detectors and
    observables retain raw parities without reference normalization.

    Returns:
        Measurement, detector, observable, and herald arrays; optional detailed
        final status and statistics. Three-array unpacking remains supported.

    Raises:
        ValueError: For invalid circuit/model contracts, unsupported forced
            execution or batching, or an exceeded active-width cap.
    """
    return compile(
        circuit,
        model,
        final_status=final_status,
        execution=execution,
        max_active_width=max_active_width,
    ).sample(shots, seed, threads, batch_size=batch_size, collect_stats=collect_stats)

Prepare an owned sampling strategy without drawing shot randomness.

execution="auto" chooses a supported exact fixed plan when its width fits; otherwise it retains a validated trajectory request. "fixed" requires fixed execution and raises with the rejection reason before sampling. "trajectory" forces the general driver. Invalid circuit/model contracts always raise rather than triggering optimization fallback.

final_status=True requests the existing detailed QubitStatus values and can require trajectories when leaked labels remain unresolved. The default omits that output. This requirement is fixed at preparation.

max_active_width caps the fixed candidate or each compiled trajectory continuation. Under auto, an over-cap fixed candidate falls back; trajectory width errors can still arise when sampling. Initial states, spreading, classifiers, and partner channels outside the fixed subset use trajectories. The existing noncomputational measurement restrictions remain in force.

505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537

def compile(
    circuit: Circuit | str,
    model: Model,
    *,
    final_status: bool = False,
    execution: Literal["auto", "fixed", "trajectory"] = "auto",
    max_active_width: int | None = None,
) -> NonComputationalProgram:
    """Prepare an owned sampling strategy without drawing shot randomness.

    ``execution="auto"`` chooses a supported exact fixed plan when its width
    fits; otherwise it retains a validated trajectory request. ``"fixed"``
    requires fixed execution and raises with the rejection reason before
    sampling. ``"trajectory"`` forces the general driver. Invalid circuit/model
    contracts always raise rather than triggering optimization fallback.

    ``final_status=True`` requests the existing detailed QubitStatus values and
    can require trajectories when leaked labels remain unresolved. The default
    omits that output. This requirement is fixed at preparation.

    ``max_active_width`` caps the fixed candidate or each compiled trajectory
    continuation. Under auto, an over-cap fixed candidate falls back; trajectory
    width errors can still arise when sampling. Initial states, spreading,
    classifiers, and partner channels outside the fixed subset use trajectories.
    The existing noncomputational measurement restrictions remain in force.
    """
    if isinstance(circuit, str):
        circuit = _clifft_core.parse(circuit)
    return NonComputationalProgram(
        _clifft_core._compile_noncomputational(
            circuit, model._handle, final_status, execution, max_active_width
        )
    )

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