qat.runtime.passes.transform module

Runtime transform passes for result formatting and post-processing.

This module contains transform passes that operate on acquired results and the executable package to shape, post-process and format results returned by the runtime. Passes are implemented as subclasses of TransformPass and are composed by the runtime pipeline.

class AcquisitionPostprocessing(target_data=None)

Bases: TransformPass

Uses the post-processing instructions from the executable package to process the results from the engine.

The target machine will return the results in a format that depends on the specified AcquireMode. However, it is often the case results need to be returned in an explicit format, e.g., as discriminated bits. To achieve this, extra software post-processing is needed.

The post-processing that appears here is the same as the post-processing responsibilities taken on by the QuantumExecutionEngine in qat.purr.compiler.execution.

Parameters:

target_data (Optional[TargetData]) – The target data is needed to know the sample time of the acquired results.

run(acquisitions, res_mgr=None, *args, package, **kwargs)
Parameters:

  • acquisitions (dict[str, Any]) – The dictionary of results acquired from the target machine.

  • res_mgr (Optional[ResultManager]) – The results manager used to record post-selection metadata and granular pipeline intermediate outputs.

  • package (Executable) – The executable program containing the results-processing information should be passed as a keyword argument.

class AssignResultsTransform

Bases: TransformPass

Processes Assign instructions.

As assigns are classical instructions they are not processed as a part of the quantum execution (right now). Read through the results dictionary and perform the assigns directly, return the results.

Extracted from purr.compiler.execution.QuantumExecutionEngine._process_assigns.

run(acquisitions, *args, package, **kwargs)
Parameters:

  • acquisitions (dict[str, Any]) – The dictionary of results acquired from the target machine.

  • package (Executable) – The executable program containing the results-processing information should be passed as a keyword argument.

class ErrorMitigation(hardware_model)

Bases: TransformPass

Applies readout error mitigation to the results.

Extracted from qat.purr.compiler.runtime.QuantumRuntime._apply_error_mitigation().

Parameters:

hardware_model (QuantumHardwareModel | PhysicalHardwareModel) – The hardware model contains the error mitigation properties.

run(acquisitions, res_mgr, *args, compiler_config, **kwargs)
Parameters:

  • acquisitions (dict[str, Any]) – The dictionary of results acquired from the target machine.

  • res_mgr (ResultManager) – The results manager is needed to look up the qubit-to-variable mapping.

  • compiler_config (CompilerConfig) – The compiler config is needed to know how to apply error mitigaiton, and should be provided as a keyword argument.

class InlineResultsProcessingTransform

Bases: TransformPass

Uses InlineResultsProcessing instructions from the executable package to format the acquired results in the desired format.

Legacy vs granular acquires

All acquires that go through measure_with_granular_post_processing() now produce granular Equalise → Discriminate instructions and appear in DiscriminateResult. Discriminate emits integer state keys directly. This includes qubits with LinearMapToRealMethod, MaxLikelihoodMethod, and legacy mean_z_map_args qubits. Pre-selection acquires (presel_*) use a shorter chain (Equalise → Discriminate → PostSelect) and are for internal runtime use only — they drive the validity mask but are never returned to the user.

Per-variable routing

Routing decisions are made per output variable (by looking up the variable in DiscriminateResult.outputs) rather than with a single execution-wide flag. This correctly handles executables that mix legacy and granular acquires.

``numpy_array_to_list`` is skipped for granular variables so ResultTransform can access the numpy arrays when routing QuantumResultsFormat results.

``binary_average`` (triggered by InlineResultsProcessing.Binary/Program) is suppressed for granular variables when a top-level QuantumResultsFormat (binary() or raw()) is active — ResultTransform owns routing in that case and needs the raw per-shot int array from Discriminate. For all other cases (no top-level format, or binary_count(), or legacy acquires) binary_average runs as before.

run(acquisitions, res_mgr=None, *args, package, compiler_config=None, **kwargs)
Parameters:

  • acquisitions (dict[str, Any]) – The dictionary of results acquired from the target machine.

  • res_mgr (Optional[ResultManager]) – Optional results manager; used to detect granular pipeline usage.

  • package (Executable) – The executable program containing the results-processing information should be passed as a keyword argument.

  • compiler_config (Optional[CompilerConfig]) – Optional compiler configuration; when provided, a top-level QuantumResultsFormat requesting per-shot output (binary() or raw()) suppresses the per-acquire binary_average reduction for granular acquires so that ResultTransform can handle routing.

class QBloxAcquisitionPostProcessing

Bases: TransformPass

Post-process QBlox acquisition playback into output arrays.

This pass operates on the combined QBlox playback structure, extracts scope or integrator data, applies any requested post-processing steps and shapes the results according to the acquisition definitions in the executable package.

run(playback, res_mgr=None, *args, package, **kwargs)

Now that the combined playback is ready, we can compute and process results as required by customers.

This requires loop nest information as well as post-processing and array shaping requirements.

Parameters:

  • playback (dict[str, dict[str, Acquisition]]) – The combined QBlox playback structure.

  • res_mgr (Optional[ResultManager]) – The results manager used to record post-selection metadata.

  • package (Executable) – The executable program containing the results-processing information should be passed as a keyword argument.

class ResultTransform

Bases: TransformPass

Transform the raw results into the format that we’ve been asked to provide.

This pass applies ResultsFormatting flags (BinaryCount, SquashBinaryResultArrays, DynamicStructureReturn) to shape final results.

Granular pipeline routing

When the granular post-processing pipeline (Equalise → Discriminate → PostSelect) has been used for end-of-circuit measurements, intermediate outputs are stored as EqualiseResult and DiscriminateResult in res_mgr. ResultTransform reads these to implement the requested format:

  • ``raw()``: Returns the complex IQ arrays from EqualiseResult (post-mask). For legacy acquires without an Equalise step, falls back to the mapped float arrays.

  • ``binary()``: Returns the per-shot integer state-key arrays from Discriminate (i.e. acquisitions as-is — one int per retained shot).

  • ``binary_count()``: Uses integer keys from DiscriminateResult to build a {label: count} dict that correctly handles multi-state classifiers.

For legacy acquires (no DiscriminateResult present) all three modes fall back to the existing binary_count / binary_average logic, with shots_retained used as the denominator when post-selection is active.

Extracted from qat.purr.compiler.runtime.QuantumRuntime._transform_results().

run(acquisitions, res_mgr=None, *args, compiler_config, package, **kwargs)
Parameters:

  • acquisitions (dict[str, Any]) – The dictionary of results acquired from the target machine.

  • res_mgr (Optional[ResultManager]) – The results manager is used to look up granular pipeline intermediates and post-selection metadata.

  • compiler_config (CompilerConfig) – The compiler config is needed to know how to process the results, and should be provided as a keyword argument.