cirq.TensoredConfusionMatrices

Store and use confusion matrices for readout error mitigation on sets of qubits.

cirq.TensoredConfusionMatrices(
    confusion_matrices: Union[np.ndarray, Sequence[np.ndarray]],
    measure_qubits: Union[Sequence['cirq.Qid'], Sequence[Sequence['cirq.Qid']]],
    *,
    repetitions: int,
    timestamp: float
)

The confusion matrix (CM) for one qubit is:

[ Pr(0|0) Pr(1|0) ]
[ Pr(1|0) Pr(1|1) ]

where Pr(i | j) = Probability of observing state "i" given state "j" was prepared.

Similarly, the confusion matrix for two qubits is:

⎡ Pr(00|00) Pr(01|00) Pr(10|00) Pr(11|00) ⎤
⎢ Pr(00|01) Pr(01|01) Pr(10|01) Pr(11|01) ⎥
⎢ Pr(00|10) Pr(01|10) Pr(10|10) Pr(11|10) ⎥
⎣ Pr(00|11) Pr(01|11) Pr(10|11) Pr(11|11) ⎦

where Pr(ij | pq) = Probability of observing “ij” given state “pq” was prepared.

This class can be used to

  • Store a list of confusion matrices computed for a list of qubit patterns.
  • Build a single confusion / correction matrix for entire set of calibrated qubits using the smaller individual confusion matrices for specific qubit patterns.
  • Apply readout corrections to observed frequencies / output probabilities.

Use cirq.measure_confusion_matrix(sampler, qubits, repetitions) to perform an experiment on sampler and construct the cirq.TensoredConfusionMatrices object.

confusion_matrices Sequence of confusion matrices, computed for qubit patterns present in measure_qubits. A single confusion matrix is also accepted.
measure_qubits Sequence of smaller qubit patterns, for which the confusion matrices were computed. A single qubit pattern is also accepted. Note that the each qubit pattern is a sequence of qubits used to label the axes of the corresponding confusion matrix.
repetitions The number of repetitions that were used to estimate the confusion matrices.
timestamp The time the data was taken, in seconds since the epoch. This will be zero for fake data (i.e. data not generated from an experiment).

ValueError If length of confusion_matrices and measure_qubits is different or if the shape of any confusion matrix does not match the corresponding qubit pattern.

confusion_matrices List of confusion matrices corresponding to measure_qubits qubit pattern.
measure_qubits Calibrated qubit pattern for which individual confusion matrices were computed.
qubits Sorted list of all calibrated qubits.
repetitions The number of repetitions that were used to estimate the confusion matrices.
timestamp The time the data for confusion matrix estimation was taken, in seconds since epoch.

Methods

apply

View source

apply(
    result: np.ndarray,
    qubits: Optional[Sequence['cirq.Qid']] = None,
    *,
    method='least_squares'
) -> np.ndarray

Applies corrections to the observed result to compensate for readout error on qubits.

The compensation can applied by the following methods:

  1. 'pseudo_inverse': The result is multiplied by the correction matrix, which is pseudo inverse of confusion matrix corresponding to the subspace defined by qubits.
  2. 'least_squares': Solves a constrained minimization problem to find optimal x s.t. a) x >= 0 b) sum(x) == sum(result) and c) sum((result - x @ confusion_matrix) ** 2) is minimized.

Args
result (2 ** len(qubits), ) shaped numpy array containing observed frequencies / probabilities.
qubits Sequence of qubits used for sampling to get result. By default, uses all qubits in sorted order, i.e. self.qubits. Note that ordering of qubits sets the basis ordering for the result argument.
method Correction Method. Should be either 'pseudo_inverse' or 'least_squares'. Equal to least_squares by default.

Returns
(2 ** len(qubits), ) shaped numpy array corresponding to result with corrections.

Raises
ValueError If result.shape != (2 ** len(qubits),).
ValueError If least_squares constrained minimization problem does not converge.

confusion_matrix

View source

confusion_matrix(
    qubits: Optional[Sequence['cirq.Qid']] = None
) -> np.ndarray

Returns a single confusion matrix constructed for the given set of qubits.

The single 2 ** len(qubits) x 2 ** len(qubits) confusion matrix is constructed using the individual smaller self.confusion_matrices by applying necessary matrix transpose / kron / partial trace operations.

Args
qubits The qubits representing the subspace for which a confusion matrix should be constructed. By default, uses all qubits in sorted order, i.e. self.qubits. Note that ordering of qubits sets the basis ordering of the returned matrix.

Returns
Confusion matrix for subspace corresponding to qubits.

Raises
ValueError If qubits is not a subset of self.qubits.

correction_matrix

View source

correction_matrix(
    qubits: Optional[Sequence['cirq.Qid']] = None
) -> np.ndarray

Returns a single correction matrix constructed for the given set of qubits.

A correction matrix is the inverse of confusion matrix and can be used to apply corrections to observed frequencies / probabilities to compensate for the readout error. A Moore–Penrose Pseudo inverse of the confusion matrix is computed to get the correction matrix.

Args
qubits The qubits representing the subspace for which a correction matrix should be constructed. By default, uses all qubits in sorted order, i.e. self.qubits. Note that ordering of qubits sets the basis ordering of the returned matrix.

Returns
Correction matrix for subspace corresponding to qubits.

Raises
ValueError If qubits is not a subset of self.qubits.

from_measurement

View source

@classmethod
from_measurement(
    gate: cirq.MeasurementGate,
    qubits: Sequence['cirq.Qid']
) -> 'TensoredConfusionMatrices'

Generates TCM for the confusion map in a MeasurementGate.

This ignores any invert_mask defined for the gate - it only replicates the confusion map.

Args
gate the MeasurementGate to match.
qubits qubits the gate is applied to.

Returns
TensoredConfusionMatrices matching the confusion map of the given gate.

Raises
ValueError if the gate has no confusion map.

__eq__

View source

__eq__(
    other: Any
) -> bool

Return self==value.

__ne__

View source

__ne__(
    other: Any
) -> bool

Return self!=value.