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

quantum_utils/display/formatters.py

@@ -0,0 +1,197 @@
+"""
+Formatters for quantum states and numbers in LaTeX notation.
+
+Converts quantum objects into mathematically-formatted strings suitable
+for display in Jupyter notebooks and educational contexts.
+"""
+
+import numpy as np
+from typing import List, Tuple
+from ._utils import (
+    as_complex_array,
+    validate_qubit_count,
+    amplitude_is_near_zero,
+)
+
+
+class AcademicNumberFormatter:
+    """Format numbers using academic/analytic notation."""
+    
+    SQRT2_INV = 1.0 / np.sqrt(2)
+    EPSILON = 1e-10
+    
+    @staticmethod
+    def format(number: complex, precision: int = 3) -> str:
+        """
+        Format a real or complex number using analytic notation.
+        
+        Special handling for:
+        - ±1/√2: Uses LaTeX fraction notation
+        - Integers: No decimal places
+        - Pure imaginary: Shows 'i' notation
+        - Complex: Shows full form
+        
+        Args:
+            number: Number to format (converted to complex)
+            precision: Decimal precision for non-special values
+            
+        Returns:
+            LaTeX-formatted string representation
+            
+        Example:
+            >>> fmt = AcademicNumberFormatter()
+            >>> fmt.format(1/np.sqrt(2))
+            '\\frac{1}{\\sqrt{2}}'
+            >>> fmt.format(1+2j)
+            '(1.000+2.000i)'
+        """
+        number = complex(number)
+        
+        # Handle purely real numbers
+        if np.isclose(number.imag, 0, atol=AcademicNumberFormatter.EPSILON):
+            real = number.real
+            
+            # Check for ±1/√2
+            if np.isclose(abs(real), AcademicNumberFormatter.SQRT2_INV):
+                return (
+                    r"\frac{1}{\sqrt{2}}" if real > 0 
+                    else r"-\frac{1}{\sqrt{2}}"
+                )
+            
+            # Check for integers
+            if np.isclose(real, round(real)):
+                return str(int(round(real)))
+            
+            # Decimal approximation
+            return f"{real:.{precision}g}"
+        
+        # Handle purely imaginary numbers
+        if np.isclose(number.real, 0, atol=AcademicNumberFormatter.EPSILON):
+            return f"{number.imag:.{precision}g}i"
+        
+        # Handle full complex numbers
+        sign = "+" if number.imag >= 0 else "-"
+        return f"({number.real:.{precision}g}{sign}{abs(number.imag):.{precision}g}i)"
+
+
+class DiracExpressionGenerator:
+    """Convert statevectors into Dirac notation (ket) expressions."""
+    
+    @staticmethod
+    def generate(statevector) -> str:
+        """
+        Convert a statevector into a sum of computational basis kets.
+        
+        Filters out near-zero amplitudes and formats non-zero terms using
+        academic number notation. Terms are concatenated with appropriate
+        signs.
+        
+        Args:
+            statevector: Statevector or Qiskit Statevector object
+            
+        Returns:
+            Dirac notation expression as string
+            
+        Raises:
+            ValueError: If not a 1D vector
+            
+        Example:
+            >>> sv = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)])
+            >>> gen = DiracExpressionGenerator()
+            >>> gen.generate(sv)
+            '\\frac{1}{\\sqrt{2}}|00\\rangle + \\frac{1}{\\sqrt{2}}|11\\rangle'
+        """
+        vector = as_complex_array(statevector)
+        
+        if vector.ndim != 1:
+            raise ValueError(
+                f"Expected 1D statevector, got {vector.ndim}D array"
+            )
+        
+        n_qubits = validate_qubit_count(len(vector))
+        terms: List[str] = []
+        formatter = AcademicNumberFormatter()
+        
+        for index, amplitude in enumerate(vector):
+            # Skip near-zero amplitudes
+            if amplitude_is_near_zero(amplitude):
+                continue
+            
+            # Format basis state
+            ket = rf"|{index:0{n_qubits}b}\rangle"
+            
+            # Handle special amplitude cases
+            if np.isclose(amplitude, 1):
+                term = ket
+            elif np.isclose(amplitude, -1):
+                term = f"-{ket}"
+            else:
+                term = f"{formatter.format(amplitude)}{ket}"
+            
+            terms.append(term)
+        
+        if not terms:
+            return "0"
+        
+        # Join terms with proper signs
+        expression = " + ".join(terms)
+        # Replace leading "+ -" with "-"
+        expression = expression.replace(" + -", " - ")
+        
+        return expression
+
+
+class LatexMatrixFormatter:
+    """Format matrices in LaTeX matrix notation."""
+    
+    @staticmethod
+    def format_vector(vector: np.ndarray) -> str:
+        """
+        Format a 1D vector in LaTeX matrix notation.
+        
+        Args:
+            vector: 1D numpy array
+            
+        Returns:
+            LaTeX bmatrix string
+        """
+        formatter = AcademicNumberFormatter()
+        rows = r" \\ ".join(formatter.format(elem) for elem in vector)
+        return rf"\begin{{bmatrix}} {rows} \end{{bmatrix}}"
+    
+    @staticmethod
+    def format_matrix(matrix: np.ndarray) -> str:
+        """
+        Format a 2D matrix in LaTeX matrix notation.
+        
+        Args:
+            matrix: 2D numpy array
+            
+        Returns:
+            LaTeX bmatrix string
+        """
+        formatter = AcademicNumberFormatter()
+        rows = r" \\ ".join(
+            " & ".join(formatter.format(elem) for elem in row)
+            for row in matrix
+        )
+        return rf"\begin{{bmatrix}} {rows} \end{{bmatrix}}"
+    
+    @staticmethod
+    def format_full_statevector(statevector) -> Tuple[str, str]:
+        """
+        Format a statevector as both Dirac notation and column vector.
+        
+        Args:
+            statevector: Input statevector
+            
+        Returns:
+            Tuple of (dirac_expression, matrix_string)
+        """
+        vector = as_complex_array(statevector)
+        validate_qubit_count(len(vector))
+        
+        dirac = DiracExpressionGenerator.generate(vector)
+        matrix = LatexMatrixFormatter.format_vector(vector)
+        
+        return dirac, matrix

