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

quantum_utils/display/_utils.py

@@ -0,0 +1,137 @@
+"""
+Internal utilities for display module.
+
+Provides helper functions for variable introspection, type conversions,
+and statevector validation.
+"""
+
+import inspect
+from typing import Any, Tuple
+import numpy as np
+
+
+def get_variable_name(value: Any, fallback: str = "Result") -> str:
+    """
+    Extract the variable name of a value from the calling scope.
+    
+    This function introspects the call stack to find the original variable name
+    that was passed to the function. Useful for display functions to auto-label output.
+    
+    Args:
+        value: The value whose variable name should be found
+        fallback: Default name if variable name cannot be determined
+        
+    Returns:
+        The variable name as a string, or fallback if not found
+        
+    Example:
+        >>> my_variable = [1, 2, 3]
+        >>> name = get_variable_name(my_variable)
+        >>> name
+        'my_variable'
+    """
+    frame = inspect.currentframe()
+    try:
+        # Go back 2 frames: get_variable_name -> caller -> original context
+        caller_frame = frame.f_back.f_back
+        if caller_frame is None:
+            return fallback
+        
+        # Search for matching object in local scope
+        for name, candidate in caller_frame.f_locals.items():
+            if candidate is value and not name.startswith('_'):
+                return name
+        return fallback
+    finally:
+        # Prevent reference cycles
+        del frame
+
+
+def as_complex_array(value: Any) -> np.ndarray:
+    """
+    Convert a value to a complex numpy array.
+    
+    Handles Qiskit Statevector objects and numpy arrays transparently.
+    
+    Args:
+        value: Value to convert (array-like or object with .data attribute)
+        
+    Returns:
+        Complex numpy array
+        
+    Raises:
+        TypeError: If value cannot be converted to array
+    """
+    # Handle Qiskit Statevector and similar objects with .data attribute
+    data = getattr(value, "data", value)
+    return np.asarray(data, dtype=complex)
+
+
+def validate_qubit_count(size: int) -> int:
+    """
+    Validate statevector size and return qubit count.
+    
+    A statevector for n qubits must have length 2^n. This function validates
+    this constraint and returns the number of qubits.
+    
+    Args:
+        size: Length of statevector
+        
+    Returns:
+        Number of qubits
+        
+    Raises:
+        ValueError: If size is not a power of 2 or less than 2
+        
+    Example:
+        >>> validate_qubit_count(4)  # 2^2 = 4
+        2
+        >>> validate_qubit_count(3)
+        Traceback (most recent call last):
+            ...
+        ValueError: Statevector length must be a power of two (at least 2).
+    """
+    if size < 2 or (size & (size - 1)):  # Check if power of 2
+        raise ValueError(
+            f"Statevector length must be a power of two (at least 2). Got {size}."
+        )
+    # bit_length() - 1 gives log2(size)
+    return size.bit_length() - 1
+
+
+def normalize_statevector(statevector: np.ndarray) -> Tuple[np.ndarray, float]:
+    """
+    Normalize a statevector and return norm squared.
+    
+    Args:
+        statevector: Input statevector (1D array)
+        
+    Returns:
+        Tuple of (normalized vector, norm_squared)
+        
+    Raises:
+        ValueError: If statevector has norm close to zero
+    """
+    if statevector.ndim != 1:
+        raise ValueError(f"Expected 1D array, got {statevector.ndim}D")
+    
+    norm_sq = float(np.vdot(statevector, statevector).real)
+    
+    if np.isclose(norm_sq, 0):
+        raise ValueError(f"Statevector has zero norm: {norm_sq}")
+    
+    return statevector / np.sqrt(norm_sq), norm_sq
+
+
+def amplitude_is_near_zero(amplitude: complex, threshold: float = 1e-10) -> bool:
+    """
+    Check if an amplitude is effectively zero.
+    
+    Args:
+        amplitude: Complex amplitude to check
+        threshold: Magnitude threshold below which amplitude is considered zero
+        
+    Returns:
+        True if amplitude magnitude is below threshold
+    """
+    return np.abs(amplitude) < threshold

quantum_utils/display/display.py

