Metadata-Version: 2.4
Name: encoding-atlas
Version: 0.1.0
Summary: A comprehensive library for quantum data encodings in machine learning
Author-email: Ashutosh Mishra <ashutoshm1771@gmail.com>
Maintainer-email: Ashutosh Mishra <ashutoshm1771@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ashutoshm1771/quantum-encoding-atlas
Project-URL: Documentation, https://q-encoding-atlas.web.app/documentation
Project-URL: Repository, https://github.com/ashutoshm1771/quantum-encoding-atlas.git
Project-URL: Issues, https://github.com/ashutoshm1771/quantum-encoding-atlas/issues
Project-URL: Changelog, https://github.com/ashutoshm1771/quantum-encoding-atlas/blob/master/CHANGELOG.md
Keywords: quantum computing,quantum machine learning,qml,data encoding,feature maps,pennylane,qiskit,cirq
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0.0,>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pennylane>=0.33.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0.0; extra == "qiskit"
Requires-Dist: qiskit-aer>=0.13.0; extra == "qiskit"
Provides-Extra: cirq
Requires-Dist: cirq-core>=1.0.0; extra == "cirq"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
Provides-Extra: all
Requires-Dist: encoding-atlas[cirq,qiskit,visualization]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: nox>=2023.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == "docs"
Requires-Dist: mkdocs-section-index>=0.3.0; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.24.0; extra == "docs"
Dynamic: license-file

<div align="center">

# Quantum Encoding Atlas

**The comprehensive library for quantum data encodings in machine learning**

[![PyPI version](https://badge.fury.io/py/encoding-atlas.svg)](https://badge.fury.io/py/encoding-atlas)
[![Python versions](https://img.shields.io/pypi/pyversions/encoding-atlas.svg)](https://pypi.org/project/encoding-atlas/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/ashutoshm1771/quantum-encoding-atlas/actions/workflows/ci.yml/badge.svg)](https://github.com/ashutoshm1771/quantum-encoding-atlas/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/ashutoshm1771/quantum-encoding-atlas/branch/master/graph/badge.svg)](https://codecov.io/gh/ashutoshm1771/quantum-encoding-atlas)
[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://q-encoding-atlas.web.app/documentation)

[Documentation](https://q-encoding-atlas.web.app/documentation) |
[Tutorials](https://q-encoding-atlas.web.app/documentation) |
[API Reference](https://q-encoding-atlas.web.app/documentation)

</div>

---

## Overview

The **Quantum Encoding Atlas** is the definitive open-source resource for understanding, comparing, and selecting quantum data encodings for machine learning applications.

## Features

- 📊 **16 Encoding Methods** — Comprehensive implementations of all major quantum data encodings
- 🔀 **Multi-Framework Support** — Works seamlessly with PennyLane, Qiskit, and Cirq
- 📈 **Analysis Tools** — Compute expressibility, entanglement capability, and trainability
- 🧪 **Benchmarking Framework** — Systematic comparison infrastructure
- 🧭 **Decision Guide** — Evidence-based encoding recommendations
- 📚 **Extensive Documentation** — Tutorials, API docs, and theoretical background

## Installation

```bash
pip install encoding-atlas
```

With optional backends:

```bash
# With Qiskit support
pip install encoding-atlas[qiskit]

# With Cirq support
pip install encoding-atlas[cirq]

# With all backends
pip install encoding-atlas[all]

# Development installation
pip install encoding-atlas[dev]
```

## Quick Start

```python
from encoding_atlas import IQPEncoding, AngleEncoding
from encoding_atlas.analysis import compute_expressibility
import numpy as np

# Create encodings
iqp = IQPEncoding(n_features=4, reps=2)
angle = AngleEncoding(n_features=4, rotation='Y')

# Generate circuits (PennyLane by default)
X = np.random.randn(10, 4)
circuit = iqp.get_circuit(X[0])

# Analyze properties
print(f"IQP qubits: {iqp.n_qubits}")
print(f"IQP depth: {iqp.depth}")
print(f"IQP expressibility: {compute_expressibility(iqp, n_samples=500):.4f}")

# Get encoding recommendation
from encoding_atlas.guide import recommend_encoding

rec = recommend_encoding(
    n_features=4,
    n_samples=500,
    task='classification',
    hardware='simulator'
)
print(f"Recommended: {rec.encoding_name}")
print(f"Reason: {rec.explanation}")
```

## Supported Encodings

| Category | Encodings |
|----------|-----------|
| **Amplitude-based** | AmplitudeEncoding |
| **Angle-based** | AngleEncoding (RX/RY/RZ), HigherOrderAngleEncoding |
| **Basis** | BasisEncoding |
| **Entangling** | IQPEncoding, ZZFeatureMap, PauliFeatureMap |
| **Advanced** | DataReuploading, HardwareEfficientEncoding, QAOAEncoding, HamiltonianEncoding |
| **Symmetry & Equivariant** | SymmetryInspiredFeatureMap, SO2EquivariantFeatureMap, CyclicEquivariantFeatureMap, SwapEquivariantFeatureMap |
| **Trainable** | TrainableEncoding |

See the [full encoding list](https://q-encoding-atlas.web.app/documentation) for details.

## Documentation

- [Installation Guide](https://q-encoding-atlas.web.app/documentation)
- [Quick Start Tutorial](https://q-encoding-atlas.web.app/documentation)
- [Encoding Selection Guide](https://q-encoding-atlas.web.app/documentation)
- [API Reference](https://q-encoding-atlas.web.app/documentation)

## Citation

If you use this library in your research, please cite:

```bibtex
@software{Mishra2026encoding,
  title={Quantum Encoding Atlas: A Comprehensive Library for Quantum Data Encodings},
  author={Mishra, Ashutosh},
  year={2026},
  url={https://github.com/ashutoshm1771/quantum-encoding-atlas},
  version={0.1.0}
}
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
