Skip to content

README.md

Latest commit

 

History

History
208 lines (155 loc) · 9.89 KB

README.md

File metadata and controls

208 lines (155 loc) · 9.89 KB
Raw

Quantum Encoding Atlas

The comprehensive library for quantum data encodings in machine learning

PyPI version Python versions License: MIT CI codecov Documentation DOI Website

Documentation | Website | Tutorials | API Reference | PyPI

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
  • 🗺️ Empirical Atlas — Query the measured benchmark results (rank, accuracy, expressibility, trainability, …) bundled with the package
  • 📚 Extensive Documentation — Tutorials, API docs, and theoretical background

Installation

pip install encoding-atlas

With optional backends:

# 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

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}")

Query the empirical atlas

The measured benchmark results for every encoding ship with the package as a queryable, read-only API:

from encoding_atlas.atlas import get_encoding_profile, rank_encodings, pareto_front

# Measured profile of a single encoding
angle = get_encoding_profile("angle")
print(angle.rank, round(angle.metric("kernel_accuracy"), 3))   # 1 0.958

# Rank encodings by any measured metric
print([p.name for p in rank_encodings(by="kernel_accuracy", limit=3)])
# ['angle', 'cyclic_equivariant', 'qaoa']

# The Pareto-optimal set across accuracy, depth, trainability, and noise
print(sorted(p.name for p in pareto_front()))
# ['angle', 'basis', 'higher_order_angle', 'swap_equivariant']

Benchmark encodings on your own data

Run variational-quantum-classifier and quantum-kernel comparisons with paired cross-validation, classical baselines, and statistical testing:

from encoding_atlas import AngleEncoding, IQPEncoding
from encoding_atlas.benchmark import EncodingBenchmark, evaluate_encoding

# Compare encodings across datasets and methods
bench = EncodingBenchmark(
    encodings=[AngleEncoding(n_features=2), IQPEncoding(n_features=2)],
    datasets=["moons", "circles"],
    methods=("vqc", "kernel"),
    n_runs=3,
    n_folds=5,
    baselines=("svm_rbf",),
    seed=0,
)
results = bench.run()
stats = bench.statistical_tests()   # Wilcoxon + Holm–Bonferroni + Cliff's delta

# ...or evaluate a single encoding on your own (X, y)
report = evaluate_encoding(AngleEncoding(n_features=2), X, y, method="kernel")
print(report["mean"], report["ci_low"], report["ci_high"])

Diagnose why an encoding generalizes

Cheap, training-free kernel-geometry metrics that predict downstream performance — kernel-target alignment, geometric difference, and effective dimension:

from encoding_atlas.analysis import (
    compute_kernel_target_alignment,
    compute_geometric_difference,
    compute_effective_dimension,
)

# How well the encoding's kernel matches the task (predicts accuracy)
kta = compute_kernel_target_alignment(AngleEncoding(n_features=2), X, y)

# How distinct the quantum kernel is from a classical one (advantage diagnostic)
gd = compute_geometric_difference(AngleEncoding(n_features=2), X)

# Effective feature-space dimension the encoding uses (capacity)
d_eff = compute_effective_dimension(AngleEncoding(n_features=2), X)

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 for details.

Documentation

Citation

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

@software{Mishra2026encoding,
  title={Quantum Encoding Atlas: A Comprehensive Library for Quantum Data Encodings},
  author={Mishra, Ashutosh},
  year={2026},
  doi={10.5281/zenodo.18780936},
  url={https://doi.org/10.5281/zenodo.18780936},
  version={1.0.0}
}

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

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