quantum_utils/display/templates.py

@@ -0,0 +1,225 @@
+"""
+HTML templates for display components.
+
+Centralizes HTML markup to improve maintainability and enable theme customization.
+"""
+
+import html
+from typing import Dict, List
+from dataclasses import dataclass
+
+
+@dataclass
+class HTMLTheme:
+    """Configuration for HTML display styling."""
+    
+    # Data display box
+    data_border_color: str = "#4A90E2"
+    data_padding: str = "12px"
+    
+    # Bar chart styling
+    bar_height: str = "13px"
+    bar_color: str = "#8866b1"
+    bar_bg_color: str = "#e9e9e9"
+    bar_border_radius: str = "5px"
+    
+    # Container styling
+    container_border_color: str = "#ddd"
+    container_padding: str = "14px"
+    container_border_radius: str = "7px"
+    
+    # Text styling
+    label_font_weight: str = "bold"
+    unit_font_size: str = "12px"
+    unit_color: str = "#666"
+    
+    # Heatmap sizing
+    heatmap_min_size: int = 4
+
+
+class HTMLBuilder:
+    """Helper class for building HTML strings safely with escaping."""
+    
+    @staticmethod
+    def safe_text(text: str) -> str:
+        """Escape HTML special characters."""
+        return html.escape(str(text))
+    
+    @staticmethod
+    def div(content: str, style: str = "", **attrs) -> str:
+        """Create a div element with optional styling."""
+        attr_str = "".join(f' {k}="{HTMLBuilder.safe_text(str(v))}"' 
+                          for k, v in attrs.items() if v is not None)
+        style_attr = f' style="{style}"' if style else ""
+        return f"<div{style_attr}{attr_str}>{content}</div>"
+    
+    @staticmethod
+    def code(text: str) -> str:
+        """Create a code element with safe escaping."""
+        return f"<code>{HTMLBuilder.safe_text(text)}</code>"
+
+
+class RawDataTemplate:
+    """Template for displaying raw numpy arrays."""
+    
+    @staticmethod
+    def render(name: str, array_string: str, 
+               theme: HTMLTheme = None) -> str:
+        """
+        Render raw array data with label.
+        
+        Args:
+            name: Variable name or label
+            array_string: String representation of array (already escaped)
+            theme: HTMLTheme configuration
+            
+        Returns:
+            HTML string
+        """
+        if theme is None:
+            theme = HTMLTheme()
+        
+        style = (
+            f"padding:{theme.data_padding};"
+            f"border-left:4px solid {theme.data_border_color};"
+        )
+        
+        content = (
+            f"<b>{HTMLBuilder.safe_text(name)}</b> "
+            f"<code>{array_string}</code>"
+        )
+        
+        return HTMLBuilder.div(content, style=style)
+
+
+class BarChartTemplate:
+    """Template for displaying bar charts as HTML."""
+    
+    @staticmethod
+    def render_bar(state: str, value: float, width_percent: float,
+                   theme: HTMLTheme = None) -> str:
+        """
+        Render a single bar in the chart.
+        
+        Args:
+            state: State label (e.g., '|0⟩')
+            value: Numeric value to display
+            width_percent: Bar width as percentage (0-100)
+            theme: HTMLTheme configuration
+            
+        Returns:
+            HTML string for single bar
+        """
+        if theme is None:
+            theme = HTMLTheme()
+        
+        width_percent = max(0.0, min(100.0, width_percent))
+        
+        bar_style = (
+            f"width:{width_percent:.4f}%;"
+            f"height:{theme.bar_height};"
+            f"background:{theme.bar_color};"
+        )
+        
+        container_style = (
+            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 = HTMLBuilder.div("", style=bar_style)
+        container_html = HTMLBuilder.div(bar_html, style=container_style)
+        
+        value_style = "min-width:95px;text-align:right;"
+        value_html = HTMLBuilder.div(
+            f"{value:.2f}",
+            style=value_style
+        )
+        
+        state_html = HTMLBuilder.div(
+            HTMLBuilder.code(f"|{state}⟩"),
+            style="width:55px;"
+        )
+        
+        row_content = state_html + container_html + value_html
+        
+        return HTMLBuilder.div(row_content, style=row_style)
+    
+    @staticmethod
+    def render_chart(data: Dict[str, float], label: str, 
+                    suffix: str = "", unit: str = "",
+                    theme: HTMLTheme = None) -> str:
+        """
+        Render complete bar chart.
+        
+        Args:
+            data: Dict mapping state labels to values
+            label: Chart title/label
+            suffix: Suffix for values (e.g., '%')
+            unit: Unit description
+            theme: HTMLTheme configuration
+            
+        Returns:
+            HTML string for complete chart
+        """
+        if theme is None:
+            theme = HTMLTheme()
+        
+        bars = []
+        for state in sorted(data.keys()):
+            value = data[state]
+            # Display value with suffix
+            display_value = value if not suffix else value  # suffix shown separately
+            bar_width = max(0.0, min(100.0, value))
+            
+            bar_html = BarChartTemplate.render_bar(
+                state, display_value, bar_width, theme
+            )
+            bars.append(bar_html)
+        
+        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};">'
+            f"{HTMLBuilder.safe_text(unit)}</div>"
+            if unit else ""
+        )
+        
+        bars_html = "".join(bars)
+        content = label_html + unit_html + bars_html
+        
+        return HTMLBuilder.div(content, style=container_style)
+
+
+class NormalizationNoticeTemplate:
+    """Template for normalization status notice."""
+    
+    @staticmethod
+    def render(norm_squared: float) -> str:
+        """
+        Render normalization status.
+        
+        Args:
+            norm_squared: ⟨ψ|ψ⟩ value
+            
+        Returns:
+            HTML string
+        """
+        return (
+            f'<small>Normalized state: ⟨ψ|ψ⟩ = {norm_squared:.4f}</small>'
+        )

