uniqc.utils.result_adapter module

Result Adapter

Utility functions for converting and normalizing quantum measurement results.

class uniqc.utils.result_adapter.QASMResultAdapter(counts, shots=None, metadata=None)

Bases: object

Adapter for QASM Simulator results, converting raw output to a standardized analysis-ready format.

Takes a raw measurement counts dict from a QASM simulator and produces an AnalysisResult-compatible object containing counts, probabilities, and metadata.

The output can be passed directly to uniqc.visualization.result visualization functions.

Parameters:

• counts (dict[str, int]) – Raw measurement counts, e.g. {"00": 512, "11": 488}.

• shots (int | None) – Total number of shots. If not provided, inferred from counts.

• metadata (dict | None) – Optional metadata dict (e.g. simulator type, circuit info).

Variables:

• counts (Dict[str, int]) – Original measurement counts.

• probabilities (Dict[str, float]) – Normalized probability distribution.

• shots (int) – Total number of shots.

• metadata (dict) – Simulation metadata.

Example

>>> adapter = QASMResultAdapter(
...     counts={"00": 512, "11": 488},
...     metadata={"simulator": "simulator"},
... )
>>> adapter.probabilities
{'00': 0.512, '11': 0.488}
>>> adapter.shots
1000

to_dict()

Convert to a plain dict for serialization.

Returns:

dict with keys counts, probabilities, shots, metadata.

Return type:

dict

uniqc.utils.result_adapter.kv2list(kv_result, guessed_qubit_num)

Convert a key-value result dict to a flat list indexed by integer keys.

The list has length 2 ** guessed_qubit_num and is indexed by the integer representation of the measurement outcome.

Parameters:

• kv_result (dict) – Key-value result dict, e.g. {0: 0.1, 3: 0.9}. Keys must be integers.

• guessed_qubit_num (int) – Number of qubits, used to determine the output list length (2 ** guessed_qubit_num).

Returns:

Flat list where ret[k] holds the value for outcome k.

Return type:

list

uniqc.utils.result_adapter.list2kv(data)

Convert a measurement result list to a key-value frequency dict.

Parameters:

data (List[str]) – A list of measurement outcome strings, e.g. ['00', '01', '10', '00', '11', '00'].

Returns:

Frequency dict where keys are outcome strings and values are occurrence counts. Returns {} for empty input.

Return type:

Dict[str, int]

uniqc.utils.result_adapter.normalize_result(data)

Normalize measurement results to a probability distribution.

Accepts either a frequency dict or a raw list of outcome strings. List input is first converted via list2kv(). Returns a dict whose values sum to 1.0. Returns {} for empty input.

Parameters:

data (Union[Dict[str, int], List[str]]) – Measurement results as a frequency dict {'00': 3, '01': 1, ...} or a raw list ['00', '01', '10', ...].

Returns:

Probability distribution dict with values summing to 1.0.

Return type:

Dict[str, float]

uniqc.utils.result_adapter.shots2prob(measured_result, total_shots=None)

Convert a shot-counts dict to a probability distribution.

Parameters:

• measured_result (Dict[str, int]) – Measurement counts, e.g. {'00': 512, '11': 488}.

• total_shots (int, optional) – Total number of shots. If not provided, it is inferred by summing the values of measured_result.

Returns:

Probability dict where each count is divided by total_shots.

Return type:

Dict[str, float]