qat.runtime.post_processing module

Runtime post-processing utilities.

This module provides helpers to map raw IQ readout arrays into processed forms expected by higher-level code. It implements the supported legacy PostProcessType operations (mean, linear map, discriminate), plus the granular post-processing pipeline functions (apply_equalise(), apply_discriminate_instruction(), apply_post_select()) and small helpers for axis bookkeeping.

For a full description of the granular pipeline and how each step fits together, see the Readout Post-Processing guide.

The legacy LINEAR_MAP_COMPLEX_TO_REAL path is preserved unchanged for backward compatibility.

apply_discriminate_instruction(response, instr, axes)

Runtime implementation of qat.ir.measure.Discriminate.

Discriminate equalised values to integer state keys using a Discriminate instruction.

For the threshold path (instr.threshold is not None) values above the threshold map to 0 and values at or below map to 1.

For the ML path (instr.method is set) normalised Gaussian likelihoods are computed using a single global noise_est; the state with the highest likelihood wins and its dict key (the integer from MaxLikelihoodMethod.states) is returned directly. Likelihoods are computed in log-domain with log-sum-exp stabilisation to avoid underflow. When p_min > 0, shots below the minimum confidence threshold are assigned BG_KEY.

Parameters:

  • response (ndarray) – Equalised (real or complex) readout array.

  • instr (Discriminate) – The Discriminate instruction.

  • axes (dict[ProcessAxis, int]) – Current axis map.

Return type:

tuple[ndarray, dict[ProcessAxis, int]]

Returns:

Integer state-key array and unchanged axis map.

apply_equalise(response, instr, axes)

Runtime implementation of qat.ir.measure.Equalise.

Applies the affine [I', Q'] = A @ [I, Q] + b transform to the complex readout array and returns the result as a complex array I' + j Q'.

Parameters:

  • response (ndarray) – Complex IQ readout array (arbitrary batch shape).

  • instr (Equalise) – The Equalise instruction carrying transform and offset.

  • axes (dict[ProcessAxis, int]) – Current axis map.

Return type:

tuple[ndarray, dict[ProcessAxis, int]]

Returns:

Complex-valued transformed data and unchanged axis map.

Raises:

ValueError – If instr.transform is not shape (2, 2) or instr.offset is not shape (2,).

apply_post_processing(response, post_processing, axes)

Applies software post processing to the results.

Uses the information in the PostProcessing instruction to determine what method to apply.

Parameters:

  • response (ndarray) – Readout results from an execution engine.

  • post_processing (PostProcessing) – The post processing instruction.

  • axes (dict[ProcessAxis, int]) – A dictionary containing which axes contain the shots and which contain time series.

Return type:

tuple[ndarray, dict[ProcessAxis, int]]

Returns:

The processed results as an array and the axis map.

apply_post_select(state_keys, instr, axes)

Runtime implementation of qat.ir.measure.PostSelect.

Build a per-shot validity mask from a PostSelect instruction.

A shot is marked False (invalid) when either:

  • Its integer state key is negative — negative keys encode disallowed states and the p_min background sentinel (BG_KEY), or

  • Its integer state key appears in additional_disallowed — used by the pre-selection pass to reject specific non-negative states without re-keying the Discriminate method.

Parameters:

  • state_keys (ndarray) – Integer state-key array produced by a Discriminate step.

  • instr (PostSelect) – The PostSelect instruction.

  • axes (dict[ProcessAxis, int]) – Current axis map (not used; present for interface consistency).

Return type:

tuple[ndarray, ndarray]

Returns:

A tuple of (state_keys, validity_mask) where validity_mask is a boolean ndarray with the same shape as state_keys.

discriminate(response, axes, threshold)

Discriminates a real value to a classical bit by comparison to a supplied discrimination threshold.

Parameters:

  • response (np.ndarray) – Readout results from an execution engine.

  • axes (dict[ProcessAxis, Int]) – A dictionary containing which axes contain the shots and which contain time series.

  • threshold (float) – The supplied discrimination threshold.

Returns:

The processed results as an array and the axis map.

get_axis_map(mode, response)

Given the acquisition mode, determine what each axis corresponds to.

The way the results are returned are defined by the acquisition mode: this could be averaged over shots, averaged over time, or neither. We must determine how to unpack the results.

Parameters:

  • mode (AcquireMode) – The acquisition mode.

  • response (ndarray) – The response returned by the target machine.

Return type:

dict[ProcessAxis, int]

Returns:

A dictionary containing the axis index for each type of ProcessAxis.

linear_map_complex_to_real(response, axes, multiplier, constant)

Maps complex values onto a real z-projection using a provided linear mapping.

Parameters:

  • response (np.ndarray) – Readout results from an execution engine.

  • axes (dict[ProcessAxis, Int]) – A dictionary containing which axes contain the shots and which contain time series.

  • multiplier (numbers.Number) – Coeffecient for the linear map.

  • constant (numbers.Number) – Constant for the linear map.

Returns:

The processed results as an array and the axis map.

mean(response, axes, target_axes)

Calculates the mean over the given axes.

Parameters:

  • response (ndarray) – Readout results from an execution engine.

  • axes (dict[ProcessAxis, int]) – A dictionary containing which axes contain the shots and which contain time series.

  • target_axes (ProcessAxis | list[ProcessAxis]) – Which axis or axes should the mean be done over?

Returns:

The processed results as an array and the axis map.