PauliMeasurementConfig¶
from cascaqit import PauliMeasurementConfig
PauliMeasurementConfig ¶
PauliMeasurementConfig(
shots_per_group: int = 1024,
grouping: Literal[
"qubit_wise_commuting"
] = "qubit_wise_commuting",
allocation: Literal[
"uniform", "coefficient_l1", "pilot_variance"
] = "uniform",
pilot_shots_per_group: int | None = None,
mitigation: ReadoutMitigationConfig | None = None,
schema_version: str = MEASUREMENT_SCHEMA_VERSION,
)
Configure finite-shot Pauli energy estimates through the measurement argument of VQE.evaluate_sampled() or VQE.run(). Grouping is restricted to qubit_wise_commuting: nonidentity Pauli axes within a group are compatible on each qubit, so terms share a batch of rotated-basis measurements. Constructing the configuration does not sample.
shots_per_group must be an integer of at least 2. For a plan with G groups, one objective estimate has a total budget of G * shots_per_group. The constant does not add a measurement group. Identity Pauli terms follow the same grouping rules as other terms; an identity-only Hamiltonian still produces a group.
| allocation | Shot assignment |
|---|---|
| uniform | Every group receives exactly shots_per_group shots |
| coefficient_l1 | Divide the total budget by each group’s sum of absolute coefficients, with at least 2 shots per group |
| pilot_variance | Sample every group first, then distribute the remaining budget using observed group-energy variance; normally requires two backend executions per group |
Only pilot_variance accepts pilot_shots_per_group. At least 2 pilot shots and 2 additional shots must be available per group, requiring shots_per_group >= 4. An omitted pilot size follows resolved_pilot_shots_per_group. Both stages count toward the total budget; read actual group counts from the returned plan and allocation records.
Optional ReadoutMitigationConfig uses explicit calibration to estimate corrected energy and uncertainty while preserving raw counts.
from cascaqit import HamiltonianTerm, PauliHamiltonian, PauliMeasurementConfig, PauliX, PauliZ, VQE
hamiltonian = PauliHamiltonian("xz", (
HamiltonianTerm("x", 0.2, PauliX("q0")),
HamiltonianTerm("z", 0.8, PauliZ("q0")),
), logical_order=("q0",))
measurement = PauliMeasurementConfig(shots_per_group=32, allocation="coefficient_l1")
result = VQE(hamiltonian).evaluate_sampled((0.3, 0.1), measurement=measurement, seed=7)
assert len(result.plan.groups) == 2
assert result.total_shots == 64
assert sum(group.shots for group in result.group_results) == 64
assert result.group_results[0].shots != result.group_results[1].shots
Return the explicit integer pilot size or max(2, min(32, shots_per_group // 4)). Other allocation modes can read this value without acquiring a pilot stage. Construction separately checks that the pilot leaves enough budget for the second stage.
Restore PauliMeasurementConfig from a dictionary. Omitted fields use defaults. Nested mitigation settings are restored and validated. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.
Parse a JSON object and call from_dict(), returning PauliMeasurementConfig. Invalid JSON raises a parsing error; a non-object root raises TypeError.
Return a JSON-compatible dictionary, serializing nested objects and converting tuples to arrays. This stores the declaration, not an execution result.
Return a JSON string without writing a file. indent=None uses compact formatting; supply an indentation width for readable output.
Return the SHA-256 hex digest of canonical JSON. Fields, identifiers and metadata can affect it. Use it to compare saved content, not to decide physical equivalence.