SampledSelectionConfig¶
from cascaqit import SampledSelectionConfig
SampledSelectionConfig ¶
SampledSelectionConfig(
candidate_count: int = 3,
repeats_per_candidate: int = 3,
max_repeats_per_candidate: int | None = None,
shots_per_group: int | None = None,
confidence_level: float = 0.95,
max_backend_executions: int | None = None,
schema_version: str = SAMPLED_SELECTION_SCHEMA_VERSION,
)
Select a parameter point from sampled VQE optimization history using independent confirmation measurements. candidate_count must be at least 2 and bounds the number of distinct parameter bindings considered. Fewer bindings can produce fewer candidates; repeated bindings retain one source. Confirmation reduces selection bias from a single low energy estimate without guaranteeing the truly best parameters.
repeats_per_candidate must be at least 2. An omitted max_repeats_per_candidate, or a maximum equal to the initial count, uses fixed confirmation. A larger maximum enables sequential confirmation: add samples for uncertain candidates until confidence comparisons separate them, the repeat cap is reached or the backend budget is exhausted. Optional positive max_backend_executions limits confirmation and must cover the complete initial look for all actual candidates. An insufficient budget raises instead of comparing only a partially measured subset.
shots_per_group optionally overrides the optimization measurement budget and must be at least 2; otherwise it is inherited. Grouping, allocation and readout mitigation remain consistent. confidence_level must lie in (0, 1); sequential comparisons additionally use decision_confidence_level to adjust for repeated comparisons. Candidate intervals and decision intervals can differ, and confidence separation is not an unconditional optimality guarantee. Final computational-basis sampling is a separate later step outside this confirmation cost.
from cascaqit import PauliMeasurementConfig, SampledSelectionConfig
selection = SampledSelectionConfig(candidate_count=2, repeats_per_candidate=2,
max_repeats_per_candidate=4, shots_per_group=64)
measurement = selection.resolved_measurement(PauliMeasurementConfig(shots_per_group=32))
assert selection.mode == "sequential"
assert selection.planned_look_count == 5
assert selection.decision_confidence_level > selection.confidence_level
assert measurement.shots_per_group == 64
assert SampledSelectionConfig.from_json(selection.to_json()) == selection
Return fixed when the resolved maximum equals repeats_per_candidate, otherwise sequential. Explicitly supplying an equal maximum does not enable additional rounds.
Return the explicit maximum, or repeats_per_candidate when omitted. The limit applies to repeats for one candidate.
Return 1 in fixed mode or 1 + candidate_count * (maximum repeats - initial repeats) in sequential mode. This conservative bound is used for repeated-comparison adjustment, not as the observed round count.
Use confidence_level in fixed mode. Sequential mode divides alpha=1-confidence_level by planned_look_count times the number of candidate pairs, then returns 1-alpha. This is the Bonferroni-adjusted level for an individual decision, using the configured candidate count.
resolved_measurement ¶
resolved_measurement(
optimization_measurement: PauliMeasurementConfig,
) -> PauliMeasurementConfig
Return confirmation settings from an optimization PauliMeasurementConfig, overriding shots_per_group when requested and retaining grouping, allocation, pilot settings and mitigation. A reduced budget incompatible with the retained pilot raises. A non-PauliMeasurementConfig input raises TypeError.
Restore SampledSelectionConfig from a dictionary. Omitted fields use defaults; candidate counts, repeats, budgets and confidence levels are validated again. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.
Parse a JSON object and call from_dict(), returning SampledSelectionConfig. 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.