Quantum Study Utils

A robust Python library for visualization, analysis, and formatting of quantum computing data. Perfect for academic purposes, research, and education.

Documentation in: English | Português

---

✨ Features

• Quantum Data Visualization - Interactive displays with customizable themes
• Academic Formatting - LaTeX notation for mathematical expressions
• Dirac Notation - Automatic quantum state conversion
• Multiple Themes - Light, dark, professional, and neon themes
• Operator Heatmaps - Visualization of quantum operator matrices
• ✅ 100% Compatible - Fully backward compatible with previous version

---

Installation

Local Installation (Development)

# Clone the repository
git clone https://github.com/wellington/comp-quantica.git
cd quantum-study-utils

# Install in editable mode (development)
pip install -e ".[dev]"

Installation in Jupyter Notebook

Once the module is installed correctly, import it in your notebook:

import quantum_utils
from quantum_utils import (
 display_data,
 display_probabilities,
 display_counts,
 display_operator_heatmap,
 AcademicNumberFormatter,
 DiracExpressionGenerator,
 HTMLTheme,
)

---

Quick Start Guide

1️⃣ Import and Configure Themes

import numpy as np
from quantum_utils import display_data, HTMLTheme

# Define themes (once, at the beginning)
DARK_THEME = HTMLTheme.DARK
LIGHT_THEME = HTMLTheme.LIGHT
PROFESSIONAL_THEME = HTMLTheme.PROFESSIONAL
NEON_THEME = HTMLTheme.NEON

2️⃣ Visualize Quantum States

# Bell state: |Φ+⟩ = (1/√2)(|00⟩ + |11⟩)
bell_state = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)])

display_data(bell_state, label="Bell State |Φ+⟩", theme=LIGHT_THEME)

3️⃣ Display Probabilities

# Normalized superposition state
superposition = np.array([1/np.sqrt(2), 1/np.sqrt(2)])

display_probabilities(
 superposition,
 label="Superposition (50% |0⟩, 50% |1⟩)",
 theme=DARK_THEME
)

4️⃣ Show Measurement Counts

# Measurement results (1000 shots)
counts = {
 '0': 512,
 '1': 488,
}

display_counts(counts, label="Results: Aer Simulator", theme=LIGHT_THEME)

5️⃣ Visualize Operators

# Pauli X matrix (NOT gate)
pauli_x = np.array([[0, 1], [1, 0]])

display_operator_heatmap(pauli_x, label="Pauli X Operator", theme=PROFESSIONAL_THEME)

6️⃣ Academic Formatting

from quantum_utils import AcademicNumberFormatter, DiracExpressionGenerator

# Number formatter
formatter = AcademicNumberFormatter()
print(formatter.format(1/np.sqrt(2), precision=3)) # → \frac{1}{\sqrt{2}}
print(formatter.format(1+2j, precision=2)) # → (1.00+2.00i)

# Dirac notation generator
generator = DiracExpressionGenerator()
bell = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)])
print(generator.generate(bell)) # → (1/√2)|00⟩ + (1/√2)|11⟩

---

Detailed Documentation

Visualization Functions

display_data(value, label=None, theme=None)

Displays a vector or array as quantum data.

Parameters:

• value (array): Vector or numpy array
• label (str, optional): Graph title
• theme (HTMLTheme, optional): Visual theme

Example:

display_data([1, 0, 0, 0], label="State |00⟩")

---

display_probabilities(statevector, label=None, theme=None)

Displays probabilities of a normalized statevector.

Parameters:

• statevector (array): Normalized array with ⟨ψ|ψ⟩ = 1.0
• label (str, optional): Graph title
• theme (HTMLTheme, optional): Visual theme

Important: The statevector MUST be normalized!

# ✅ CORRECT - Normalized
superposition = np.array([1/np.sqrt(2), 1/np.sqrt(2)]) # norm = 1.0

# ❌ WRONG - Not normalized
wrong = np.array([0.5, 0.5]) # norm = 0.707

---

display_counts(counts, label=None, theme=None)

Displays measurement counts as a histogram.

Parameters:

• counts (dict): Dictionary with key (str) and values (int)
• label (str, optional): Graph title
• theme (HTMLTheme, optional): Visual theme

Example:

counts = {'0': 500, '1': 500}
display_counts(counts, label="Results")

---

display_operator_heatmap(operator, label=None, theme=None)

Displays an operator matrix as a heatmap.

Parameters:

• operator (array 2D): Operator matrix
• label (str, optional): Graph title
• theme (HTMLTheme, optional): Visual theme

Example:

hadamard = (1/np.sqrt(2)) * np.array([[1, 1], [1, -1]])
display_operator_heatmap(hadamard, label="Hadamard Gate")

---

Formatting Classes

AcademicNumberFormatter

Formats numbers in academic LaTeX notation.

Methods:

formatter = AcademicNumberFormatter()

# Format with precision
latex_str = formatter.format(number, precision=3)

Examples:

fmt = AcademicNumberFormatter()

fmt.format(1/np.sqrt(2)) # → r"\frac{1}{\sqrt{2}}"
fmt.format(np.sqrt(2)/2) # → r"\frac{\sqrt{2}}{2}"
fmt.format(1+2j, precision=2) # → "(1.00+2.00i)"
fmt.format(0.707, precision=3) # → "0.707"

---

DiracExpressionGenerator

