Skip to content

reducers

Turn measurement counts into numbers.

A :class:Measurement reads chosen qubits from a counts dict and evaluates one arithmetic expression on them. :func:apply_measurements does that for every time point of a :class:~shadowsim.simulators.result.SimulationResult.

QUBIT_EXPECTATIONS module-attribute

QUBIT_EXPECTATIONS = 'qubit_expectations'

observable_kind metadata of a result with one Pauli expectation per qubit.

Measurement dataclass

One number per time point, computed from the shot counts of chosen qubits.

expression may use numbers, parentheses, unary + and -, + - * / **, shots, and counts["01"]. A counts key has one character per entry of qubits, in that order, so with qubits=(2, 0) counts["10"] is the number of shots where qubit 2 read 1 and qubit 0 read 0. A bitstring that was never observed is 0. shots is the total number of shots at that time point. Values are floats, so ** cannot build an unbounded integer.

The counts must come from a run in the basis this expression assumes. A Measurement does not change or check that basis.

An expectation backend has no counts. :func:apply_measurements then reads a one-qubit expression from that qubit's distribution: counts["0"] is (1 + expectation) / 2, counts["1"] is (1 - expectation) / 2, and shots is 1. Dividing by shots gives the infinite-shot value. An expression that uses raw counts without shots reads those probabilities.

Attributes:

  • qubits (tuple[int, ...]) –

    System qubit indexes, in the order a counts key lists them.

  • expression (str) –

    Arithmetic on counts and shots.

  • label (str) –

    Name of the resulting curve. Defaults to expression.

Examples:

Probability that qubits 0 and 1 agree:

from shadowsim.simulators import Measurement

same = Measurement((0, 1), '(counts["00"] + counts["11"]) / shots')
print(same.evaluate({"000": 6, "110": 2, "011": 2}))
0.8
Source code in shadowsim/simulators/reducers.py
@dataclass(frozen=True)
class Measurement:
    """One number per time point, computed from the shot counts of chosen qubits.

    ``expression`` may use numbers, parentheses, unary ``+`` and ``-``,
    ``+ - * / **``, ``shots``, and ``counts["01"]``. A ``counts`` key has one
    character per entry of ``qubits``, in that order, so with ``qubits=(2, 0)``
    ``counts["10"]`` is the number of shots where qubit 2 read 1 and qubit 0 read 0.
    A bitstring that was never observed is 0. ``shots`` is the total number of
    shots at that time point. Values are floats, so ``**`` cannot build an
    unbounded integer.

    The counts must come from a run in the basis this expression assumes. A
    Measurement does not change or check that basis.

    An expectation backend has no counts. :func:`apply_measurements` then reads
    a one-qubit expression from that qubit's distribution: ``counts["0"]`` is
    ``(1 + expectation) / 2``, ``counts["1"]`` is ``(1 - expectation) / 2``, and
    ``shots`` is 1. Dividing by ``shots`` gives the infinite-shot value. An
    expression that uses raw counts without ``shots`` reads those probabilities.

    Attributes:
        qubits: System qubit indexes, in the order a ``counts`` key lists them.
        expression: Arithmetic on ``counts`` and ``shots``.
        label: Name of the resulting curve. Defaults to ``expression``.

    Examples:
        Probability that qubits 0 and 1 agree:

        ```python exec="1" source="above" result="text"
        from shadowsim.simulators import Measurement

        same = Measurement((0, 1), '(counts["00"] + counts["11"]) / shots')
        print(same.evaluate({"000": 6, "110": 2, "011": 2}))
        ```
    """

    qubits: tuple[int, ...]
    expression: str
    label: str = ""
    _tree: ast.expr = field(init=False, repr=False, compare=False)

    def __post_init__(self) -> None:
        """Check ``qubits`` and parse ``expression``.

        Raises:
            ValueError: ``qubits`` is empty, repeats an index, or holds something
                other than non-negative integers, or ``expression`` is not allowed.
        """
        if isinstance(self.qubits, (str, bytes)) or not isinstance(self.qubits, Sequence):
            raise ValueError("qubits must be a non-empty list of qubit indexes")
        qubits = tuple(self.qubits)
        if not qubits:
            raise ValueError("qubits must be a non-empty list of qubit indexes")
        for qubit in qubits:
            if isinstance(qubit, bool) or not isinstance(qubit, int) or qubit < 0:
                raise ValueError("qubits must be non-negative integer indexes")
        if len(set(qubits)) != len(qubits):
            raise ValueError("qubits must not repeat an index")
        object.__setattr__(self, "qubits", qubits)
        object.__setattr__(self, "_tree", _parse(self.expression, len(qubits)))
        if not self.label:
            object.__setattr__(self, "label", self.expression.strip())

    def evaluate(self, counts: dict[str, int]) -> float:
        """Return this measurement on one time point's counts.

        Args:
            counts: Bitstring to shot count, where bit ``i`` of a key is system qubit ``i``.

        Raises:
            ValueError: A key is too short for ``qubits``, the expression divides
                by zero or overflows, or the result is not a finite real number.
        """
        last = max(self.qubits)
        marginal: dict[str, int] = {}
        for bitstring, shot_count in counts.items():
            if len(bitstring) <= last:
                raise ValueError(f"counts have {len(bitstring)} qubits, but this measurement reads qubit {last}")
            key = "".join(bitstring[qubit] for qubit in self.qubits)
            marginal[key] = marginal.get(key, 0) + shot_count
        try:
            value: object = _value(self._tree, marginal, sum(counts.values()))
        except ZeroDivisionError:
            raise ValueError(f"{self.label} divides by zero") from None
        except OverflowError:
            raise ValueError(f"{self.label} is too large") from None
        if not isinstance(value, float) or not math.isfinite(value):
            raise ValueError(f"{self.label} must be a finite real number")
        return value

