ObservableMeasuringMixin

class ObservableMeasuringMixin(*args, grouping_strategy=<object object>, shot_distribution=None, **kwargs)[source]

Bases: object

Mixin adding measurement-stage configuration to a quantum program.

Mix in alongside QuantumProgram (the mixin must come first so its cooperative super().__init__() resolves to the program base) — for example:

class MyProgram(ObservableMeasuringMixin, QuantumProgram):
    ...

The mixin stores the two measurement-stage knobs verbatim. Runtime shape-aware decisions — including the auto-flip from "qwc" to the internal "_backend_expval" strategy when the backend supports analytic expvals and every MetaCircuit carries a single observable — live inside MeasurementStage.

Initialize the measurement-config layer.

Parameters:

  • grouping_strategy (Literal['wires', 'default', 'qwc', '_backend_expval'] | None) – Strategy for partitioning Hamiltonian terms into compatible measurement groups; one circuit is executed per group. Options: "qwc" (qubit-wise- commuting — most compact, default), "wires" (group by support wires), or None (one circuit per term). MeasurementStage may further auto-flip "qwc" to its internal "_backend_expval" mode at runtime when the backend supports analytic expvals and the batch is single- observable; "_backend_expval" is not user-passable.

  • shot_distribution (Literal['uniform', 'weighted', 'weighted_random'] | Callable[[list[float], int], list[int]] | None) –

    Focus the backend’s shot budget on the Hamiltonian terms that matter most. Without this option, every measurement group is sampled with the backend’s full shot count, even tiny terms with little impact on the final energy. With shot_distribution set, the same total budget is split across groups according to their importance — reducing variance without spending more shots.

    Available strategies:

    • "uniform" — equal split across groups.

    • "weighted" — proportional to per-group coefficient L1 norm; dominant Hamiltonian terms get more shots.

    • "weighted_random" — multinomial sample of the same probabilities; may drop more low-weight groups than the deterministic "weighted" for the same budget.

    • A callable (group_l1_norms, total_shots) -> per_group_shots for fully custom allocation.

    Defaults to None (every group receives the full shot budget).

  • *args – Forwarded to the next class in the MRO (typically QuantumProgram).

  • **kwargs – Forwarded to the next class in the MRO (typically QuantumProgram).