Metadata-Version: 2.4
Name: dense-evolution
Version: 8.0.0
Summary: Micro-optimized High-Performance NISQ Statevector Quantum Circuit Simulator (Hardware-Adaptive Integration of Native NumPy, CUDA-Accelerated CuPy, and Linear Kernel Fusion via JAX JIT/XLA Compilation)
Author-email: Salvatore Pennacchio <jtatopenn@libero.it>
License: MIT
Project-URL: Homepage, https://github.com/tatopenn-cell/Dense-Evolution
Project-URL: Documentation, https://github.com/tatopenn-cell/Dense-Evolution/wiki
Project-URL: Repository, https://github.com/tatopenn-cell/Dense-Evolution
Project-URL: Bug Tracker, https://github.com/tatopenn-cell/Dense-Evolution/blob/main/dense_evolution.py
Keywords: quantum-computing,quantum-simulation,statevector,jax,cupy,cuda-acceleration,openqasm,nisq-noise,hpc,linear-kernel-fusion
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: jax
Requires-Dist: jax>=0.4.0; extra == "jax"
Requires-Dist: jaxlib>=0.4.0; extra == "jax"
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=12.0.0; extra == "gpu"
Provides-Extra: full
Requires-Dist: jax>=0.4.0; extra == "full"
Requires-Dist: jaxlib>=0.4.0; extra == "full"
Requires-Dist: cupy-cuda12x>=12.0.0; extra == "full"
Dynamic: license-file

# 💎 Dense Evolution v8.0 (TurboQuant Core)

