Result¶

The Result class holds the output of a quantum circuit execution — measurement counts, probabilities, and methods for analysis and visualization.

Overview¶

import quantsdk as qs

circuit = qs.Circuit(2).h(0).cx(0, 1).measure_all()
result = qs.run(circuit, shots=1000)

# Access data
result.counts          # {'00': 512, '11': 488}
result.probabilities   # {'00': 0.512, '11': 0.488}
result.most_likely     # '00'
result.top_k(1)        # [('00', 512)]

# Visualization
result.plot_histogram()          # matplotlib bar chart
df = result.to_pandas()          # pandas DataFrame
print(result.summary())          # formatted summary string

# Serialization
result.to_dict()                 # dict for JSON export

API Reference¶

Result `dataclass` ¶

Result(
    counts: dict[str, int],
    shots: int,
    backend: str = "local_simulator",
    job_id: str = "",
    metadata: dict[str, Any] = dict(),
)

Result of a quantum circuit execution.

Contains measurement counts, backend metadata, and convenience methods for analysis and visualization.

ATTRIBUTE	DESCRIPTION
`counts`	Dictionary mapping bitstring outcomes to their counts. TYPE: `dict[str, int]`
`shots`	Number of shots (measurement repetitions). TYPE: `int`
`backend`	Name of the backend that executed the circuit. TYPE: `str`
`job_id`	Unique identifier for the execution job. TYPE: `str`
`metadata`	Additional backend-specific metadata. TYPE: `dict[str, Any]`

Attributes¶

probabilities `property` ¶

probabilities: dict[str, float]

Measurement probabilities (counts normalized to sum = 1.0).

RETURNS	DESCRIPTION
`dict[str, float]`	Dictionary mapping bitstrings to their probability.

most_likely `property` ¶

most_likely: str

The most frequently measured bitstring.

RETURNS	DESCRIPTION
`str`	The bitstring with the highest count.

RAISES	DESCRIPTION
`ValueError`	If counts are empty.

num_qubits `property` ¶

num_qubits: int

Number of qubits (inferred from bitstring length).

Functions¶

get_probability ¶

get_probability(bitstring: str) -> float

Get the probability of a specific bitstring outcome.

PARAMETER	DESCRIPTION
`bitstring`	The measurement outcome to query. TYPE: `str`

RETURNS	DESCRIPTION
`float`	Probability as a float (0.0 if bitstring was not observed).

top_k ¶

top_k(k: int = 5) -> list[tuple[str, int, float]]

Get the top-k most frequent measurement outcomes.

PARAMETER	DESCRIPTION
`k`	Number of top results to return. TYPE: `int` DEFAULT: `5`

RETURNS	DESCRIPTION
`list[tuple[str, int, float]]`	List of (bitstring, count, probability) tuples, sorted by count descending.

expectation_value ¶

expectation_value() -> float

Compute the expectation value treating bitstrings as binary numbers.

RETURNS	DESCRIPTION
`float`	Weighted average of bitstring values (as integers).

to_dict ¶

to_dict() -> dict[str, Any]

Export result as a plain dictionary.

RETURNS	DESCRIPTION
`dict[str, Any]`	Dictionary containing all result data.

to_pandas ¶

to_pandas() -> Any

Export result as a pandas DataFrame.

Requires: pip install pandas

RETURNS	DESCRIPTION
`Any`	A `pandas.DataFrame` with columns: bitstring, count, probability.

Example::

result = qs.run(circuit, shots=1000)
df = result.to_pandas()
print(df.head())

plot_histogram ¶

plot_histogram(
    *,
    top_k: int | None = None,
    title: str | None = None,
    figsize: tuple[float, float] = (10, 5),
    color: str = "#4C72B0",
    show: bool = True,
) -> Any

Plot a histogram of measurement results.

Requires: pip install matplotlib

PARAMETER	DESCRIPTION
`top_k`	Show only the top-k most frequent outcomes. Default: all. TYPE: `int \| None` DEFAULT: `None`
`title`	Plot title. Default: "Measurement Results ({shots} shots)". TYPE: `str \| None` DEFAULT: `None`
`figsize`	Figure size as (width, height) in inches. TYPE: `tuple[float, float]` DEFAULT: `(10, 5)`
`color`	Bar color (any matplotlib color string). TYPE: `str` DEFAULT: `'#4C72B0'`
`show`	Whether to call `plt.show()`. Set False for programmatic use. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`Any`	A `matplotlib.figure.Figure` object.