dense-evolution 8.1.6__tar.gz → 8.1.8__tar.gz

dense_evolution-8.1.8/PKG-INFO

@@ -0,0 +1,576 @@
+Metadata-Version: 2.4
+Name: dense-evolution
+Version: 8.1.8
+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: Business Source License 1.1
+Project-URL: Homepage, https://github.com/tatopenn-cell/Dense-Evolution
+Project-URL: Documentation, https://github.com/tatopenn-cell/Dense-Evolution/blob/main/README.md
+Project-URL: Repository, https://github.com/tatopenn-cell/Dense-Evolution
+Project-URL: Bug Tracker, https://github.com/tatopenn-cell/Dense-Evolution/issues
+Keywords: quantum-computing,quantum-simulation,statevector,jax,cupy,cuda-acceleration,openqasm,nisq-noise,hpc,linear-kernel-fusion,dashboard,visualization
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary 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.md
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: scipy>=1.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: dashboard
+Requires-Dist: dash>=2.0.0; extra == "dashboard"
+Requires-Dist: plotly>=5.0.0; extra == "dashboard"
+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"
+Requires-Dist: dash>=2.0.0; extra == "full"
+Requires-Dist: plotly>=5.0.0; extra == "full"
+Dynamic: license-file
+
+```
+██████╗ ███████╗███╗   ██╗███████╗███████╗
+██╔══██╗██╔════╝████╗  ██║██╔════╝██╔════╝
+██║  ██║█████╗  ██╔██╗ ██║███████╗█████╗  
+██║  ██║██╔══╝  ██║╚██╗██║╚════██║██╔══╝  
+██████╔╝███████╗██║ ╚████║███████║███████╗
+╚═════╝ ╚══════╝╚═╝  ╚═══╝╚══════╝╚══════╝
+███████╗██╗   ██╗ ██████╗ ██╗     ██╗   ██╗████████╗██╗ ██████╗ ███╗   ██╗
+██╔════╝██║   ██║██╔═══██╗██║     ██║   ██║╚══██╔══╝██║██╔═══██╗████╗  ██║
+█████╗  ██║   ██║██║   ██║██║     ██║   ██║   ██║   ██║██║   ██║██╔██╗ ██║
+██╔══╝  ╚██╗ ██╔╝██║   ██║██║     ██║   ██║   ██║   ██║██║   ██║██║╚██╗██║
+███████╗ ╚████╔╝ ╚██████╔╝███████╗╚██████╔╝   ██║   ██║╚██████╔╝██║ ╚████║
+╚══════╝  ╚═══╝   ╚═════╝ ╚══════╝ ╚═════╝    ╚═╝   ╚═╝ ╚═════╝ ╚═╝  ╚═══╝
+```
+
+
+**Dense Statevector Quantum Simulator · JAX XLA · NISQ · VQE · QML**
+
+[![CI](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml/badge.svg)](https://github.com/tatopenn-cell/Dense-Evolution/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dense-evolution?style=flat-square&color=00e5ff)](https://pypi.org/project/dense-evolution/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/dense-evolution?style=flat-square&color=00e5ff)](https://pypi.org/project/dense-evolution/)
+[![Python](https://img.shields.io/badge/Python-3.9+-blue?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-BSL_1.1-orange?style=flat-square)](LICENSE.md)
+[![Build](https://img.shields.io/badge/Build-Passing-00ff9d?style=flat-square)](https://github.com/tatopenn-cell/Dense-Evolution/actions)
+[![Cross-Validation CI](https://github.com/tatopenn-cell/Dense-Evolution-Ising-Tests/actions/workflows/ci.yml/badge.svg)](https://github.com/tatopenn-cell/Dense-Evolution-Ising-Tests/actions/workflows/ci.yml)
+[![Latest Release](https://img.shields.io/github/v/release/tatopenn-cell/Dense-Evolution?style=flat-square&color=blueviolet)](https://github.com/tatopenn-cell/Dense-Evolution/releases)
+[![Last Commit](https://img.shields.io/github/last-commit/tatopenn-cell/Dense-Evolution?style=flat-square)](https://github.com/tatopenn-cell/Dense-Evolution/commits/main)
+[![Issues](https://img.shields.io/github/issues/tatopenn-cell/Dense-Evolution?style=flat-square)](https://github.com/tatopenn-cell/Dense-Evolution/issues)
+[![Stars](https://img.shields.io/github/stars/tatopenn-cell/Dense-Evolution?style=flat-square&color=yellow)](https://github.com/tatopenn-cell/Dense-Evolution/stargazers)
+[![JAX](https://img.shields.io/badge/Backend-JAX_XLA-f9ab00?style=flat-square&logo=google&logoColor=white)](https://github.com/google/jax)
+
+---
+
+## ▍ What It Is
+
+**Dense Evolution** is a high-performance statevector simulator engineered for deep NISQ circuits, VQE pipelines, and QML workloads. It eliminates Kronecker product overhead entirely via stride-sliced linear kernel fusion compiled through JAX XLA — keeping memory at the theoretical minimum of `2ⁿ × 16 bytes`.
+
+The integrated `dash.py` dashboard provides live ipywidgets telemetry across 8 panels per simulation run, directly inside Google Colab or Jupyter.
+
+---
+
+## ▍ Install
+
+```bash
+pip install dense-evolution
+
+# full stack: JAX · GPU · dashboard
+pip install dense-evolution[full]
+
+# development
+git clone https://github.com/tatopenn-cell/Dense-Evolution.git
+cd Dense-Evolution && pip install -e .[full]
+```
+
+**Google Colab (3 lines):**
+
+```python
+!git clone https://github.com/tatopenn-cell/Dense-Evolution.git
+%cd Dense-Evolution
+!pip install -e .
+```
+
+---
+
+## ▍ Quick Start
+
+```python
+from dense_evolution import DenseSVSimulator, QASMParser
+
+# parse any OpenQASM 2.0 / 3.0 string
+qasm = """
+OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[3];
+h q[0];
+cx q[0], q[1];
+cx q[1], q[2];
+"""
+
+parser = QASMParser()
+circuit = parser.parse(qasm)
+
+sim = DenseSVSimulator(n_qubits=3)
+sim.run_circuit_jit_beast_mode(circuit.ops)
+
+probs = sim.get_probabilities()
+sv    = sim.get_statevector()
+```
+
+**Dashboard (Colab / Jupyter):**
+
+```python
+import dash
+from IPython.display import display, clear_output
+
+clear_output()
+display(dash.dashboard_unificata)
+```
+
+**Anti-OOM for large circuits:**
+
+```python
+from dense_evolution import Chunk
+
+sim = Chunk(27)                                    # logical 27 qubits
+circuit_ops = [['h', i] for i in range(27)]
+sim.run_chunk(circuit_ops, chunk_size_gates=500)   # SafeMemoryGuard active
+```
+
+---
+
+## ▍ Architecture
+
+```
+dense_evolution/
+├── registry.py     hardware detection · JAX/CuPy/NumPy flags · NoiseModel (Kraus channels)
+├── gates.py        GATES{} · PARAMETRIC_GATES{} · GATE_IDS{}
+├── healing.py      predictive state engine · Phi_AB · vettore dinamico · MemoryReflectionEngine
+├── parser.py       QASMParser · QASMCircuit · OpenQASM 2.0 / 3.0
+├── compiler.py     QuantumTranspiler · _apply_gate_fast_step (jit) · gate decomposition
+├── chunk.py        SafeMemoryGuard · MemoryChunker · CircuitChunker · Chunk (Anti-OOM)
+├── simulator.py    DenseSVSimulator · run_parametric_batch_jit · vmap batch VQE
+└── dash.py         ipywidgets dashboard · VQE engine · QM/MM · MD simulation · 3D wavefunction
+
+ia_utils/
+└── vector_healing.py   median_healing · enhanced_dense_healing_hybrid (NaN/Inf-safe, lazy JAX import)
+```
+
+**Data flow per run:**
+
+```
+▶ Run
+└─ core_calcolo_quantistico()        parse → JIT execute → apply noise
+    ├─ ottimizza_vqe()               Hellmann-Feynman AD → ADAM → df_vqe_telemetry
+    ├─ run_md_simulation_dummy()     QM/MM dynamics → df_md_telemetry + Pearson matrix
+    └─ build_panel_*(res)            matplotlib figure → display()
+```
+
+---
+
+## ▍ Core Features
+
+| Feature | Detail |
+|---|---|
+| **Linear Kernel Fusion** | Stride-sliced tensor ops via JAX XLA — zero Kronecker matrices |
+| **Parametric Batch JIT** | `run_parametric_batch_jit()` evaluates full parameter grids in one `jax.vmap` + `jax.jit` call |
+| **Circuit Chunking** | Fixed-size JIT blocks eliminate tracer overhead on 1000+ gate circuits |
+| **Kraus Noise Channels** | `depolarizing` `amplitude_damping` `phase_damping` `bitflip` `combined` — stochastic, O(2ⁿ) cost |
+| **VQE + ADAM** | Hellmann-Feynman gradient · positional parameter injection into any OpenQASM 2.0 circuit |
+| **Anti-OOM Engine** | `SafeMemoryGuard` blocks execution before JAX raises `RESOURCE_EXHAUSTED` |
+| **Predictive Healing** | `healing.py` — Φ_AB alignment, dynamic vector, Σ-sync, `MemoryReflectionEngine` |
+| **Vector Sequence Healing** | `ia_utils/` — `median_healing`, `enhanced_dense_healing_hybrid` — NaN/Inf-safe, lazy JAX import |
+| **Backend Agnostic** | NumPy CPU · JAX XLA CPU/TPU · CuPy CUDA — runtime selection, zero code changes |
+| **Live Dashboard** | 8-panel ipywidgets telemetry: probability, VQE energy, entropy, purity, gradient, noise, θ-correction, Pearson heatmap |
+
+---
+
+## ▍ Scientific Validation & Applications
+
+To demonstrate the numerical accuracy and stability of **Dense Evolution**, the simulator was stress-tested across 3,500 continuous spatial sampling points to compute the **Silicon Dimer (Si2) Dissociation Curve** via Variational Quantum Eigensolver (VQE).
+
+* Physical Accuracy: The simulation successfully maps the exact Born-Oppenheimer Potential Energy Curve (PEC), capturing the deep quantum ground state bound minimum at ~3.55 Å with negative total energy, before converging asymptotically toward full molecular dissociation.
+* Numerical Precision: Calculations are locked at Double Precision (float64), proving the simulator's resilience against cumulative machine epsilon errors (~ 1.11 × 10⁻¹⁶) across thousands of sequential circuit executions.
+* Run this molecular experiment instantly on Google Colab Free Tier:
+  [Open Notebook on Google Colab](https://colab.research.google.com/drive/1cX7vYsVaxO29677ltgDTbh3pqUi0NYC5#scrollTo=Qg_lqX-Iw_UM)
+
+---
+
+```text
+============================================================
+🔬 MOLECULAR VQE: EXACT POTENTIAL ENERGY CURVE (PEC)
+============================================================
+Distanza R: 1.200 Å | Energia Totale Molecola: +155.761158 eV
+Distanza R: 1.671 Å | Energia Totale Molecola: +34.372692 eV
+Distanza R: 2.142 Å | Energia Totale Molecola: +6.583098 eV
+Distanza R: 2.614 Å | Energia Totale Molecola: +0.727422 eV
+Distanza R: 3.085 Å | Energia Totale Molecola: -0.253226 eV
+Distanza R: 3.557 Å | Energia Totale Molecola: -0.273498 eV
+Distanza R: 4.028 Å | Energia Totale Molecola: -0.170948 eV
+Distanza R: 4.500 Å | Energia Totale Molecola: -0.093048 eV
+```
+
+#### Variational Quantum Chemistry Plot
+Below is the physical validation plot showing the Born-Oppenheimer potential energy curve:
+
+<img width="993" height="593" alt="image" src="https://github.com/user-attachments/assets/5fe57865-40f2-4930-9e8d-63959ea93a22" />
+
+
+👉 *For the full suite of physical benchmarks, including the Transverse Field Ising Model (TFIM) and Phase Transition mappings, visit the main [Dense-Evolution-Ising-Tests](https://github.com/tatopenn-cell/Dense-Evolution-Ising-Tests) repository. You can also view the raw script for this specific molecular run [here](https://github.com/tatopenn-cell/Dense-Evolution-Ising-Tests/blob/main/vqe_silicon_molecular.py).*
+
+---
+
+## ▍ API Reference
+
+### `DenseSVSimulator`
+
+```python
+sim = DenseSVSimulator(
+    n_qubits   : int,
+    use_gpu    : bool = False,
+    use_float32: bool = False,
+)
+```
+
+| Method | Description |
+|---|---|
+| `set_initial_state(state=None)` | Reset to `\|0⟩ⁿ` or inject custom statevector |
+| `run_circuit_jit_beast_mode(circuit)` | JIT-compiled gate execution — primary execution path |
+| `run_circuit_with_chunking(circuit, chunk_size=500)` | Chunked execution for long circuits |
+| `run_parametric_batch_jit(base_circuit, parameter_batch)` | `vmap` over parameter grid — returns full batch of statevectors |
+| `get_probabilities()` → `np.ndarray` | `\|ψ_i\|²` for all basis states |
+| `get_statevector()` → `np.ndarray` | Full complex statevector |
+| `measure(qubit_idx)` → `int` | Projective measurement with state collapse |
+| `memory_mb()` → `float` | Current RAM usage in MB |
+| `apply_gate_1q(gate, qubit)` | Apply arbitrary 2×2 unitary |
+| `apply_gate_2q(gate, q1, q2)` | Apply arbitrary 4×4 unitary |
+
+### `QASMParser`
+
+```python
+parser  = QASMParser()
+circuit = parser.parse(qasm_str)   # → QASMCircuit
+valid, msg = parser.validate(circuit)
+```
+
+`QASMCircuit` fields: `n_qubits`, `n_cbits`, `ops` (list of gate tuples).
+
+### `NoiseModel`
+
+```python
+noise = NoiseModel()
+noise.apply(sv, model='depolarizing', p=0.01, n_qubits=4, rng=rng)
+desc  = NoiseModel.kraus_description('amplitude_damping')
+```
+
+### `Chunk` (Anti-OOM)
+
+```python
+sim = Chunk(
+    n_qubits         : int,
+    chunk_size_gates : int   = 500,
+    memory_threshold : float = 0.15,   # block below 15% free RAM
+    use_gpu          : bool  = False,
+    use_float32      : bool  = False,
+)
+sim.run_chunk(circuit, chunk_size_gates=500)
+```
+
+Backward-compatibility aliases: `chunk1 = MemoryChunker`, `chunk2 = Chunk`, `Chunk2Incrociato = Chunk`.
+
+### `ia_utils.vector_healing`
+
+```python
+from ia_utils.vector_healing import median_healing, enhanced_dense_healing_hybrid
+
+healed, radius   = median_healing(vettori, radius_baseline=None)
+healed, metadata = enhanced_dense_healing_hybrid(vettori, radius_baseline=None, median_fallback_threshold=0.1)
+```
+
+See **IA Utils — Vector Sequence Healing** above for details.
+
+---
+
+## ▍ Gate Library
+
+**Fixed gates** (no parameters):
+
+| Gate | Symbol | Gate | Symbol |
+|---|---|---|---|
+| `h` | Hadamard | `x` | Pauli-X |
+| `y` | Pauli-Y | `z` | Pauli-Z |
+| `s` | S gate | `sdg` | S† gate |
+| `t` | T gate | `tdg` | T† gate |
+| `sx` | √X gate | `id` | Identity |
+| `cx` | CNOT | `cz` | CZ |
+| `cy` | CY | `swap` | SWAP |
+| `iswap` | iSWAP | `ecr` | ECR |
+| `ccx` | Toffoli | | |
+
+**Parametric gates**:
+
+| Gate | Parameters | Description |
+|---|---|---|
+| `rx(θ)` | θ | X-rotation |
+| `ry(θ)` | θ | Y-rotation |
+| `rz(θ)` | θ | Z-rotation |
+| `p(λ)` | λ | Phase gate |
+| `u1(λ)` | λ | U1 (≡ p) |
+| `u2(φ, λ)` | φ, λ | U2 rotation |
+| `u3(θ, φ, λ)` | θ, φ, λ | Generic single-qubit |
+| `cp(λ, ctrl, tgt)` | λ | Controlled-Phase |
+| `crz(λ, ctrl, tgt)` | λ | Controlled-RZ |
+
+---
+
+## ▍ Noise Models
+
+All channels applied as post-circuit stochastic Kraus operations on the full statevector.
+
+| Model | Kraus operators | Physical process |
+|---|---|---|
+| `ideal` | `I` | Noiseless |
+| `depolarizing` | `{√(1−p)I, √(p/3)X, √(p/3)Y, √(p/3)Z}` | Isotropic Pauli error |
+| `amplitude_damping` | `{K₀=diag(1,√(1−γ)), K₁=[[0,√γ],[0,0]]}` | T₁ energy relaxation |
+| `phase_damping` | `{K₀, K₁}` | T₂ dephasing |
+| `bitflip` | `{√(1−p)I, √p·X}` | Bit flip σₓ |
+| `combined` | depolarizing(p/2) ∘ amplitude_damping(p/3) | Worst-case NISQ |
+
+Fidelity metrics computed on every noisy run: Bhattacharyya `F = Σᵢ √(pᵢqᵢ)` and TVD `= ½Σᵢ|pᵢ−qᵢ|`.
+
+---
+
+## ▍ Mitigation & Predictive Healing
+
+Active error tracking and stabilization integrated natively into the simulation runtime via `healing.py`.
+
+| Model | Operators | Description |
+|---|---|---|
+| `dephasing_tracking` | `Δ_pre_emp ∘ Σ` | Predictive deviation vs ideal eigenstate |
+| `phi_ab_alignment` | `Φ_AB(state_A, state_B, ipg)` | Semantic + coherence alignment between two quantum states |
+| `vettore_dinamico` | `V_din = K · log(E_B/E_A) · Φ_AB` | Log-differential energetic evolution vector |
+| `kappa_stabilization` | `κ-strength routine` | Proactive statevector profile shielding |
+| `richardson_integration` | `{λ₁=1.0, λ₂=2.0}` | Dual-point zero-noise trajectory approximation |
+
+All core functions compiled via `@jax.jit`. Event history managed by `MemoryReflectionEngine` with JAX Zero-Drift spectral aggregation.
+
+---
+
+## ▍ IA Utils — Vector Sequence Healing
+
+`ia_utils/vector_healing.py` — standalone module for cleaning sequences of vectors (e.g. hidden states / embeddings) that may contain `NaN` or `Inf` entries. Both functions preprocess the input (Inf → NaN → column-mean imputation) before healing, so corrupted values never propagate into the output.
+
+| Function | Approach | Returns |
+|---|---|---|
+| `median_healing(vettori, radius_baseline=None)` | `scipy.ndimage.median_filter`, dynamic radius `min(20, max(3, n // 3))` | `(healed: np.ndarray, radius: int)` |
+| `enhanced_dense_healing_hybrid(vettori, radius_baseline=None, median_fallback_threshold=0.1)` | Blends the `dense_evolution.healing` Φ-trigger logic with a median fallback, decided per-step | `(healed: np.ndarray, metadata: dict)` |
+
+`enhanced_dense_healing_hybrid` metadata:
+
+| Key | Type | Description |
+|---|---|---|
+| `fallback_triggered` | `bool` | `True` if the median fallback or dense blending fired at least once |
+| `adaptive_radius_used` | `int` | Baseline radius actually applied |
+| `reconstruction_error` | `float` | Mean norm of the correction applied vs. the sanitized input |
+
+```python
+import numpy as np
+from ia_utils.vector_healing import median_healing, enhanced_dense_healing_hybrid
+
+vettori = np.random.default_rng(0).normal(size=(50, 128))
+vettori[10, 3] = np.nan          # simulate a corrupted hidden state
+vettori[30, 7] = np.inf
+
+healed, radius = median_healing(vettori)
+
+healed_hybrid, meta = enhanced_dense_healing_hybrid(vettori)
+print(meta)
+# {'fallback_triggered': True, 'adaptive_radius_used': 16, 'reconstruction_error': 11.48}
+```
+
+`jax` is imported lazily inside `enhanced_dense_healing_hybrid` — `median_healing` and the module import itself work without the `[jax]` extra installed; only calling `enhanced_dense_healing_hybrid` requires it.
+
+---
+
+## ▍ Anti-OOM Chunk Engine
+
+All operations parcellized dynamically using a 4-layer architectural shield.
+
+| Layer | Class | Role |
+|---|---|---|
+| 1 | `SafeMemoryGuard` | Pre-allocation RAM check — blocks before JAX raises `RESOURCE_EXHAUSTED` |
+| 2 | `MemoryChunker` | Geometry calculator — computes `num_chunks`, `chunk_dim`, `chunk_size_bits` from available RAM without any JAX allocation |
+| 3 | `CircuitChunker` | Per-slice execution — `SafeMemoryGuard` fires before every gate-slice dispatch |
+| 4 | `Chunk` | Top-level wrapper — logical n_qubits decoupled from physical allocation at `safe_qubits` |
+
+### Benchmark vs PennyLane — Windows CPU (8 GB RAM)
+
+> Dense Evolution maintains constant ~2 GB RAM at any qubit count via dynamic chunking.
+> PennyLane allocates the full statevector — OOM beyond 26q.
+
+| Qubits | Hilbert Space | PennyLane | PennyLane RAM | Dense Evolution | Dense RAM | Chunk Geometry |
+|:------:|:-------------:|:---------:|:-------------:|:---------------:|:---------:|:--------------:|
+| 24 | 16,777,216 | ✅ | 307 MB | ✅ | 516 MB | 1× (2²⁷) |
+| 26 | 67,108,864 | ✅ | 1,074 MB | ✅ | 2,050 MB | 1× (2²⁷) |
+| 28 | 268,435,456 | ❌ OOM | — | ✅ | 2,050 MB | 2× (2²⁷) |
+| 30 | 1,073,741,824 | ❌ OOM | — | ✅ | 2,048 MB | 8× (2²⁷) |
+| 32 | 4,294,967,296 | ❌ OOM | — | ✅ | 2,048 MB | 32× (2²⁷) |
+
+```python
+from dense_evolution import Chunk
+
+sim = Chunk(27)
+sim.run_chunk([['h', i] for i in range(27)], chunk_size_gates=500)
+
+print(sim)
+# Chunk(n_qubits=27, safe_qubits=27, num_chunks=1,
+#       chunk_size_bits=27, mem_per_chunk=2048.0 MB, ram_free=42.3%, has_jax=True)
+```
+
+---
+
+## ▍ Benchmarks
+
+> Measured on Google Colab Free Tier (CPU runtime)
+
+| Metric | Value |
+|---|---|
+| Numerical drift (30-layer Ansatz, 1360 gates) | `Δ = 1.11 × 10⁻¹⁶` |
+| Memory footprint @ 20q | `32 MB` (float64) · `16 MB` (float32) |
+| JIT compile overhead (first run) | `< 400 ms` |
+| Gate throughput after warm-up | `> 10⁶ gates/s` (CPU) |
+| Maximum tested qubits (Colab Free) | `24q` stable · `33q` high-RAM runtime |
+| Anti-OOM latency reduction (static JIT cache) | `−86.47%` |
+
+---
+
+## ▍ Dashboard Panels
+
+| Panel | Contents |
+|---|---|
+| **Overview** | R0 header · R1 P(\|n⟩) histogram + Top-12 states · R2 wavefunction helix 3D + metrics table · R3 noise analysis + shot histogram · R4–R6 VQE telemetry ×3 · R7 Pearson heatmap |
+| **Fisica Stato** | Bloch projection · Schmidt rank · coherence vector |
+| **Mosaico** | 2D probability density map up to 1008 qubits |
+| **VQE Results** | 6-subplot: energy convergence, entropy, purity, ‖∇L‖, noise factor, θ-correction |
+| **MD Results** | 6-subplot MD telemetry + masked Pearson correlation heatmap |
+| **Performance** | Gate throughput · JIT compile time · RAM usage |
+
+---
+
+## ▍ VQE Engine
+
+**Positional parameter injection** — `QASMParser` tokenizes all literals to `0.0` for JIT speed. VQE recovers parameters by:
+1. Counting parametric gates (`rx ry rz p u1 cp crz`) → `n_params`
+2. Initializing `θ ∈ ℝⁿ` uniform in `[−π, π]`
+3. Injecting `θ[i]` sequentially by gate order in the AST via `risolvi_qasm()`
+
+Compatible with any custom OpenQASM 2.0 string without pre-labelling.
+
+**Gradient & update rule:**
+
+$$\frac{\partial E}{\partial \theta_i} = \left\langle\psi(\theta)\left|\frac{\partial H}{\partial \theta_i}\right|\psi(\theta)\right\rangle \qquad \theta \leftarrow \theta - \frac{\alpha\,\hat{m}_t}{\sqrt{\hat{v}_t}+\varepsilon}$$
+
+**Telemetry columns** (→ `df_vqe_telemetry`):
+
+| Column | Unit | Description |
+|---|---|---|
+| `VQE_Energy` | Ha | ⟨ψ\|H\|ψ⟩ |
+| `Entropy` | bit | −Tr(ρ log₂ ρ) |
+| `Purity` | — | Tr(ρ²) ∈ [1/d, 1] |
+| `Gradient` | — | ‖∇L‖ — barren plateau detection |
+| `Noise_Factor` | — | Fidelity-derived noise proxy |
+| `Theta_Correction` | rad | ADAM step norm |
+
+---
+
+## ▍ Hamiltonian Library
+
+Auto-filtered by qubit count to prevent shape mismatch.
+
+| Molecule | Qubits | Bond length | E₀ (Ha) |
+|---|:---:|:---:|:---:|
+| H₂ | 2 | 0.74 Å | −1.13 |
+| H₃⁺ | 3 | 0.85 Å | −1.28 |
+| LiH | 4 | 1.40 Å | −2.31 |
+| H₂O | 5 | 0.96 Å | −4.12 |
+
+Custom: JSON array of diagonal eigenvalues, length `2^n_qubits`.
+
+---
+
+## ▍ Circuit Library (30+ presets)
+
+All circuits stored as OpenQASM 2.0 strings in `QASM_LIBRARY`.
+
+**Standard** — Bell Φ⁺, QFT 4q/8q, Toffoli, Adder 2-bit, Deutsch-Jozsa, Bernstein-Vazirani
+
+**Algorithms** — Grover 3q/4q, Simon 4q, Shor 15, HHL, QAOA Max-Cut 4q, QPE 5q, Quantum Walk, Teleportation, BB84
+
+---
+
+## ▍ Changelog
+
+### v8.1.8
+- **Fixed**: `parser.py` — controlled two-qubit gates (`cx`/`cy`/`cz`/`cp`/`crz`) parsed from QASM in the dashboard layer had control and target swapped relative to `compiler.py`'s documented `(gate, control, target)` contract, breaking entanglement for circuits run through the dashboard. The core `QASMCircuit.to_tuples()` path was already correct.
+- **Fixed**: `parser.py` — range syntax (`q[0:3]`) on single-qubit gates only applied to the first qubit in the range, silently dropping the rest. Now expands into one gate application per qubit, matching the parser's own documented contract.
+- **Fixed**: `from dense_evolution import Chunk` raised `ImportError` — `Chunk` is now re-exported from the package root. Added `get_probabilities()`/`get_statevector()` to `Chunk` for parity with `DenseSVSimulator`.
+- **Removed**: `dense_evolution/test2.py` and `stress_test.py` — byte-identical, assertion-free debug scripts that shipped inside every install with 0% test coverage. Their one real check (Kraus noise is genuinely stochastic across independent runs) is now a real regression test.
+
+### v8.1.7
+- `ia_utils/` — new package: `median_healing`, `enhanced_dense_healing_hybrid` for vector sequence healing (NaN/Inf-safe)
+- `jax` import in `ia_utils.vector_healing` made lazy — importable without the `[jax]` extra
+- Fixed `reconstruction_error` telemetry returning `NaN` when input contained `NaN`/`Inf`
+- Added `scipy` to core dependencies (was used but undeclared)
+
+### v8.1.6
+- Modular package structure (`dense_evolution/` directory)
+- Split `registry.py`, `gates.py`, `healing.py`, `chunk.py` into dedicated modules
+
+### v8.1.5
+- `chunk.py` — `SafeMemoryGuard`: hard block at configurable free-RAM threshold (default 15%), soft warning at 2× threshold, `gc.collect()` before every check
+- `chunk.py` — `Chunk` no longer subclasses `DenseSVSimulator`; inner simulator allocated at `safe_qubits` only — eliminates `RESOURCE_EXHAUSTED` on 28q–34q circuits
+- `chunk.py` — `CircuitChunker.split_circuit` RAM-checks every gate-slice before dispatch
+- `chunk.py` — `MemoryChunker` attributes (`num_chunks`, `chunk_size_bits`, `dtype`) forwarded as `@property` on `Chunk` for benchmark compatibility
+
+### v8.1.0
+- `healing.py` — Predictive State Engine: `calculate_phi_ab`, `calculate_vettore_dinamico`, `calculate_delta_preemp`, `evaluate_phi_trigger`, `calculate_jax_reflection` — all `@jax.jit`
+- `MemoryReflectionEngine` — event logging + JAX Zero-Drift spectral aggregation
+
+### v8.0.x
+- `run_parametric_batch_jit()` — `jax.vmap` over full parameter grids in single XLA call
+- `run_circuit_jit_beast_mode()` — static JIT compilation with QuantumTranspiler
+- OpenQASM 2.0/3.0 dual-mode parser with paren-depth-aware expression splitting
+- `NoiseModel` Kraus channels in `registry.py`
+
+---
+
+## ▍ License
+
+**Business Source License 1.1** — converts automatically to **Apache 2.0** on **1 June 2029**.
+
+- Non-commercial use: unrestricted
+- Commercial use: ≤ 24 allocated qubits · ≤ 1,000 circuits/day · ≤ 10,000 shots/circuit
+- Attribution required: `© 2026 Salvatore Pennacchio <jtatopenn@libero.it> — Dense Evolution`
+
+Full text: [LICENSE.md](LICENSE.md)
+
+---
+
+<div align="center">
+  <sub>© 2026 Salvatore Pennacchio — Dense Evolution</sub>
+</div>