quantum-study-utils 0.2.0__py3-none-any.whl

quantum_utils/measurements.py

@@ -0,0 +1,268 @@
+
+"""
+Quantum measurement utilities.
+
+Provides functions for calculating probabilities,
+analyzing measurement counts, and comparing results
+from quantum simulators and real quantum hardware.
+
+Compatible with standard Python, NumPy and Qiskit.
+"""
+
+from collections.abc import Mapping, Sequence
+
+import numpy as np
+
+
+def calculate_probabilities(
+    counts: Mapping[str, int],
+) -> dict[str, float]:
+    """
+    Calculate measurement probabilities from shot counts.
+
+    Args:
+        counts: Dictionary mapping bitstrings to shot counts.
+
+    Returns:
+        Dictionary mapping bitstrings to probabilities.
+    """
+    _validate_counts(counts)
+
+    total = sum(counts.values())
+
+    if total == 0:
+        return {}
+
+    return {
+        state: count / total
+        for state, count in sorted(counts.items())
+    }
+
+
+def calculate_state_probabilities(
+    statevector: Sequence[complex],
+) -> dict[str, float]:
+    """
+    Calculate theoretical probabilities from a statevector.
+
+    Uses the Born rule: P(i) = |amplitude_i|^2.
+
+    Args:
+        statevector: Quantum statevector amplitudes.
+
+    Returns:
+        Dictionary mapping computational basis states
+        to their theoretical probabilities.
+    """
+    if hasattr(statevector, "data"):
+        statevector = statevector.data
+
+    amplitudes = np.asarray(statevector, dtype=complex)
+
+    if amplitudes.ndim != 1:
+        raise ValueError("Statevector must be one-dimensional.")
+
+    dimension = len(amplitudes)
+
+    if dimension == 0 or dimension & (dimension - 1):
+        raise ValueError(
+            "Statevector length must be a power of two."
+        )
+
+    norm = np.sum(np.abs(amplitudes) ** 2)
+
+    if not np.isclose(norm, 1.0):
+        raise ValueError(
+            f"Statevector is not normalized: {norm:.6f}"
+        )
+
+    num_qubits = dimension.bit_length() - 1
+
+    probabilities = np.abs(amplitudes) ** 2
+
+    return {
+        format(i, f"0{max(1, num_qubits)}b"): float(p)
+        for i, p in enumerate(probabilities)
+    }
+
+
+def calculate_percentages(
+    counts: Mapping[str, int],
+) -> dict[str, float]:
+    """
+    Convert measurement counts into percentages.
+
+    Returns:
+        Dictionary mapping bitstrings to percentages.
+    """
+    probabilities = calculate_probabilities(counts)
+
+    return {
+        state: probability * 100
+        for state, probability in probabilities.items()
+    }
+
+
+def calculate_expectation_z(
+    counts: Mapping[str, int],
+    qubit: int = 0,
+) -> float:
+    """
+    Calculate the expectation value of Pauli-Z
+    for a measured qubit.
+
+    For Qiskit bitstrings, qubit 0 is the rightmost bit.
+
+    Args:
+        counts: Measurement counts.
+        qubit: Qubit index.
+
+    Returns:
+        Expectation value between -1 and +1.
+    """
+    probabilities = calculate_probabilities(counts)
+
+    if not probabilities:
+        raise ValueError("No measurement shots available.")
+
+    if qubit < 0:
+        raise ValueError("Qubit index must be non-negative.")
+
+    expectation = 0.0
+
+    for bitstring, probability in probabilities.items():
+
+        bits = bitstring.replace(" ", "")
+
+        if qubit >= len(bits):
+            raise ValueError("Qubit index out of range.")
+
+        bit = bits[-(qubit + 1)]
+
+        if bit not in ("0", "1"):
+            raise ValueError("Invalid measurement bitstring.")
+
+        eigenvalue = 1 if bit == "0" else -1
+
+        expectation += eigenvalue * probability
+
+    return expectation
+
+
+def compare_measurements(
+    simulator_counts: Mapping[str, int],
+    hardware_counts: Mapping[str, int],
+) -> dict[str, dict[str, float]]:
+    """
+    Compare simulator and real hardware measurements.
+
+    Args:
+        simulator_counts: Counts obtained from simulation.
+        hardware_counts: Counts obtained from hardware.
+
+    Returns:
+        Dictionary containing simulator probabilities,
+        hardware probabilities and absolute differences.
+    """
+    simulator = calculate_probabilities(simulator_counts)
+    hardware = calculate_probabilities(hardware_counts)
+
+    if not simulator or not hardware:
+        raise ValueError(
+            "Both datasets must contain measurement shots."
+        )
+
+    states = sorted(set(simulator) | set(hardware))
+
+    return {
+        state: {
+            "simulator": simulator.get(state, 0.0),
+            "hardware": hardware.get(state, 0.0),
+            "difference": abs(
+                simulator.get(state, 0.0)
+                - hardware.get(state, 0.0)
+            ),
+        }
+        for state in states
+    }
+
+
+def calculate_total_variation_distance(
+    counts_a: Mapping[str, int],
+    counts_b: Mapping[str, int],
+) -> float:
+    """
+    Calculate total variation distance between
+    two measurement distributions.
+
+    TVD = 1/2 * sum(|P(i) - Q(i)|)
+
+    Returns:
+        Value between 0 and 1.
+    """
+    comparison = compare_measurements(counts_a, counts_b)
+
+    return 0.5 * sum(
+        values["difference"]
+        for values in comparison.values()
+    )
+
+
+def measurement_summary(
+    counts: Mapping[str, int],
+) -> dict:
+    """
+    Generate a statistical summary of measurement results.
+
+    Returns:
+        Dictionary with shot counts, probabilities,
+        percentages and most frequent state.
+    """
+    probabilities = calculate_probabilities(counts)
+
+    total_shots = sum(counts.values())
+
+    if total_shots == 0:
+        return {
+            "total_shots": 0,
+            "unique_states": 0,
+            "most_frequent_state": None,
+            "probabilities": {},
+            "percentages": {},
+        }
+
+    return {
+        "total_shots": total_shots,
+        "unique_states": sum(
+            count > 0 for count in counts.values()
+        ),
+        "most_frequent_state": max(
+            counts, key=counts.get
+        ),
+        "probabilities": probabilities,
+        "percentages": calculate_percentages(counts),
+    }
+
+
+def _validate_counts(
+    counts: Mapping[str, int],
+) -> None:
+    """
+    Validate measurement count data.
+    """
+    for state, count in counts.items():
+
+        if not isinstance(state, str):
+            raise TypeError(
+                "Measurement states must be strings."
+            )
+
+        if not isinstance(count, (int, np.integer)):
+            raise TypeError(
+                "Measurement counts must be integers."
+            )
+
+        if count < 0:
+            raise ValueError(
+                "Measurement counts cannot be negative."
+            )

