quantum-study-utils 0.2.0__tar.gz

quantum_study_utils-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Quantum Study Utils Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantum_study_utils-0.2.0/PKG-INFO

@@ -0,0 +1,513 @@
+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! **