Metadata-Version: 2.4
Name: QCOM
Version: 0.2.2
Summary: Quantum Computation Library
Author-email: Avi Kaufman <avigkaufman@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Avi Kaufman
        
        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.
        
Project-URL: Homepage, https://github.com/AviKaufman/QCOM
Project-URL: Source, https://github.com/AviKaufman/QCOM
Project-URL: Issues, https://github.com/AviKaufman/QCOM/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Requires-Dist: pandas>=1.5
Provides-Extra: parquet
Requires-Dist: pyarrow>=10; extra == "parquet"
Provides-Extra: mitigation
Requires-Dist: mthree>=2.0; extra == "mitigation"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: QCOM[mitigation,parquet,viz]; extra == "all"
Dynamic: license-file

# QCOM

[![PyPI version](https://img.shields.io/pypi/v/QCOM.svg)](https://pypi.org/project/QCOM/)
[![Python versions](https://img.shields.io/pypi/pyversions/QCOM.svg)](https://pypi.org/project/QCOM/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/AviKaufman/QCOM/blob/main/LICENSE.txt)

**Quantum Computation (QCOM)** is a Python package originally developed as part of Avi Kaufman’s 2025 honors thesis, and now maintained as an **ongoing project for quantum systems research**.

QCOM offers a lightweight, extensible toolkit for building model Hamiltonians, evolving states, and analyzing classical/quantum information measures from simulated or experimental bitstring data.

---

## 📦 Installation

```bash
pip install QCOM
```

Upgrade to the latest release:

```bash
pip install --upgrade QCOM
```


⸻

✅ Quick check in python

```python
import qcom
print("QCOM version:", qcom.__version__)
```


⸻

## ✨ Core Capabilities

- **Hamiltonians**
  - Exact builders for **Rydberg** systems (chains/ladders)
  - (Growing set) utilities to support additional models

- **Solvers**
  - *Static*: thin-spectrum eigen solve, ground-state utilities, dense full spectrum for small systems
  - *Dynamic*: generic time evolution under time-dependent Hamiltonians via matrix exponentials

- **Metrics**
  - *Classical*: Shannon entropy, conditional entropy, mutual information
  - *Quantum*: von Neumann entanglement entropy (from state vectors, density matrices, or Hamiltonians)
  - *Probability tools*: cumulative distributions, N(p) diagnostic, statevector → probabilities

- **Data & Noise**
  - Parse/normalize/sample binary datasets (Plaintext, **Parquet**, **Aquila JSON**)
  - Readout noise models (bit-flip) and optional mitigation via `mthree`

- **I/O**
  - Save/load in plaintext and Parquet
  - Lightweight JSON reader for QuEra **Aquila** results

- **Developer Ergonomics**
  - `ProgressManager` hooks for long tasks
  - Clear conventions (MSB ↔ site 0), endianness controls where relevant

---

## 🚀 Examples

- Build a ladder Rydberg Hamiltonian and compute its ground-state entropy
- Parse measurement data (e.g., from Aquila) and evaluate **mutual information**
- Simulate **readout error** on a probability distribution and apply mitigation
- Sample and **merge** large bitstring datasets for statistical analysis

---

## 📚 Tutorials

Step-by-step notebooks live in the repository:

- **Tutorials directory**:  
  https://github.com/AviKaufman/QCOM/tree/main/tutorials

Suggested order:
1. I/O basics (text, JSON, Parquet)  
2. Lattice registers and geometry  
3. Rydberg Hamiltonians  
4. Static eigen solvers (ground states)  
5. Control time series  
6. Dynamic time evolution  
7. Data utilities (noise, sampling, mitigation)  
8. Metrics (classical + entanglement)

---

## 🧪 Testing

From the project root:

```bash
pytest
# or restrict to the project tests folder
pytest tests/
```

If you see an “import file mismatch” error, clear caches:

```bash
find . -name "__pycache__" -type d -exec rm -rf {} +
find . -name "*.pyc" -delete
```
⸻

📂 Example Data

Curated toy datasets for quick experiments:  
- https://github.com/AviKaufman/QCOM/tree/main/example_data

⸻

🗺️ Roadmap
- New Hamiltonians: Ising, Heisenberg, and additional lattice models
- Parameter sweeps for large optimization workloads
- Tensor-network methods: DMRG / TEBD for large Hilbert spaces
- Expanded I/O readers and richer plotting presets

Community feedback helps shape priorities—feel free to open issues or PRs.

⸻

🤝 Contributing

We welcome contributions of all sizes:
	•	Bug reports, minimal reproductions
	•	Tests and doc improvements
	•	New examples/tutorials
	•	Feature proposals via GitHub Issues

Repo: https://github.com/AviKaufman/QCOM

⸻

📬 Contact

Avi Kaufman — avigkaufman@gmail.com

⸻

Last updated: December 9, 2025