quantum_utils/visualization.py

@@ -0,0 +1,371 @@
+
+"""
+Visualization utilities for quantum computing.
+
+Visualize quantum states, probabilities, measurement
+counts, operators, and simulator/hardware comparisons.
+
+Compatible with Jupyter and standard Python.
+"""
+
+from collections.abc import Mapping, Sequence
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.figure import Figure
+
+from .measurements import (
+    calculate_probabilities,
+    calculate_state_probabilities,
+    compare_measurements,
+    calculate_total_variation_distance,
+)
+
+
+def _get_statevector(statevector) -> np.ndarray:
+    """Convert a statevector into a validated NumPy array."""
+    if hasattr(statevector, "data"):
+        statevector = statevector.data
+
+    array = np.asarray(statevector, dtype=complex)
+
+    if array.ndim != 1:
+        raise ValueError("Statevector must be one-dimensional.")
+
+    size = len(array)
+    if size == 0 or size & (size - 1):
+        raise ValueError("Statevector length must be a power of two.")
+
+    return array
+
+
+def _basis_labels(size: int) -> list[str]:
+    """Create computational basis labels."""
+    if size <= 0 or size & (size - 1):
+        raise ValueError("Dimension must be a power of two.")
+
+    num_qubits = max(1, size.bit_length() - 1)
+
+    return [
+        format(i, f"0{num_qubits}b")
+        for i in range(size)
+    ]
+
+
+def _finish(
+    fig: Figure,
+    show: bool,
+) -> Figure:
+    """Apply layout and optionally display a figure."""
+    fig.tight_layout()
+
+    if show:
+        plt.show()
+
+    return fig
+
+
+def display_data(
+    data,
+    label: str = "Quantum Data",
+    show: bool = True,
+) -> Figure:
+    """
+    Display a quantum vector or matrix with numeric values.
+
+    Args:
+        data: One-dimensional vector or two-dimensional matrix.
+        label: Figure title.
+        show: Whether to display the figure.
+
+    Returns:
+        Matplotlib Figure.
+    """
+    array = np.asarray(data, dtype=complex)
+
+    if array.ndim not in (1, 2):
+        raise ValueError("Data must be a vector or matrix.")
+
+    if array.size == 0:
+        raise ValueError("Data cannot be empty.")
+
+    matrix = array.reshape(-1, 1) if array.ndim == 1 else array
+
+    rows, cols = matrix.shape
+
+    fig, ax = plt.subplots(
+        figsize=(
+            max(5, min(cols * 1.2, 16)),
+            max(2.5, min(rows * 0.55 + 1, 18)),
+        )
+    )
+
+    ax.axis("off")
+
+    formatted = [
+        [
+            f"{value.real:.3f}"
+            if np.isclose(value.imag, 0)
+            else f"{value.real:.3f}{value.imag:+.3f}j"
+            for value in row
+        ]
+        for row in matrix
+    ]
+
+    table = ax.table(
+        cellText=formatted,
+        loc="center",
+        cellLoc="center",
+    )
+
+    table.auto_set_font_size(False)
+    table.set_fontsize(10)
+    table.scale(1, 1.5)
+
+    ax.set_title(label, pad=18)
+
+    return _finish(fig, show)
+
+
+def display_probabilities(
+    statevector: Sequence[complex],
+    label: str = "Theoretical Probabilities",
+    show: bool = True,
+) -> Figure:
+    """
+    Display theoretical probabilities using Born's rule.
+
+    Args:
+        statevector: Normalized quantum statevector.
+        label: Figure title.
+        show: Whether to display.
+
+    Returns:
+        Matplotlib Figure.
+    """
+    probabilities = calculate_state_probabilities(statevector)
+
+    states = list(probabilities)
+    values = [100 * p for p in probabilities.values()]
+
+    fig, ax = plt.subplots(figsize=(max(6, len(states) * 0.75), 4))
+
+    bars = ax.bar(states, values)
+
+    ax.set_title(label)
+    ax.set_xlabel("Computational basis state")
+    ax.set_ylabel("Probability (%)")
+    ax.set_ylim(0, max(5, max(values) * 1.2))
+
+    for bar, value in zip(bars, values):
+        ax.text(
+            bar.get_x() + bar.get_width() / 2,
+            bar.get_height(),
+            f"{value:.2f}%",
+            ha="center",
+            va="bottom",
+            fontsize=9,
+        )
+
+    return _finish(fig, show)
+
+
+def display_counts(
+    counts: Mapping[str, int],
+    label: str = "Measurement Results",
+    show: bool = True,
+) -> Figure:
+    """
+    Display quantum measurement counts.
+
+    Works with counts from both simulators and real hardware.
+
+    Args:
+        counts: Dictionary mapping bitstrings to shot counts.
+        label: Name of the simulator or quantum computer.
+        show: Whether to display.
+
+    Returns:
+        Matplotlib Figure.
+    """
+    probabilities = calculate_probabilities(counts)
+
+    if not probabilities:
+        raise ValueError("No measurement shots available.")
+
+    states = list(probabilities)
+    values = [100 * p for p in probabilities.values()]
+    total_shots = sum(counts.values())
+
+    fig, ax = plt.subplots(figsize=(max(6, len(states) * 0.75), 4))
+
+    bars = ax.bar(states, values)
+
+    ax.set_title(f"{label}\n{total_shots} shots")
+    ax.set_xlabel("Measured state")
+    ax.set_ylabel("Frequency (%)")
+    ax.set_ylim(0, max(5, max(values) * 1.2))
+
+    for bar, state, value in zip(bars, states, values):
+        ax.text(
+            bar.get_x() + bar.get_width() / 2,
+            bar.get_height(),
+            f"{counts[state]} ({value:.1f}%)",
+            ha="center",
+            va="bottom",
+            fontsize=9,
+        )
+
+    return _finish(fig, show)
+
+
+def compare_counts(
+    simulator_counts: Mapping[str, int],
+    hardware_counts: Mapping[str, int],
+    labels: tuple[str, str] = ("Simulator", "Hardware"),
+    show: bool = True,
+) -> Figure:
+    """
+    Compare simulator and hardware measurement distributions.
+
+    Args:
+        simulator_counts: Simulation results.
+        hardware_counts: Real hardware results.
+        labels: Names displayed in the legend.
+        show: Whether to display.
+
+    Returns:
+        Matplotlib Figure.
+    """
+    if len(labels) != 2:
+        raise ValueError("Exactly two labels are required.")
+
+    comparison = compare_measurements(
+        simulator_counts,
+        hardware_counts,
+    )
+
+    states = list(comparison)
+    simulator = [
+        comparison[s]["simulator"] * 100 for s in states
+    ]
+    hardware = [
+        comparison[s]["hardware"] * 100 for s in states
+    ]
+
+    x = np.arange(len(states))
+    width = 0.36
+
+    fig, ax = plt.subplots(
+        figsize=(max(7, len(states) * 0.9), 4.5)
+    )
+
+    ax.bar(
+        x - width / 2,
+        simulator,
+        width,
+        label=labels[0],
+    )
+    ax.bar(
+        x + width / 2,
+        hardware,
+        width,
+        label=labels[1],
+    )
+
+    tvd = calculate_total_variation_distance(
+        simulator_counts,
+        hardware_counts,
+    )
+
+    ax.set_title(
+        f"Quantum Measurement Comparison\n"
+        f"Total Variation Distance: {tvd:.4f}"
+    )
+
+    ax.set_xlabel("Measured state")
+    ax.set_ylabel("Frequency (%)")
+    ax.set_xticks(x, states)
+    ax.set_ylim(
+        0,
+        max(5, max(simulator + hardware) * 1.2),
+    )
+    ax.legend()
+
+    return _finish(fig, show)
+
+
+def display_operator_heatmap(
+    operator,
+    label: str = "Quantum Operator",
+    show: bool = True,
+) -> Figure:
+    """
+    Display the magnitude of a quantum operator matrix.
+
+    Args:
+        operator: Square matrix or compatible Qiskit Operator.
+        label: Figure title.
+        show: Whether to display.
+
+    Returns:
+        Matplotlib Figure.
+    """
+    if hasattr(operator, "data"):
+        operator = operator.data
+
+    matrix = np.asarray(operator, dtype=complex)
+
+    if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
+        raise ValueError("Operator must be a square matrix.")
+
+    size = matrix.shape[0]
+    states = _basis_labels(size)
+
+    magnitude = np.abs(matrix)
+
+    fig, ax = plt.subplots(
+        figsize=(max(5, size * 0.9), max(4, size * 0.8))
+    )
+
+    image = ax.imshow(
+        magnitude,
+        cmap="Blues",
+        vmin=0,
+        vmax=max(1, float(magnitude.max())),
+    )
+
+    ax.set_xticks(range(size), [f"|{s}⟩" for s in states])
+    ax.set_yticks(range(size), [f"|{s}⟩" for s in states])
+    ax.set_xlabel("Input state")
+    ax.set_ylabel("Output state")
+    ax.set_title(label)
+
+    for row in range(size):
+        for col in range(size):
+            value = matrix[row, col]
+
+            if not np.isclose(value, 0):
+                text = (
+                    f"{value.real:.2f}"
+                    if np.isclose(value.imag, 0)
+                    else f"{value.real:.2f}{value.imag:+.2f}j"
+                )
+
+                ax.text(
+                    col,
+                    row,
+                    text,
+                    ha="center",
+                    va="center",
+                    fontsize=9,
+                    color=(
+                        "white"
+                        if magnitude[row, col] > 0.65
+                        else "black"
+                    ),
+                )
+
+    fig.colorbar(image, ax=ax, label="Magnitude")
+
+    return _finish(fig, show)