Metadata-Version: 2.4
Name: hilbertlens
Version: 0.1.2
Summary: A diagnostic suite for Quantum Machine Learning encodings.
Author-email: "Md. Abdullah Al Mamun" <abdullah18@temple.edu>
License: MIT License
        
        Copyright (c) 2026 Md. Abdullah Al Mamun
        
        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/mamuncseru/hilbertlens
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: matplotlib>=3.5
Requires-Dist: scikit-learn>=1.0
Requires-Dist: scipy>=1.7
Requires-Dist: qiskit>=1.0
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.30; extra == "pennylane"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Dynamic: license-file


# HilbertLens 🔬

**HilbertLens** is a diagnostic tool for Quantum Machine Learning (QML). It visualizes the hidden geometry of your quantum encodings and "diagnoses" their capacity to learn complex data.

Instead of blindly training Variational Quantum Circuits (VQC) and guessing why they fail, `HilbertLens` tells you:
1.  **Spectrum Analysis:** Does the circuit have enough bandwidth (expressibility) for the data?
2.  **Geometry Analysis:** Does the encoding preserve the topological structure of the data?

## 📦 Installation

```bash
pip install .

```

For development (so edits are reflected immediately):

```bash
pip install -e .

```

## 🚀 Quick Start

### 1. The "Doctor" Check

Pass your circuit to the `QuantumLens` and ask for a diagnosis.

```python
import hilbertlens as hl
from qiskit.circuit import ParameterVector, QuantumCircuit

# Define your circuit
x = ParameterVector('x', 2)
qc = QuantumCircuit(2)
qc.h([0, 1])
qc.rz(x[0], 0)
qc.rz(x[1], 1)
qc.cx(0, 1) # Entanglement

# Initialize Lens
lens = hl.QuantumLens(qc, params=list(x), framework='qiskit')

# Run Diagnosis (Auto-runs Spectrum and Geometry checks)
lens.diagnose()

```

### 2. Manual Inspection

You can run individual checks and save the plots.

```python
# Check Frequency Spectrum (Capacity)
lens.spectrum(mode='global', save_path="spectrum.png")

# Check Geometry Preservation (using synthetic Swiss Roll)
lens.geometry(save_path="geometry.png")

```

## 🏥 Understanding the Report

* **[GOLD STANDARD]:** Your circuit has a rich spectrum (multiple frequencies) AND preserves geometry. It is ready for research.
* **[SAFE BUT SIMPLE]:** Your circuit is linear (). It will work on simple data (Iris) but underfit complex data (Moons).
* **[BROKEN GEOMETRY]:** Your circuit destroys the data structure (e.g., score < 0.5). Check your data scaling!

## 🔧 Supported Frameworks

* **Qiskit** (Native support)
* **PennyLane** (Auto-detected if installed)


## Sample Output
---
#### Testing with Real Data: Two Moons 
[Test Script: Two Moons](https://raw.githubusercontent.com/mamuncseru/hilbertlens/main/tests/hilbertlens_testing/test_two_moons.py)

**Data Shape:** `(200, 2)`  
**Features:** 2  

#### i. Quantum Circuit
**Circuit Created:** 2-Qubit Entangled Network

![Two Moons Encoding Circuit](https://raw.githubusercontent.com/mamuncseru/hilbertlens/main/tests/hilbertlens_testing/two_moons_encoding_circuit.png)

**[HilbertLens]** Initialized for framework: `qiskit`


#### ii. Geometry Check (Two Moons)

**Status:** Analyzing Geometry  
- **Geometry Score (Spearman Correlation):** `0.9182`  
- **Output:** `moons_geometry.png`



#### iii. Spectrum Check

**Status:** Computing Spectrum  
**Mode:** Global

**Dominant Frequencies — Global Sweep**
- **k = 1.0** | Power: `0.446`  
- **k = 3.0** | Power: `0.442`  
- **k = 2.0** | Power: `0.112`  

**Output:** `moons_spectrum.png`
![Two Moons Spectrum](https://raw.githubusercontent.com/mamuncseru/hilbertlens/main/tests/hilbertlens_testing/moons_spectrum.png)

#### HILBERTLENS DIAGNOSIS REPORT

### [1] Spectrum Analysis — Capacity & Expressibility
- **Active Frequencies:** 3 (Richness)  
- **Max Frequency:** `k = 3.0` (Bandwidth)  
- **Category:** High Capacity (Rich Expressibility)  
- **Assessment:** Complex spectrum with three active frequencies; capable of deep nuance.  
- **Advice:** Gold standard. Capable of universal classification.


#### [2] Geometry Analysis — Inductive Bias
- **Preservation Score:** `0.9182` (Spearman ρ)  
- **Category:** Excellent Preservation  
- **Assessment:** The quantum kernel faithfully preserves the topological structure of the input data.


#### [3] Final Verdict

> **[GOLD STANDARD] READY FOR RESEARCH**  
> Your circuit exhibits **High Capacity (Rich Spectrum)** and **Stable Geometry**.  
> It can learn complex decision boundaries without breaking data topology.
