Metrics Utilities

Output Screening

Histogram-only screening for applications seeking one outstanding candidate.

compute_output_screen(counts, *, significance_level=None)

Report observed peak separation and an exact two-sided rank test.

Parameters:

• counts (Mapping[str, int]) – Complete measured counts on the application’s output register. Labels are opaque nonempty strings. Counts must be nonnegative integers, not probabilities, mitigated weights, or filtered top-k counts. Omitted unobserved outcomes have count zero. The caller must align/marginalize output registers before calling this function.

• significance_level (Optional[float]) – Optional per-histogram level strictly between zero and one. If omitted, rank_verified is None; the p-value is still returned. No contrast cutoff is applied.

Returns:

Counts, contrast, mass, ties, and rank evidence. A tie gives no unique candidate, zero contrast, and p-value one. With only one observed outcome the runner-up count is zero. P-values retain floating-point precision (extreme tails can underflow to zero).

Return type:

OutputScreeningSchema

Raises:

ValueError – If counts are empty, invalid, sum to zero, or the supplied significance level is invalid.

Notes

For top counts n1 >= n2, the p-value is min(1, 2 * P[Binomial(n1+n2, 1/2) >= n1]). This is the conservative nonrandomized form of the selected-winner test in Hung and Fithian, “Rank Verification for Exponential Families”, section 1.2, https://arxiv.org/abs/1610.03944. The TWO-sided comparison accounts for selecting the observed ranks under a fixed-shot IID multinomial model. It does not control repeated looks or tests across many jobs.

A verified rank does not imply a correct answer. A failed rank test does not establish uniformity or mean the output should be discarded. Several valid answers can yield low contrast. Use application-level verification after screening. No expected outcomes or ideal simulation enter this function. The count scan is linear in observed bins; only tied leading labels are sorted for deterministic serialization.

class OutputScreeningSchema(**data)

Observed peak separation and finite-shot rank evidence.

leading_outcome is absent when leaders tie; leading_outcomes lists all observed leaders without choosing one by bitstring order. A verified rank concerns the population mode under IID multinomial sampling, not application correctness. No significance level or acceptance rule is implicit.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_flat_dict()

Return fields for DataFrame creation, omitting unspecified values.

Return type:

Dict[str, Any]

Default Metrics

Default metric strategies for QWARD.

get_all_pre_runtime_strategies()

Get all pre-runtime metric strategy classes.

Returns:

List of all pre-runtime strategy classes

Return type:

List[Type[MetricCalculator]]

get_default_strategies()

Get the default list of metric strategies.

Note: FidelityMetrics (and legacy CircuitPerformanceMetrics) are not included in defaults since they require execution results (job or counts) and should be added manually when needed.

Returns:

List of default metric strategy classes

Return type:

List[Type[MetricCalculator]]

General Utilities (qward.utils)

flatten_dict(d, parent_key='', sep='.')

Recursively flattens a nested dictionary using dot notation for keys.

Parameters:

• d (Dict[str, Any]) – Dictionary to flatten

• parent_key (str) – Parent key for nested flattening

• sep (str) – Separator to use between keys

Return type:

Dict[str, Union[int, bool, str, list, Any]]

Returns:

Flattened dictionary with dot-notation keys

Example

{‘a’: {‘b’: 1}} -> {‘a.b’: 1}