Metadata-Version: 2.4
Name: quantum-study-utils
Version: 0.2.0
Summary: Utilities for quantum computing education, visualization and research
Author-email: "Wellington F. Silva" <wellington@altrion.com.br>
License-Expression: MIT
Keywords: quantum computing,quantum mechanics,qiskit,visualization,display,education,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.12
Requires-Dist: ipython>=8.0
Provides-Extra: qiskit
Requires-Dist: qiskit>=2.0; extra == "qiskit"
Provides-Extra: simulator
Requires-Dist: qiskit>=2.0; extra == "simulator"
Requires-Dist: qiskit-aer>=0.17; extra == "simulator"
Provides-Extra: ibm
Requires-Dist: qiskit>=2.0; extra == "ibm"
Requires-Dist: qiskit-ibm-runtime>=0.45; extra == "ibm"
Provides-Extra: notebook
Requires-Dist: ipykernel>=6.0; extra == "notebook"
Requires-Dist: jupyterlab>=4.0; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: all
Requires-Dist: qiskit>=2.0; extra == "all"
Requires-Dist: qiskit-aer>=0.17; extra == "all"
Requires-Dist: qiskit-ibm-runtime>=0.45; extra == "all"
Requires-Dist: ipykernel>=6.0; extra == "all"
Requires-Dist: jupyterlab>=4.0; extra == "all"
Dynamic: license-file

# Quantum Study Utils

[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
![Version](https://img.shields.io/badge/Version-0.2.0-brightgreen)

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](README_PT.md)

---

## ✨ 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)

```bash
# 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:

```python
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

```python
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

```python
# 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

```python
# 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

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

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

### 5️⃣ Visualize Operators

```python
# 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

```python
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:**
```python
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!
```python
# ✅ 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:**
```python
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:**
```python
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:**
```python
formatter = AcademicNumberFormatter()

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

**Examples:**
```python
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:**
```python
gen = DiracExpressionGenerator()
dirac_expr = gen.generate(statevector)
```

**Examples:**
```python
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:**
```python
HTMLTheme.DARK # Dark theme (default)
HTMLTheme.LIGHT # Light theme
HTMLTheme.PROFESSIONAL # Professional theme
HTMLTheme.NEON # Vibrant neon theme
```

**Usage Example:**
```python
display_data(state, label="My State", theme=HTMLTheme.PROFESSIONAL)
```

---

## Jupyter Notebook Examples

See the [examples/exemplos.ipynb](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:**
```bash
# 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:**
```python
# 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:**
```python
# ❌ 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:**
```python
# ❌ WRONG
fmt.format(num, use_sqrt=True)

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

---

## Detailed Guides

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

---

## Tests

Run tests to check library integrity:

```bash
# 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](LICENSE) file for details.

---

## ‍ Author

**Wellington** - Software Developer
- GitHub: [@wellington](https://github.com/wellington)
- Project: comp-quantica

---

## Support

Have questions? Check out:

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

---

## Next Steps

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

**Have fun exploring quantum computing! **