[![Python Version](https://shields.io)](https://python.org)
[![Backend](https://shields.io)](https://github.com)
[![License](https://shields.io)](https://opensource.org)

**Dense Evolution v8.0** è un simulatore quantistico basato su vettori di stato (*Statevector*) ad altissime prestazioni, ingegnerizzato specificamente per l'esecuzione di circuiti NISQ (Noisy Intermediate-Scale Quantum) complessi, profondi e algoritmi di Quantum Machine Learning (QML) e VQE.

L’architettura interna si basa sul principio della **Linear Kernel Fusion** ad allocazione controllata, superando i tradizionali colli di bottiglia legati all’uso della memoria ausiliaria (*scratchpad RAM*) e ridefinendo i limiti computazionali della compilazione statica accelerata via hardware.

---

## 🚀 Caratteristiche Architetturali & Features

* **⚡ Linear Kernel Fusion (JAX XLA):** Il simulatore non calcola mai esplicitamente le enormi matrici di gate derivanti dai prodotti tensoriali (Kronecker). L’applicazione degli operatori avviene tramite algoritmi di *stride-slicing* e permutazione lineare sui tensori contigui, riducendo la complessità di memoria spaziale al minimo teorico assoluto.
* **🧩 Circuit Chunking Transpiler:** Risolve il problema del congelamento o degrado della cache JIT di JAX quando si lavora con migliaia di porte logiche. Il circuito viene frammentato in sotto-blocchi (chunk) geometrici equivalenti, garantendo stabilità computazionale infinita, azzerando l'overhead di tracing su circuiti massivi.
* **🎲 Coerenza Stocastica e Collasso d'Onda:** La funzione di misura implementa uno *stride-slicing* chirurgico direttamente sulle matrici di vista hardware (NumPy/CuPy/JAX). Questo garantisce la perfetta convergenza binomiale ed evita l'allocazione di maschere booleane giganti in RAM, prevenendo crash di sistema.
* **📉 Modelli di Rumore a Traiettoria Kraus:** Consente la simulazione realistica di hardware affetti da rumore ambientale tramite canali di *Amplitude Damping*, *Phase Damping* e *Depolarizzazione*, applicati como salti quantici stocastici discreti senza l’onere computazionale $2^{2n}$ delle matrici di densità piene.
* **🎛️ Disaccoppiamento Hardware (Agnostic Backend):** Sfrutta un’astrazione polimorfa per selezionare a runtime l’hardware più efficiente: NumPy (CPU standard), JAX (Compilazione JIT hardware parallelizzata CPU/TPU) o CuPy (Calcolo parallelo accelerato su NVIDIA GPU CUDA).

---

## ⚙️ Istruzioni di Installazione

Il motore è strutturato in conformità con lo standard **PEP 621** (tramite `pyproject.toml`) ed è completamente installabile tramite `pip` in modalità isolata o editabile per gli sviluppatori.

```bash
# Clone della repository locale
git clone
 https://github.com/tatopenn-cell/Dense-Evolution.git


# Installazione Standard (Backend CPU standard NumPy)
pip install .

# Installazione High-Performance (Raccomandata in modalità sviluppatore editable)
pip install -e .
```

---

## 📊 Benchmark Industriali e Limiti del Sistema

Il motore è stato sottoposto a stress-test aggressivi in ambienti a risorse limitate (Google Colab Free), registrando risultati d’élite nel contenimento della memoria e nella precisione aritmetica.

### 1. Stabilità Numerica Assoluta (Zero-Drift Execution)
Sottoposto ad Ansatz variazionali profondi (oltre 80 strati e 1360 porte parametriche consecutive fuse in un unico blocco XLA), il core del simulatore ha registrato una deriva numerica assoluta controllata pari a:
$$\Delta = 1.1102230246251565 \times 10^{-16}$$
Questo valore coincide esattamente con l'**Epsilon di macchina ($\epsilon$)** per la precisione doppia a 64 bit (`float64`). La fusione algebrica dei kernel in XLA annulla l'accumulo sequenziale degli errori di arrotondamento delle funzioni trigonometriche.

### 2. Scaling dei Qubit e Throughput Computazionale (Chunking Engine)
Grazie al motore di chunking in-place, il simulatore gestisce registri quantistici estesi ottimizzando chirurgicamente la cache di sistema senza generare copie temporanee dello stato:


| Qubits | Dimensione Stato (Ampiezze) | Tempo di Esecuzione (s) | Gates / Secondo | RAM Reale Allocata | Delta RAM a Runtime |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **14** | 16.384 | 0.3546 s | 2819.9 | ~0.26 MB | **0.00 MB** |
| **16** | 65.536 | 0.4217 s | 2370.8 | ~1.04 MB | **0.00 MB** |
| **24** | 16.777.216 | 0.7090 s | *JIT Standard Tier* | ~256.00 MB | < 1.00 MB |
| **29** | **536.870.912** | *HPC Chunk Tier* | *Hardware Saturation* | **8192.00 MB** | **0.00 MB** |

> 💡 **Nota di Merito:** Il superamento della barriera dei 24 qubit in ambienti con soli 12 GB di RAM totali (Colab Free) evidenzia l’efficacia dell'architettura lineare 1D a norma fissa, che azzera i reshape dinamici a basso livello.

### 3. Parallelizzazione Vettorizzata JAX `vmap` (Batch Engine)
Il modulo `run_parametric_batch_jit` sfrutta la parallelizzazione inter-circuito per il Quantum Machine Learning. Esegue un singolo tracciamento del grafo computazionale e distribuisce istantaneamente N configurazioni di parametri sulla griglia hardware:
* **Throughput testato:** 64 circuiti variazionali paralleli eseguiti simultaneamente in **1.96 secondi**.
* **Tempo medio per circuito:** ⏱️ **0.031 secondi**.

---

## 💻 Esempi Pratici di Codice

### 🛠️ Esempio 1: Esecuzione in Beast Mode (Kernel Fusion JIT)
Dimostrazione dell'interfaccia ultra-veloce a zero allocazioni. La Beast Mode accetta un array lineare di operazioni stringa per bypassare completamente i controlli dell'interprete Python:

```python
import dense_evolution as de

# Inizializzazione del simulatore a 2 Qubit
sim = de.DenseSVSimulator(n_qubits=2)

# Definizione del circuito strutturato (Porta, Target, Controllo/Parametro)
# Generazione nativa di uno Stato di Bell entangled
ops = [
    ["h", 0, -1],
    ["cx", 1, 0]
]

# Esecuzione istantanea nel compilatore fuso XLA
sim.run_circuit_jit_beast_mode(ops)

print(f"Stato Finale Entangled JIT: {sim.get_statevector()}")
print(f"Probabilità di estrazione: {sim.get_probabilities()}")
```

### 🧠 Esempio 2: Decomposizione Topologica con il QuantumTranspiler
Il transpiler integrato scompone le porte logiche non native e complesse a più qubit nelle primitive a 1 e 2 qubit accettate dal core lineare 1D:

```python
import dense_evolution as de

transpiler = de.QuantumTranspiler()

# Estrazione della scomposizione esatta di una porta Toffoli (CCNOT) sui qubit 0, 1 e 2
sequenza_primitive = transpiler.decompose_toffoli(0, 1, 2)

print(f"Totale porte primitive generate per il Core V4: {len(sequenza_primitive)}")
for gate in sequenza_primitive:
    print(f"  -> {gate}")
# Output generato: Sequenza esatta a 15 porte stabili (H, CNOT, T, Tdg)
```

### 📉 Esempio 3: Iniezione stocastica del NoiseModel
Applicazione di canali di rumore realistici NISQ in modalità stocastica unificata JAX-safe:

```python
import dense_evolution as de
import numpy as np

sim = de.DenseSVSimulator(n_qubits=2)

# Applicazione manuale di una porta singola (Firma: Matrice, Qubit)
h_matrix = de.GATES['h']
sim.apply_gate_1q(h_matrix, 0)

# Lettura telemetria di sistema in tempo reale (Variabile float globale)
print(f"RAM attualmente disponibile su Colab: {de.ram_avail:.2f} MB")

# Iniezione di rumore di depolarizzazione al 5% sul vettore di stato
sim.sv = de.NoiseModel.apply_to_sv(
    sv=sim.sv, 
    n=2, 
    model='depolarizing', 
    p=0.05
)

print(f"Stato rumoroso degradato: {sim.get_statevector()}")
```

---

## 📂 Architettura dei File nella Repository

```text
Dense-Evolution/
│
├── pyproject.toml         # Configurazione PEP 621, build backend e dipendenze opzionali [jax,gpu]
├── README.md              # Documentazione tecnica ufficiale, telemetria e benchmark (Questo file)
└── dense_evolution.py     # Codice sorgente core del simulatore (DenseSVSimulator v8.0)
```

---

## 📜 Licenza e Note Legali

Il progetto è interamente distribuito sotto i termini della licenza ufficiale **MIT**.

```text
MIT License

Copyright (c) 2026 salvatore pennacchio [tatopenn-cell]

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.
```