quantum_utils/formatting.py

@@ -0,0 +1,136 @@
+
+"""
+Formatting utilities for quantum states and measurement results.
+
+Provides text-based representations for quantum statevectors
+and measurement counts.
+
+Compatible with NumPy, Qiskit Statevector and standard Python.
+"""
+
+from collections.abc import Mapping
+from typing import Sequence
+
+import numpy as np
+
+
+def format_statevector(
+    statevector: Sequence[complex],
+    precision: int = 4,
+    threshold: float = 1e-10,
+) -> str:
+    """
+    Format a quantum statevector using computational basis notation.
+
+    Args:
+        statevector:
+            Sequence of complex amplitudes or Qiskit Statevector.
+        precision:
+            Number of decimal places.
+        threshold:
+            Minimum amplitude magnitude to display.
+
+    Returns:
+        Formatted string representation.
+    """
+
+    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."
+        )
+
+    if precision < 0:
+        raise ValueError("Precision must be non-negative.")
+
+    if threshold < 0:
+        raise ValueError("Threshold must be non-negative.")
+
+    num_qubits = max(1, dimension.bit_length() - 1)
+
+    results = []
+
+    for index, amplitude in enumerate(amplitudes):
+
+        if abs(amplitude) <= threshold:
+            continue
+
+        bitstring = format(index, f"0{num_qubits}b")
+
+        real = float(amplitude.real)
+        imag = float(amplitude.imag)
+
+        if abs(imag) <= threshold:
+            formatted = f"{real:.{precision}f}"
+
+        elif abs(real) <= threshold:
+            formatted = f"{imag:.{precision}f}j"
+
+        else:
+            sign = "+" if imag >= 0 else "-"
+            formatted = (
+                f"{real:.{precision}f}"
+                f"{sign}"
+                f"{abs(imag):.{precision}f}j"
+            )
+
+        results.append(
+            f"|{bitstring}⟩: {formatted}"
+        )
+
+    return "\n".join(results) if results else "Zero statevector"
+
+
+def format_measurement_results(
+    counts: Mapping[str, int],
+    precision: int = 2,
+) -> str:
+    """
+    Format quantum measurement counts and percentages.
+
+    Args:
+        counts:
+            Mapping of measured bitstrings to shot counts.
+        precision:
+            Decimal places for percentages.
+
+    Returns:
+        Formatted measurement summary.
+    """
+
+    if not counts:
+        return "No measurements available."
+
+    if any(count < 0 for count in counts.values()):
+        raise ValueError(
+            "Measurement counts cannot be negative."
+        )
+
+    total_shots = sum(counts.values())
+
+    if total_shots == 0:
+        return "No measurement shots recorded."
+
+    results = []
+
+    for bitstring in sorted(counts):
+
+        count = counts[bitstring]
+        percentage = 100 * count / total_shots
+
+        results.append(
+            f"|{bitstring}⟩: "
+            f"{count} "
+            f"({percentage:.{precision}f}%)"
+        )
+
+    return "\n".join(results)