__post_init__

__post_init__() -> None

Check qubits and parse expression.

Raises:

  • ValueError –

    qubits is empty, repeats an index, or holds something other than non-negative integers, or expression is not allowed.

Source code in shadowsim/simulators/reducers.py
def __post_init__(self) -> None:
    """Check ``qubits`` and parse ``expression``.

    Raises:
        ValueError: ``qubits`` is empty, repeats an index, or holds something
            other than non-negative integers, or ``expression`` is not allowed.
    """
    if isinstance(self.qubits, (str, bytes)) or not isinstance(self.qubits, Sequence):
        raise ValueError("qubits must be a non-empty list of qubit indexes")
    qubits = tuple(self.qubits)
    if not qubits:
        raise ValueError("qubits must be a non-empty list of qubit indexes")
    for qubit in qubits:
        if isinstance(qubit, bool) or not isinstance(qubit, int) or qubit < 0:
            raise ValueError("qubits must be non-negative integer indexes")
    if len(set(qubits)) != len(qubits):
        raise ValueError("qubits must not repeat an index")
    object.__setattr__(self, "qubits", qubits)
    object.__setattr__(self, "_tree", _parse(self.expression, len(qubits)))
    if not self.label:
        object.__setattr__(self, "label", self.expression.strip())

evaluate

evaluate(counts: dict[str, int]) -> float

Return this measurement on one time point's counts.

Parameters:

  • counts (dict[str, int]) –

    Bitstring to shot count, where bit i of a key is system qubit i.

Raises:

  • ValueError –

    A key is too short for qubits, the expression divides by zero or overflows, or the result is not a finite real number.

Source code in shadowsim/simulators/reducers.py
def evaluate(self, counts: dict[str, int]) -> float:
    """Return this measurement on one time point's counts.

    Args:
        counts: Bitstring to shot count, where bit ``i`` of a key is system qubit ``i``.

    Raises:
        ValueError: A key is too short for ``qubits``, the expression divides
            by zero or overflows, or the result is not a finite real number.
    """
    last = max(self.qubits)
    marginal: dict[str, int] = {}
    for bitstring, shot_count in counts.items():
        if len(bitstring) <= last:
            raise ValueError(f"counts have {len(bitstring)} qubits, but this measurement reads qubit {last}")
        key = "".join(bitstring[qubit] for qubit in self.qubits)
        marginal[key] = marginal.get(key, 0) + shot_count
    try:
        value: object = _value(self._tree, marginal, sum(counts.values()))
    except ZeroDivisionError:
        raise ValueError(f"{self.label} divides by zero") from None
    except OverflowError:
        raise ValueError(f"{self.label} is too large") from None
    if not isinstance(value, float) or not math.isfinite(value):
        raise ValueError(f"{self.label} must be a finite real number")
    return value

apply_measurements

apply_measurements(
    result: SimulationResult,
    measurements: Sequence[Measurement],
) -> SimulationResult

Return result with one curve per measurement in place of its observables.

Each curve has one value per entry of result.counts. The metadata gains measurements: the qubits, expression, and label of each one, in order.

Only a sampling backend, such as Aer, records counts. An expectation backend, such as PauliPropagation, returns one Pauli expectation per qubit instead (observable_kind is "qubit_expectations"). A one-qubit measurement is evaluated on that distribution: counts["0"] is (1 + expectation) / 2, counts["1"] is (1 - expectation) / 2, and shots is 1. Dividing by shots gives the infinite-shot value. An expression that uses raw counts without shots reads those probabilities. Two or more qubits need a sampling backend, because the result has no correlations between qubits.

Raises:

  • ValueError –

    measurements is empty, or a measurement cannot be evaluated on result.

Source code in shadowsim/simulators/reducers.py
def apply_measurements(result: SimulationResult, measurements: Sequence[Measurement]) -> SimulationResult:
    """Return ``result`` with one curve per measurement in place of its observables.

    Each curve has one value per entry of ``result.counts``. The metadata gains
    ``measurements``: the qubits, expression, and label of each one, in order.

    Only a sampling backend, such as Aer, records counts. An expectation backend,
    such as PauliPropagation, returns one Pauli expectation per qubit instead
    (``observable_kind`` is ``"qubit_expectations"``). A one-qubit measurement is
    evaluated on that distribution: ``counts["0"]`` is ``(1 + expectation) / 2``,
    ``counts["1"]`` is ``(1 - expectation) / 2``, and ``shots`` is 1. Dividing by
    ``shots`` gives the infinite-shot value. An expression that uses raw counts
    without ``shots`` reads those probabilities. Two or more qubits need a
    sampling backend, because the result has no correlations between qubits.

    Raises:
        ValueError: ``measurements`` is empty, or a measurement cannot be
            evaluated on ``result``.
    """
    if not measurements:
        raise ValueError("at least one measurement is required")
    if result.counts is None:
        curves = [_from_expectations(result, item) for item in measurements]
    else:
        curves = [
            np.array([item.evaluate(counts) for counts in result.counts], dtype=np.float64) for item in measurements
        ]
    recorded = [
        {"qubits": list(item.qubits), "expression": item.expression, "label": item.label} for item in measurements
    ]
    metadata = {key: value for key, value in result.metadata.items() if key != "observable_kind"}
    return replace(result, observables=curves, metadata={**metadata, "measurements": recorded})