Converts statevectors to automatic Dirac notation.

Methods:

gen = DiracExpressionGenerator()
dirac_expr = gen.generate(statevector)

Examples:

gen = DiracExpressionGenerator()

# Single qubit - superposition
superposition = np.array([1/np.sqrt(2), 1/np.sqrt(2)])
print(gen.generate(superposition))
# → "(1/√2)|0⟩ + (1/√2)|1⟩"

# Bell state - two qubits
bell = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)])
print(gen.generate(bell))
# → "(1/√2)|00⟩ + (1/√2)|11⟩"

# Generic state - 3 qubits
state_3q = np.array([1/np.sqrt(2), 0, 0, 0, 0, 0, 0, 1/np.sqrt(2)])
print(gen.generate(state_3q))
# → "(1/√2)|000⟩ + (1/√2)|111⟩"

---

HTMLTheme

Defines visual themes for graphs.

Available Themes:

HTMLTheme.DARK # Dark theme (default)
HTMLTheme.LIGHT # Light theme
HTMLTheme.PROFESSIONAL # Professional theme
HTMLTheme.NEON # Vibrant neon theme

Usage Example:

display_data(state, label="My State", theme=HTMLTheme.PROFESSIONAL)

---

Jupyter Notebook Examples

See the examples/exemplos.ipynb file for 9 ready-to-copy cells:

1. CELL 1 - Imports and themes (REQUIRED)
2. CELL 2 - Simple quantum states
3. CELL 3 - Superpositions and distributions
4. CELL 4 - Measurement counts
5. CELL 5 - Quantum operators
6. CELL 6 - Academic formatting (numbers and Dirac)
7. CELL 7 - Custom themes
8. CELL 8 - Multiple visualizations
9. CELL 9 - Real-world use cases

---

⚠️ Common Problems and Solutions

❌ ModuleNotFoundError: No module named 'quantum_utils'

Solution:

# Navigate to project directory
cd /Users/wellington/comp-quantica/quantum-study-utils

# Install the module
pip install -e "."

---

❌ ImportError: cannot import name 'X' from 'quantum_utils'

Cause: Old file conflicting with new module.

Solution:

# Restart Jupyter kernel:
# 1. Menu Kernel → Restart Kernel
# 2. Or in terminal: jupyter --clean-cache

---

❌ ValueError: Statevector is not normalized: ⟨ψ|ψ⟩ = 0.50

Cause: Array is not normalized (norm ≠ 1.0).

Solution:

# ❌ WRONG
wrong = np.array([0.5, 0.5]) # norm = 0.707

# ✅ CORRECT
correct = np.array([1/np.sqrt(2), 1/np.sqrt(2)]) # norm = 1.0

# Or normalize manually
wrong_norm = wrong / np.linalg.norm(wrong) # now norm = 1.0

---

❌ TypeError: unexpected keyword argument 'use_sqrt'

Cause: Wrong parameter in AcademicNumberFormatter.

Solution:

# ❌ WRONG
fmt.format(num, use_sqrt=True)

# ✅ CORRECT
fmt.format(num, precision=3)

---

Detailed Guides

• GUIA_RÁPIDO.md - Quick cheat sheet with examples (Portuguese)
• REFERÊNCIA_PARÂMETROS.md - Complete API reference (Portuguese)
• GUIA_FORMATADORES.md - All about formatters (Portuguese)
• examples/exemplos.ipynb - 9 example cells

---

Tests

Run tests to check library integrity:

# All tests
pytest tests/

# With coverage
pytest tests/ --cov=src/quantum_utils

# Specific test
pytest tests/test_measurements.py -v

---

Project Structure

quantum-study-utils/
├── pyproject.toml # Project configuration
├── README.md # Documentation in English
├── README_PT.md # Documentation in Portuguese
├── LICENSE # MIT License
│
├── src/quantum_utils/ # Source code
│ ├── __init__.py
│ ├── display/
│ │ ├── __init__.py
│ │ ├── display.py # Visualization functions
│ │ ├── formatters.py # Formatters (LaTeX, Dirac)
│ │ └── themes.py # Visual themes
│ ├── formatting.py # General formatting
│ ├── visualization.py # Visualization
│ └── measurements.py # Measurements
│
├── examples/ # Examples
│ ├── bell_state.ipynb
│ └── ibm_quantum.ipynb
│
├── tests/ # Tests
│ └── test_measurements.py
│
├── docs/ # Extra documentation
│ ├── examples/
│ ├── GUIA_RÁPIDO.md
│ ├── REFERÊNCIA_PARÂMETROS.md
│ └── GUIA_FORMATADORES.md
│
└── venv/ # Virtual environment (ignored)

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a branch for your feature (git checkout -b feature/new-feature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

‍ Author

Wellington - Software Developer

• GitHub: @wellington
• Project: comp-quantica

---

Support

Have questions? Check out:

• GUIA_RÁPIDO.md - Quick answers (Portuguese)
• REFERÊNCIA_PARÂMETROS.md - Complete documentation (Portuguese)
• examples/exemplos.ipynb - Working examples

---

Next Steps

1. ✅ Install the library
2. ✅ See examples/exemplos.ipynb
3. ✅ Paste into your Jupyter Notebook
4. ✅ Explore examples from cells 2-9
5. ✅ Refer to REFERÊNCIA_PARÂMETROS.md as needed

**Have fun exploring quantum computing! **