Python API Reference¶

Compile a quantum circuit string to executable bytecode.

Runs the full pipeline: parse -> trace -> [HIR optimize] -> lower -> [bytecode optimize].

By default both optimization stages run with their default pass managers. To skip optimization, pass hir_passes=None and/or bytecode_passes=None. To use a custom pipeline, pass an explicit HirPassManager / BytecodePassManager.

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:

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
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374

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,
    bytecode_passes: BytecodePassManager | None | _DefaultPasses = _DEFAULT_PASSES,
) -> Program:
    """Compile a quantum circuit string to executable bytecode.

    Runs the full pipeline: parse -> trace -> [HIR optimize] ->
    lower -> [bytecode optimize].

    By default both optimization stages run with their default pass
    managers. To skip optimization, pass ``hir_passes=None`` and/or
    ``bytecode_passes=None``. To use a custom pipeline, pass an
    explicit ``HirPassManager`` / ``BytecodePassManager``.

    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 in .stim text 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.
        bytecode_passes: BytecodePassManager to run after lowering.
            Defaults to ``default_bytecode_pass_manager()``. Pass ``None`` to skip.
    """
    if isinstance(hir_passes, _DefaultPasses):
        hir_passes = default_hir_pass_manager()
    if isinstance(bytecode_passes, _DefaultPasses):
        bytecode_passes = default_bytecode_pass_manager()
    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,
        bytecode_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.

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

Trace a parsed circuit through the Clifford front-end to produce the Heisenberg IR.

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 executable VM bytecode.

To optimize the bytecode, use a BytecodePassManager after lowering: prog = clifft.lower(hir) bpm = clifft.default_bytecode_pass_manager() bpm.run(prog)

Parameters:

sample(program: clifft._clifft_core.Program, shots: int, seed: int | None = None) -> object

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.

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

sample_survivors(program: clifft._clifft_core.Program, shots: int, seed: int | None = None, keep_records: bool = False) -> object

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

If seed is None (default), uses hardware entropy.

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: clifft._clifft_core.Program, shots: int, k: int, seed: int | None = None) -> object

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.

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

sample_k_survivors(program: clifft._clifft_core.Program, shots: int, k: int, seed: int | None = None, keep_records: bool = False) -> object

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.

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

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.

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

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.

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
311
312
313
314

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)

execute(program: clifft._clifft_core.Program, state: clifft._clifft_core.State) -> None

Execute a compiled program, updating the state in-place.

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

Expand the SVM state into a dense statevector.

For unitary programs, compilation preserves the API-visible global phase across optimization passes. Retained final-tableau expansion uses Stim's complex unitary path, so those amplitudes have float-scale precision. After measurements or noise, only relative amplitudes and probabilities are meaningful; overall phase may differ between compilations.

default_hir_pass_manager() -> clifft._clifft_core.HirPassManager

Return an HirPassManager pre-loaded with the default passes.

default_bytecode_pass_manager() -> clifft._clifft_core.BytecodePassManager

Return a BytecodePassManager pre-loaded with the default passes.

get_num_threads() -> int

Return the current maximum number of OpenMP threads.

Threading only activates for circuits with peak rank >= 18 (statevector >= 4 MB).

Returns 1 if Clifft was built without OpenMP support.

set_num_threads(num_threads: int) -> None

Set the number of OpenMP threads for multi-core statevector operations.

Threading only activates for circuits with peak rank >= 18 (statevector >= 4 MB). Pure Clifford and low-T-count circuits run single-threaded regardless of this setting.

When using multiprocessing (e.g. sinter), set num_threads=1 in each worker to avoid oversubscription.

Has no effect if Clifft was built without OpenMP support.

svm_backend() -> str

Return the active SVM dispatch backend.

Reflects the resolved runtime kernel path or the CLIFFT_FORCE_ISA environment override. In normal operation returns one of 'avx512', 'avx2', or 'scalar' ('scalar' names the generic/base SVM path).

If CLIFFT_FORCE_ISA names an ISA the host CPU cannot execute, or is set to an unrecognized value, the backend instead reports one of 'trap:avx512', 'trap:avx2', or 'trap:unknown'. The next execute() call throws RuntimeError with a message naming the missing features or accepted values.

version() -> str

Return the Clifft version string

compute_reference_syndrome(hir: clifft._clifft_core.HirModule) -> dict

Compute noiseless reference syndrome for an HirModule.

Returns a dict with 'detectors' and 'observables' lists.