@@ -0,0 +1,388 @@
+"""
+High-level display functions for quantum objects.
+
+These are the main user-facing functions for displaying:
+- Quantum states and amplitudes
+- Probability distributions
+- Measurement counts
+- Quantum operators
+"""
+
+import numpy as np
+from typing import Dict, Optional, Union
+from IPython.display import HTML, display, Math
+
+from ._utils import (
+    get_variable_name,
+    as_complex_array,
+    validate_qubit_count,
+    normalize_statevector,
+    amplitude_is_near_zero,
+)
+from .formatters import (
+    AcademicNumberFormatter,
+    DiracExpressionGenerator,
+    LatexMatrixFormatter,
+)
+from .templates import (
+    HTMLTheme,
+    RawDataTemplate,
+    BarChartTemplate,
+    NormalizationNoticeTemplate,
+)
+
+
+def display_data(
+    value: Union[np.ndarray, object],
+    label: Optional[str] = None,
+    theme: Optional[HTMLTheme] = None
+) -> None:
+    """
+    Display raw quantum data with LaTeX mathematical representation.
+    
+    Shows both:
+    1. Raw numpy array (with HTML formatting)
+    2. Mathematical notation:
+       - For vectors: Dirac notation + matrix form
+       - For matrices: Matrix form only
+    
+    Automatically detects variable name if label not provided.
+    
+    Args:
+        value: Statevector (1D) or operator (2D) array, or Qiskit object
+        label: Display label (auto-detected from variable name if None)
+        theme: HTMLTheme for styling (uses default if None)
+        
+    Raises:
+        ValueError: If not a 1D vector or 2D square matrix
+        
+    Example:
+        >>> psi = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)])
+        >>> display_data(psi)  # Shows as "psi"
+        >>> display_data(psi, label="Bell state")
+    """
+    if theme is None:
+        theme = HTMLTheme()
+    
+    name = label or get_variable_name(value, fallback="Result")
+    array = as_complex_array(value)
+    
+    # Escape and format raw array
+    raw_str = np.array2string(array).replace('\n', '<br>')
+    raw_html = RawDataTemplate.render(name, raw_str, theme)
+    display(HTML(raw_html))
+    
+    # Display mathematical representation
+    if array.ndim == 1:
+        # Validate statevector
+        validate_qubit_count(len(array))
+        
+        # Generate Dirac expression and matrix form
+        dirac, matrix = LatexMatrixFormatter.format_full_statevector(array)
+        latex_expr = rf"|\psi\rangle = {dirac} = {matrix}"
+        
+    elif array.ndim == 2:
+        # Format matrix
+        matrix = LatexMatrixFormatter.format_matrix(array)
+        latex_expr = matrix
+        
+    else:
+        raise ValueError(
+            f"Only 1D vectors or 2D matrices supported, got {array.ndim}D"
+        )
+    
+    display(Math(latex_expr))
+
+
+def display_probabilities(
+    statevector: Union[np.ndarray, object],
+    label: str = "Theoretical probabilities",
+    theme: Optional[HTMLTheme] = None
+) -> np.ndarray:
+    """
+    Display computational-basis probabilities of a normalized pure state.
+    
+    Computes |amplitude|² for each basis state and displays as bar chart.
+    Validates normalization (⟨ψ|ψ⟩ = 1.0).
+    
+    Args:
+        statevector: Input statevector (must be normalized)
+        label: Chart title
+        theme: HTMLTheme for styling
+        
+    Returns:
+        Probability array (same as |amplitude|²)
+        
+    Raises:
+        ValueError: If not a 1D vector or not normalized
+        
+    Example:
+        >>> psi = np.array([0.6, 0.8])
+        >>> probs = display_probabilities(psi)
+        >>> print(probs)  # [0.36, 0.64]
+    """
+    if theme is None:
+        theme = HTMLTheme()
+    
+    vector = as_complex_array(statevector)
+    
+    if vector.ndim != 1:
+        raise ValueError(
+            f"Probabilities require 1D statevector, got {vector.ndim}D"
+        )
+    
+    n_qubits = validate_qubit_count(len(vector))
+    
+    # Validate normalization
+    norm_sq = float(np.vdot(vector, vector).real)
+    if not np.isclose(norm_sq, 1.0):
+        raise ValueError(
+            f"Statevector is not normalized: ⟨ψ|ψ⟩ = {norm_sq:.6f}"
+        )
+    
+    # Compute probabilities
+    probabilities = np.abs(vector) ** 2
+    
+    # Prepare data for bar chart
+    data = {
+        f'{i:0{n_qubits}b}': float(prob * 100)
+        for i, prob in enumerate(probabilities)
+    }
+    
+    # Render bar chart
+    html_chart = BarChartTemplate.render_chart(
+        data, label, suffix="%", unit="Probability", theme=theme
+    )
+    display(HTML(html_chart))
+    
+    # Show normalization status
+    norm_notice = NormalizationNoticeTemplate.render(norm_sq)
+    display(HTML(norm_notice))
+    
+    return probabilities
+
+
+def display_counts(
+    counts: Dict[str, int],
+    label: str = "Quantum simulator",
+    theme: Optional[HTMLTheme] = None
+) -> Dict[str, float]:
+    """
+    Display shot counts from quantum simulator or real hardware.
+    
+    Converts raw counts (number of measurement outcomes) into percentages
+    and displays as bar chart.
+    
+    Args:
+        counts: Dictionary mapping bitstrings to shot counts
+        label: Chart title (e.g., "Aer simulator", "IBM Fez")
+        theme: HTMLTheme for styling
+        
+    Returns:
+        Normalized probability distribution (counts / total_shots)
+        
+    Raises:
+        ValueError: If counts dict is empty or has non-positive total
+        
+    Example:
+        >>> counts = {'00': 512, '11': 512}
+        >>> probs = display_counts(counts, label="Aer simulator")
+        >>> print(probs)  # {'00': 0.5, '11': 0.5}
+    """
+    if theme is None:
+        theme = HTMLTheme()
+    
+    if not counts:
+        raise ValueError("Counts dictionary cannot be empty")
+    
+    total_shots = sum(counts.values())
+    if total_shots <= 0:
+        raise ValueError(f"Total shots must be positive, got {total_shots}")
+    
+    # Prepare data: convert counts to percentages
+    data = {
+        bitstring: (count / total_shots) * 100
+        for bitstring, count in counts.items()
+    }
+    
+    # Build custom unit string with shot count
+    unit_str = f"{total_shots} shots"
+    
+    # Render bar chart with custom formatting for shot counts
+    html_chart = BarChartTemplate.render_chart(
+        data, label, suffix="", unit=unit_str, theme=theme
+    )
+    
+    # Post-process to add actual counts next to percentages
+    # This is a workaround to show both count and percentage
+    html_chart_lines = []
+    for bitstring in sorted(counts.keys()):
+        count = counts[bitstring]
+        percentage = (count / total_shots) * 100
+        
+        bar_width = min(100.0, percentage)
+        bar_line = BarChartTemplate.render_bar(
+            bitstring, count, bar_width, theme
+        )
+        
+        # Modify to show "count (percentage%)" format
+        bar_line = bar_line.replace(
+            f">{count:.2f}<",
+            f">{count} ({percentage:.1f}%)<"
+        )
+        html_chart_lines.append(bar_line)
+    
+    # Reconstruct chart with modified bars
+    chart_html_base = BarChartTemplate.render_chart(
+        data, label, unit=unit_str, theme=theme
+    )
+    
+    # Simpler approach: render one by one
+    from .templates import HTMLBuilder
+    
+    container_style = (
+        f"max-width:550px;"
+        f"padding:{theme.container_padding};"
+        f"border:1px solid {theme.container_border_color};"
+        f"border-radius:{theme.container_border_radius};"
+    )
+    
+    label_html = f"<b>{HTMLBuilder.safe_text(label)}</b>"
+    unit_html = (
+        f'<div style="font-size:{theme.unit_font_size};'
+        f'color:{theme.unit_color};">{unit_str}</div>'
+    )
+    
+    bars = []
+    for bitstring in sorted(counts.keys()):
+        count = counts[bitstring]
+        percentage = (count / total_shots) * 100
+        bar_width = min(100.0, percentage)
+        
+        bar_style = (
+            f"width:{bar_width:.4f}%;"
+            f"height:{theme.bar_height};"
+            f"background:{theme.bar_color};"
+        )
+        
+        container_style_bar = (
+            f"flex:1;"
+            f"background:{theme.bar_bg_color};"
+            f"border-radius:{theme.bar_border_radius};"
+            f"overflow:hidden;"
+        )
+        
+        row_style = (
+            "display:flex;"
+            "align-items:center;"
+            "gap:10px;"
+            "margin:7px 0;"
+        )
+        
+        bar_html = f'<div style="{bar_style}"></div>'
+        container_bar_html = f'<div style="{container_style_bar}">{bar_html}</div>'
+        value_html = f'<div style="min-width:130px;text-align:right;">{count} ({percentage:.1f}%)</div>'
+        state_html = f'<div style="width:55px;"><code>|{HTMLBuilder.safe_text(bitstring)}⟩</code></div>'
+        
+        row_html = f'<div style="{row_style}">{state_html}{container_bar_html}{value_html}</div>'
+        bars.append(row_html)
+    
+    full_html = (
+        f'<div style="{container_style}">'
+        f'{label_html}{unit_html}{"".join(bars)}'
+        f'</div>'
+    )
+    
+    display(HTML(full_html))
+    
+    # Return normalized distribution
+    return {bitstring: count / total_shots for bitstring, count in counts.items()}
+
+
+def display_operator_heatmap(
+    operator: Union[np.ndarray, object],
+    label: str = "Quantum operator",
+    theme: Optional[HTMLTheme] = None
+):
+    """
+    Display quantum operator as heatmap with annotated elements.
+    
+    Creates a matplotlib heatmap showing:
+    - Color intensity proportional to element magnitude |⟨i|U|j⟩|
+    - Annotations showing decimal approximations
+    - Basis state labels on axes
+    
+    Args:
+        operator: Square matrix representing quantum operator
+        label: Plot title
+        theme: HTMLTheme configuration (for sizing hints)
+        
+    Returns:
+        matplotlib figure object
+        
+    Raises:
+        ValueError: If not a square 2D matrix
+        ImportError: If matplotlib or seaborn not installed
+        
+    Example:
+        >>> pauli_x = np.array([[0, 1], [1, 0]])
+        >>> fig = display_operator_heatmap(pauli_x, label="Pauli X")
+    """
+    try:
+        import matplotlib.pyplot as plt
+        import seaborn as sns
+    except ImportError as e:
+        raise ImportError(
+            "display_operator_heatmap requires matplotlib and seaborn"
+        ) from e
+    
+    if theme is None:
+        theme = HTMLTheme()
+    
+    matrix = as_complex_array(operator)
+    
+    if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
+        raise ValueError(
+            f"Operator must be square 2D matrix, "
+            f"got shape {matrix.shape}"
+        )
+    
+    n_qubits = validate_qubit_count(matrix.shape[0])
+    
+    # Create basis state labels
+    states = [f'|{i:0{n_qubits}b}⟩' for i in range(matrix.shape[0])]
+    
+    # Prepare annotations: show magnitude in decimal form, omit near-zero elements
+    annotations = np.array([
+        ["" if np.isclose(x, 0) else f"{x:.2g}" for x in row]
+        for row in matrix
+    ])
+    
+    # Compute figure size (at least theme minimum)
+    size = max(theme.heatmap_min_size, matrix.shape[0] * 1.1)
+    
+    fig, ax = plt.subplots(figsize=(size, size))
+    
+    # Plot heatmap
+    sns.heatmap(
+        np.abs(matrix),
+        annot=annotations,
+        fmt="",
+        cmap="Blues",
+        cbar=False,
+        square=True,
+        xticklabels=states,
+        yticklabels=states,
+        linewidths=1,
+        linecolor="white",
+        ax=ax,
+    )
+    
+    # Move x-axis labels to top
+    ax.xaxis.tick_top()
+    ax.set_title(label, pad=22)
+    
+    plt.tight_layout()
+    plt.show()
+    
+    return fig