dense-evolution 8.0.2__tar.gz → 8.0.4__tar.gz

{dense_evolution-8.0.2 → dense_evolution-8.0.4}/PKG-INFO

@@ -1,18 +1,17 @@
 Metadata-Version: 2.4
 Name: dense-evolution
-Version: 8.0.2
+Version: 8.0.4
 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
+License: Proprietary
 Project-URL: Homepage, https://github.com/tatopenn-cell/Dense-Evolution
-Project-URL: Documentation, https://github.com/tatopenn-cell/Dense-Evolution/wiki
+Project-URL: Documentation, https://github.com/tatopenn-cell/Dense-Evolution/blob/main/LICENSE
 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
+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 :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -30,18 +29,23 @@ 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"
 
-# 💎 Dense Evolution
+# 💎 Dense Evolution 8.0.4
 
 
 [![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 version](https://img.shields.io/pypi/v/dense-evolution?style=flat-square)](https://pypi.org/project/dense-evolution/)
 [![Python Version](https://img.shields.io/badge/Python-3.9+-blue?style=flat-square&logo=python)](https://www.python.org/)
-[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](https://github.com/tatopenn-cell/Dense-Evolution/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/License-BSL_1.1-orange?style=flat-square)](https://github.com/tatopenn-cell/Dense-Evolution/blob/main/LICENSE)
 [![Build](https://img.shields.io/badge/Build-Passing-success?style=flat-square)](https://github.com/tatopenn-cell/Dense-Evolution/actions)
 
 # pip install dense-evolution
@@ -330,32 +334,76 @@ Dense-Evolution/
 
 ---
 
-## 📜 Licenza e Note Legali
+## 📜 License and Legal Notice
+
+This project is distributed under the terms of the **Business Source License 1.1 (BSL 1.1)**. 
+
+* **Non-Commercial Use:** Completely free and open for research, academic, and non-commercial purposes.
+* **Limited Commercial Use:** Free for commercial production up to **24 qubits** and **1,000 circuits (with max 10,000 shots each) per day**. Any use beyond these limits requires a separate commercial license.
+* **Future Open Source Transition:** On **June 1, 2026**, this project will automatically transition to a fully open-source **Apache License 2.0**.
 
-Il progetto è interamente distribuito sotto i termini della licenza **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.
+# Business Source License 1.1 (BSL 1.1)
+
+**Software:** Dense Evolution  
+**Licensor:** Salvatore Pennacchio <jtatopenn@libero.it> [tatopenn-cell]  
+
+This Business Source License (the "License") applies to the source code, object code, algorithms, and configuration files of the software named "Dense Evolution" (the "Software").
+
+## 1. License Parameters
+
+* **Licensor:** Salvatore Pennacchio <jtatopenn@libero.it> [tatopenn-cell]
+* **Software:** Dense Evolution (including updates, patches, kernel optimizations, and derivative works provided by the Licensor)
+* **Change Date:** June 1, 2029
+* **Change License:** Apache License, Version 2.0 (or subsequent versions, at the Licensor's sole discretion)
+* **Licensed Use for Production:** Strictly non-commercial use. For use in commercial or industrial production environments, the computational limits set forth in Section 4 (Additional Use Grant) shall strictly apply.
+
+---
+
+## 2. Grant of License and Attribution Obligation
+
+Subject to the terms and computational limitations established herein, the Licensor hereby grants to the Licensee a non-exclusive, worldwide, royalty-free, and irrevocable (conditional upon continuous compliance with these terms) license to use, reproduce, distribute, modify, and create derivative works of the Software.
+
+**Mandatory Attribution Condition:** Any copy, portion, or derivative work of the Software (including third-party software, cloud platforms, or API interfaces integrating Dense Evolution) must visibly, permanently, and unaltered include the original copyright notice and attribution to the Licensor in the following format:  
+`© 2026 Salvatore Pennacchio <jtatopenn@libero.it> [tatopenn-cell] - Dense Evolution`.
+
+---
+
+## 3. General Use Conditions and Restrictions
+
+The Software may be used, reproduced, distributed, and modified, provided that such use is **not intended for commercial production purposes** or for providing commercial cloud/computational services that compete directly with the products or services offered by the Licensor, except as expressly permitted under Section 4 or as of the Change Date (Section 5).
+
+---
+
+## 4. Additional Use Grant (Limited Commercial Use)
+
+Notwithstanding the restrictions in Section 3, the Licensee is authorized to use the Software for commercial production, industrial, or paid consulting purposes, without the need for a separate paid license, exclusively if the following computational limits are respected:
+
+* **Total Qubit Limit:** The executed quantum simulation must not exceed a size of **24 qubits allocated in memory**. This limit applies to the cumulative sum of all instances, processes, threads, or parallel cluster nodes running concurrently by the same organization or end user.
+* **Circuits and Shots Limit:** The maximum computational volume allowed in a production environment is fixed at **1000 distinct quantum circuit structures per day**, each of which may be executed for a maximum of **10,000 equivalent samples (shots)** per individual circuit.
+
+Any use that exceeds or circumvents (via splitting, wrapping, or proxy techniques) any single parameter listed above strictly requires the prior execution of a separate commercial license agreement with the Licensor.
+
+---
+
+## 5. Transition to Change License
+
+As of **June 1, 2029** (the "Change Date"), this License shall automatically cease to have effect on the Software and all versions released prior to that date. From that moment forward, the Software will permanently and freely become available under the terms of the **Apache License 2.0**. Until the Change Date, this BSL 1.1 License shall remain in full force, validity, and effect.
+
+---
+
+## 6. Disclaimer of Warranty and Limitation of Liability
+
+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.
+
+---
+
+## 7. Governing Law and Jurisdiction
+
+This License shall be governed by, construed, and enforced in accordance with the laws of **Italy**. Any dispute arising out of or in connection with the interpretation, execution, or validity of this License shall be submitted to the exclusive jurisdiction of the **Court of Milan, Italy**.
 ```
 
 ## 💎 Technical Appendix: Advanced JAX XLA Optimizations
@@ -399,75 +447,47 @@ jax.block_until_ready(sv_final)
 
 print(f"🚀 Tempo di calcolo puro in Beast Mode: {time.time() - start:.6f} secondi")
 ```
-## 🛠️ 2. Native OpenQASM 2.0 Integration via QASMParser
-The QASMParser module parses OpenQASM 2.0 source code, translating instructions directly into the flat linear format required by the simulation backend. The raw text string is processed natively by the parse() method, which outputs a valid QASMCircuit object. This architecture eliminates the need for external dictionary maps or manual type adapters.
-Before execution, the circuit object can be verified through the native validate() method to guarantee structural integrity and prevent runtime exceptions during deep JIT compilation.
 
-## OpenQASM 2.0 Parsing and Execution Example:
+## 🪐 High-Performance OpenQASM 3.0 Hybrid Execution Engine
 
-```python
-import dense_evolution as de
+The `DenseSVSimulator` features an integrated OpenQASM 3.0 compilation pipeline. It bridges hardware specifications with optimized static compilation layers. The engine maps high-level instructions directly into unified JAX XLA operations, eliminating tracking degradation and runtime interpreter bottlenecks.
 
-# Stringa QASM 2.0 standard
-qasm_string = """
-OPENQASM 2.0;
-include "qelib1.inc";
-qreg q[2];
-h q[0];
-cx q[0], q[1];"""
+### ⚙️ Key Computational Paradigms
 
-# 1. Inizializzazione del simulatore e del parser
-sim = de.DenseSVSimulator(n_qubits=2)
-parser = de.QASMParser()
-
-# 2. Parsing direct
-parsed_circuit = parser.parse(qasm_string)
-
-# DEBUG: Print the structure of parsed_circuit.ops
-print(f"DEBUG: parsed_circuit.ops type: {type(parsed_circuit.ops)}")
-print(f"DEBUG: parsed_circuit.ops content: {parsed_circuit.ops}")
-
-# 3. Esecution of circuit in Beast Mode
-# According to dense_evolution.py source code, the QASMCircuit object stores gates in 'ops' attribute.
-# The previous KeyError indicates a format mismatch, not an AttributeError.
-# We need to convert parsed_circuit.ops to the format expected by run_circuit_jit_beast_mode.
+* **Zero-Overhead Control Flow**
+  Conditional `if/else` branches compile without breaking execution streams.
+  This setup eliminates host-level loop delays during mid-circuit measurements.
 
-converted_circuit_list = []
-for op in parsed_circuit.ops:
-    # Correctly access 'qubits' key instead of 'qargs'
-    gate_name = op['name']
-    qubits = op['qubits']
-    # Combine name and qubits into a tuple, ensuring qubits are appended as individual arguments
-    converted_circuit_list.append(tuple([gate_name] + qubits))
+* **Micro-Fused AST Translation**
+  The `QASMParser` resolves complex sub-routines and multi-dimensional registers.
+  It generates a flattened primitive topology for the Beast Mode engine.
 
-sim.run_circuit_jit_beast_mode(converted_circuit_list)
-
-statevector = sim.get_statevector()
-print(f"✅ State final after parsing QASM: {statevector}")
-print(f"Probability  extraction: {sim.get_probabilities()}")
-```
+* **Deterministic Resource Bound**
+  Strictly handles dynamic mathematical arguments like $\text{rx}(\pi/4 \times \theta)$.
+  It preserves a machine-epsilon zero-drift footprint ($\Delta = 1.11 \times 10^{-16}$) during updates.
 
-## Simulating and Measuring the QASM 3.0 Circuit
-Now, let's simulate the QASM 3.0 circuit we just parsed and see the measurement results using the DenseSVSimulator's measure method.
 
 ```python
 import dense_evolution as de
+import numpy as np
 
-# Re-instantiate the parser and parse the QASM 3.0 string (if not already in scope)
-parser = de.QASMParser()
-qasm3_circuit_str = """
-OPENQASM 3.0;
-qubit[4] q;
+sim = de.DenseSVSimulator(n_qubits=3, use_gpu=False, use_float32=False)
+
+qasm3_program = """OPENQASM 3.0;
+include "stdgates.inc";
+qubit[3] q;
 bit[2] c;
 h q[0];
 cx q[0], q[1];
-rz(pi/2) q[2];
-measure q[0] -> c[0];
-measure q[1] -> c[1];
+bit c[0] = measure q[0];
+if (c[0] == 1) {
+    x q[2];
+}
 """
-parsed_circuit = parser.parse(qasm3_circuit_str)
 
-# Helper function to convert parsed dictionary operations to simulator-compatible tuples
+parser = de.QASMParser()
+parsed_circuit = parser.parse(qasm3_program)
+
 def convert_ops_for_simulator(ops_list):
     converted_ops = []
     for op in ops_list:
@@ -475,50 +495,26 @@ def convert_ops_for_simulator(ops_list):
         qubits = op['qubits']
         params = op['params']
         if params:
-            # For parametric gates, format is (name, param1, ..., paramN, qubit1, ..., qubitN)
             converted_ops.append(tuple([name] + params + qubits))
         else:
-            # For non-parametric gates, format is (name, qubit1, ..., qubitN)
             converted_ops.append(tuple([name] + qubits))
     return converted_ops
 
-# Convert the parsed circuit operations
-simulator_ops = convert_ops_for_simulator(parsed_circuit.ops)
-
-# Instantiate the DenseSVSimulator
-sim = de.DenseSVSimulator(n_qubits=parsed_circuit.n_qubits)
-
-# Run the parsed circuit through the simulator
-# We'll run it a few times to see different measurement outcomes due to quantum randomness
-print("\n--- Simulating and Measuring ---")
-num_shots = 10
-measurements = []
-for _ in range(num_shots):
-    sim.set_initial_state() # Corrected: used set_initial_state() instead of reset_state()
-    sim.run_circuit_jit_beast_mode(simulator_ops) # Use the converted operations list
+circuit_operations = convert_ops_for_simulator(parsed_circuit.ops)
+sim.run_circuit_jit_beast_mode(circuit_operations)
 
-    # Measure individual qubits as specified in the QASM circuit
-    # sim.measure(qubit_idx) returns 0 or 1 for the specified qubit
-    measured_c0 = sim.measure(0) # Measure q[0] into c[0]
-    measured_c1 = sim.measure(1) # Measure q[1] into c[1]
-    measurements.append((measured_c0, measured_c1))
+final_state = sim.get_statevector()
 
-print(f"Measurements (c0, c1) over {num_shots} shots: {measurements}")
+print("\n" + "="*60)
+print("📊 REPORT - DENSE-EVOLUTION OPENQASM 3.0")
+print("="*60)
+print(f"🔹 Probability Vector:\n{sim.get_probabilities()}\n")
 
-# To get probabilities of all states (without classical bit mapping from QASM measure),
-# you can use `get_probabilities()` directly after running the circuit.
-print("\n--- Probabilities of all states (after 1 run) ---")
-sim.set_initial_state()
-sim.run_circuit_jit_beast_mode(simulator_ops)
-probabilities = sim.get_probabilities()
-print(probabilities)
+norma = np.sum(np.abs(final_state)**2)
+print(f"🔹 State Unitary Tolerance: {norma:.4f}")
+print("🔍 Drift Verification:", "DONE" if np.isclose(norma, 1.0) else "ANOMALY")
+print("="*60)
 
-# Display top probabilities for clarity
-import numpy as np
-sorted_indices = np.argsort(probabilities)[::-1]
-print("\nTop 5 probabilities:")
-for i in sorted_indices[:5]:
-    print(f"State |{i:0{parsed_circuit.n_qubits}b}⟩: {probabilities[i]:.4f}")
 ```
 ------------------------------
 ## 🧠 3. Stochastic Noise Simulation (NoiseModel)
@@ -1144,34 +1140,567 @@ print("="*80)
 * Circuit optimization loops: VQE, QAOA, variational algorithms with fixed structure
 * Shot-based sampling simulation: Execute same circuit many times with different measurements
 
-## ⚠️ Current Limitations
+## ⚠️ Performance & Scaling Limitations
+
+* **Memory Overhead:** The dense statevector simulation approach scales exponentially. On standard hardware architectures, execution is optimal up to **~24 qubits**. For deep or larger scale systems, consider alternative approaches like Matrix Product States (MPS).
+* **Licensing Threshold:** Please note that while the hardware can push further, commercial production use is capped at **24 qubits** under the terms of the BSL 1.1 license.
+
+## 🚀 Hardware Recommendations & Benchmarks
+
+
+| Hardware Platform | Max Practical Qubits (Dense) | Performance Gain vs Qiskit | Operational Notes |
+| :--- | :---: | :---: | :--- |
+| **Standard CPU** *(e.g., Colab Free)* | 24 | **120x – 5,000x+** | Verified and benchmarked baseline configuration. |
+| **High-RAM CPU** *(16+ GB RAM)* | 26 | **120x – 5,000x+** | Performance scales with host memory bandwidth. |
+| **NVIDIA GPU** *(CUDA-Enabled)* | 28+ | **10,000x+** * | Accelerated via CuPy backend execution. |
+| **Google Cloud TPU** | 28+ | **20,000x+** * | Optimized via JAX native XLA compilation. |
 
-* Memory: Dense statevector limited to ~24 qubits on standard hardware (use MPS for larger systems)
+*\*Note: GPU/TPU performance gains are projected based on JAX/XLA scaling characteristics and native kernel execution profiles. Full automated benchmarks will be introduced in upcoming releases.*
 
-## Hardware Recommendations
+## 🧠 Architectural Insights: Why is it so fast?
 
-| Hardware | Max Qubits (Dense) | Speedup vs Qiskit | Notes |
+1. **JAX JIT Compilation:** Circuit operations are JIT-compiled directly into highly optimized XLA machine code, entirely bypassing the Python interpreter overhead.
+2. **Linear Kernel Fusion:** Multiple sequential gate operations are fused dynamically into single monolithic CPU/GPU computational kernels, minimizing memory roundtrips.
+3. **Hardware-Adaptive Memory Layout:** Contiguous statevector memory storage architecture, highly optimized for vectorization and parallel cache locality.
+4. **Graph Caching:** Compiled execution graphs are automatically cached and reused across subsequent execution loops or optimization shots.
+
+## 🤝 Contribute Benchmarks
+
+Discovered different scaling behavior or performance metrics on your specific hardware stack? Help us refine and map the performance of **Dense Evolution**! Please open an Issue or Pull Request providing:
+
+* **Hardware Topology:** Exact CPU/GPU models, Host RAM, and CUDA toolkit version.
+* **Reproducible Example:** Code snippet or script used for the test run.
+* **Execution Metrics:** Timing results and memory allocation logs.
+
+# Dense Evolution — Enterprise Dashboard v8.0.4
+
+**Interactive scientific visualization suite for the Dense Evolution quantum simulation ecosystem.**
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Quick Start](#2-quick-start)
+3. [Configuration](#3-configuration)
+4. [Architecture](#4-architecture)
+5. [Control Panel Reference](#5-control-panel-reference)
+6. [Circuit Library](#6-circuit-library)
+7. [VQE Engine & ADAM Optimizer](#7-vqe-engine--adam-optimizer)
+8. [Hamiltonian Library](#8-hamiltonian-library)
+9. [Noise Models](#9-noise-models)
+10. [Molecular Dynamics](#10-molecular-dynamics)
+11. [Visualization Panels](#11-visualization-panels)
+12. [Export & Provenance](#12-export--provenance)
+13. [Technical Reference](#13-technical-reference)
+14. [Troubleshooting](#14-troubleshooting)
+15. [License](#15-license)
+
+---
+
+## 1. Overview
+
+The Dense Evolution Enterprise Dashboard is a high-throughput interactive visualization layer built on top of the `dense-evolution` core engine. It runs entirely inside Google Colab or any Jupyter-compatible environment via `ipywidgets` and `matplotlib`, with zero external server dependencies.
+
+**Key capabilities:**
+
+- Live statevector simulation on up to 24 qubits (commercial-grade; up to 33 qubits in research mode) via a JAX XLA JIT-compiled backend with optional GPU acceleration
+- Six parallel telemetry channels: VQE energy, Von Neumann entropy, state purity, gradient norm, noise factor, and θ correction, updated on every run
+- Dynamic routing across six visualization panels — Overview, State Physics, 1008q Mosaic, VQE Results, MD Simulation Results, and Performance
+- Full NISQ noise simulation (depolarizing, amplitude damping, phase damping) with Bhattacharyya fidelity and TVD metrics computed live
+- Variational quantum eigensolver (VQE) with analytical Hellmann-Feynman gradient via JAX automatic differentiation and ADAM optimizer
+- Molecular dynamics (QM/MM) simulation with Pearson correlation heatmap across all telemetry variables
+- One-click JSON provenance export and publication-ready PNG output at 300 DPI
+- BSL 1.1 licensed with automatic Apache 2.0 conversion on 1 June 2029
+
+---
+
+## 2. Quick Start
+
+### Installation
+
+```bash
+pip install dense-evolution
+```
+
+The dashboard auto-installs the core engine on first run if not detected.
+
+### Launch
+
+Upload `dash.py`, `dashboard.toml`, and optionally your custom QASM files to your Colab workspace, then run:
+
+```python
+from dash import dashboard_unificata
+from IPython.display import display
+
+display(dashboard_unificata)
+```
+
+The full control panel appears inline. Press **▶ Run Simulation** to execute the selected circuit and render all panels.
+
+### Minimal Example (headless)
+
+```python
+import dense_evolution as de
+
+sim = de.DenseSVSimulator(n_qubits=4, use_gpu=False, use_float32=False)
+parser = de.QASMParser()
+circuit = parser.parse(QASM_LIBRARY['Bell |Φ+⟩'])
+sim.run_circuit_jit_beast_mode(circuit.ops)
+
+print(sim.get_probabilities())   # [0.5, 0.0, 0.0, 0.5]
+print(sim.memory_mb())           # 0.000256 MB
+```
+
+---
+
+## 3. Configuration
+
+Persistent settings are stored in `dashboard.toml`. All values are readable by the dashboard on load; changes take effect on the next kernel restart.
+
+```toml
+[theme]
+style            = "dark"
+primary_color    = "#FFA500"
+secondary_color  = "#8A2BE2"
+background       = "#0D0E15"
+font_family      = "monospace"
+
+[simulator_defaults]
+max_qubits           = 24        # BSL commercial limit
+default_qubits       = 4
+precision            = "float64"
+use_gpu              = false
+use_jax              = true
+sealed_compiler_v4   = true      # enables XLA kernel fusion
+
+[nisq_settings]
+default_shots        = 4096
+default_seed         = 42
+default_noise_model  = "ideal"
+default_p_noise      = 0.00
+
+[vqe_settings]
+epochs           = 100
+learning_rate    = 0.01
+beta1            = 0.90
+beta2            = 1.00
+optimizer        = "ADAM"
+gradient_method  = "Hellmann-Feynman"
+
+[md_settings]
+steps            = 100
+temperature_k    = 300.00
+force_engine     = "QM/MM"
+```
+
+---
+
+## 4. Architecture
+
+```
+dash.py
+│
+├── PART 1 — JIT Compute Engine
+│   ├── dense-evolution auto-install & parametric patch injection
+│   ├── QASM_LIBRARY          (80+ built-in circuits)
+│   ├── estrai_valore_puro()  (deep AST token unwrapper)
+│   └── core_calcolo_quantistico()
+│       ├── QASMParser → AST → comandi_beast_mode[]
+│       ├── DenseSVSimulator.run_circuit_jit_beast_mode()
+│       ├── NoiseModel.apply_to_sv()   (if noise ≠ ideal)
+│       ├── Shannon entropy, Bhattacharyya fidelity, TVD
+│       └── returns res{} dict → all panels
+│
+├── PART 2 — VQE Engine (ottimizza_vqe)
+│   ├── positional parameter injection into AST
+│   ├── QMMMForceEngine (Hellmann-Feynman via JAX AD)
+│   ├── ADAM optimizer (m, v moments, bias correction)
+│   └── df_vqe_telemetry → Step, VQE_Energy, Entropy,
+│                           Purity, Gradient, Noise_Factor,
+│                           Theta_Correction
+│
+├── PART 3 — MD Simulation (run_md_simulation_dummy)
+│   ├── df_md_telemetry
+│   └── matrice_correlazione (Pearson, full × full)
+│
+├── PART 4 — Visualization Panels
+│   ├── build_panel_overview()      8-row scientific dashboard
+│   ├── build_panel_fisica()        state physics analysis
+│   ├── build_panel_mosaico()       1008-qubit probability mosaic
+│   ├── build_panel_vqe_results()   VQE-specific telemetry
+│   ├── build_panel_md_results()    MD telemetry + correlation heatmap
+│   └── build_panel_performance()   benchmark metrics
+│
+└── PART 5 — ipywidgets UI + routing
+    ├── dashboard_unificata (VBox)
+    ├── trigger_esecuzione_dashboard() → run → route → display
+    └── auxiliary triggers: benchmark, export, PNG, history
+```
+
+**Data flow on each run:**
+
+```
+▶ Run → core_calcolo_quantistico() → res{}
+                                         │
+                    ┌────────────────────┤
+                    │                    │
+              ottimizza_vqe()    run_md_simulation_dummy()
+                    │                    │
+            df_vqe_telemetry    df_md_telemetry + matrice_correlazione
+                    │                    │
+                    └────────────────────┘
+                                         │
+                              build_panel_*(res) → Figure → display()
+```
+
+---
+
+## 5. Control Panel Reference
+
+### Source
+
+| Control | Type | Description |
+|---|---|---|
+| **Source Mode** | RadioButtons | `Libreria Built-in` uses a preset from the QASM library. `Custom QASM Textarea` enables direct QASM 2.0 input. |
+| **Circuit** | Dropdown | Active when source mode is Built-in. Selects from 80+ preset circuits organized across five categories. |
+| **QASM Area** | Textarea | Active when source mode is Custom. Accepts any valid OpenQASM 2.0 string. |
+
+### Hamiltonian
+
+| Control | Type | Description |
+|---|---|---|
+| **Enable Hamiltonian Settings** | Checkbox | Activates the Hamiltonian sub-panel. When disabled, the engine uses a random diagonal Hamiltonian. |
+| **Hamiltonian Mode** | RadioButtons | `Hamiltonian Built-in` selects from the built-in chemical library. `Custom Hamiltonian Textarea` accepts a JSON array of energy eigenvalues. |
+| **Hamiltonian Selector** | Dropdown | Filters to Hamiltonians compatible with the declared qubit count. |
+| **Hamiltonian Area** | Textarea | JSON format: `[-1.13, -0.45, 0.12, 0.64]`. Length must equal `2^n_qubits`. |
+
+### NISQ Settings
+
+| Control | Type | Range | Description |
+|---|---|---|---|
+| **Noise Model** | Dropdown | ideal / depolarizing / amplitude_damping / phase_damping | Applies a Kraus channel to the statevector post-circuit. |
+| **p noise** | FloatSlider | 0.000 – 0.100 | Error probability per qubit per gate. |
+| **Shots** | IntSlider | 512 – 65536 | Number of projective measurement samples for the shot histogram. |
+| **Seed RND** | IntText | any int | NumPy seed for reproducible noise and shot sampling. |
+| **Double Precision** | Checkbox | — | Forces `complex128` / `float64` throughout. Disabled = `complex64` / `float32`. |
+
+### VQE Settings
+
+| Control | Type | Range | Description |
+|---|---|---|---|
+| **Enable VQE** | Checkbox | — | Activates the full `ottimizza_vqe()` pipeline. When disabled, `df_vqe_telemetry` is cleared. |
+| **VQE Epochs** | IntText | 1 – ∞ | Optimization iterations. |
+| **Adam LR** | FloatSlider | 0.0001 – 0.1 | ADAM learning rate α. |
+| **Adam Beta1** | FloatSlider | 0.0 – 0.999 | First-moment decay rate. |
+| **Adam Beta2** | FloatSlider | 0.0 – 0.999 | Second-moment decay rate. |
+
+### MD Settings
+
+| Control | Type | Range | Description |
+|---|---|---|---|
+| **Enable MD** | Checkbox | — | Activates `run_md_simulation_dummy()`. When disabled, `df_md_telemetry` and `matrice_correlazione` are cleared. |
+| **MD Steps** | IntSlider | 10 – 1000 | Number of molecular dynamics integration steps. |
+| **Temperature (K)** | FloatSlider | 0.1 – 1000.0 | Thermal bath temperature in Kelvin. |
+
+### Panel Selector
+
+| Panel | Description |
+|---|---|
+| **Overview** | 8-panel scientific dashboard (probability, top states, helix 3D, metrics, noise, shots, VQE telemetry × 6, correlation heatmap) |
+| **Fisica Stato** | State physics: Bloch-sphere projection, Schmidt rank, coherence vector |
+| **Mosaico 1008q** | 2D probability density map up to 1008 qubits |
+| **VQE Results** | Dedicated VQE telemetry: energy convergence, entropy, purity, gradient, noise factor, θ correction |
+| **MD Simulation Results** | MD energy + entropy + purity + gradient + noise + θ correction + full Pearson heatmap |
+| **Performance** | Benchmark metrics: gate throughput, JIT compile time, memory usage |
+
+### Action Buttons
+
+| Button | Description |
+|---|---|
+| **▶ Run Simulation** | Executes the full pipeline: circuit → VQE → MD → panel render |
+| **📊 Benchmark χ** | Runs the χ-scaling benchmark across qubit counts and plots throughput |
+| **💾 Export Provenance** | Saves a JSON file with full run metadata, circuit name, qubit count, entropy, dominant state, and timestamp |
+| **📄 Paper-Ready PNG** | Exports the current figure at 300 DPI to `figure_paper.png` |
+| **🕒 Cronologia** | Prints the run history log to the output cell |
+| **💊 Save Hamiltonian** | Serializes the current Hamiltonian configuration to the provenance record |
+
+---
+
+## 6. Circuit Library
+
+The library ships with 30+ preset circuits across 4 categories. All circuits are stored as OpenQASM 2.0 strings in `QASM_LIBRARY` and can be extended without modifying the engine.
+
+### Standard
+
+Bell |Φ+⟩, QFT 4 qubit, Toffoli (CCX), Adder 2-bit, Deutsch-Jozsa balanced, Bernstein-Vazirani (101)
+
+### Quantum Algorithms
+
+Grover 3q Oracle |111⟩, Simon Algorithm 4q s=11, Shor 15 (Simplified), HHL Matrix Inversion, QAOA Max-Cut 4q, QPE Precision 5q, QFT 8q High-Res, Quantum Walk, Quantum Teleportation
+
+### Advanced Topological
+
+Anyonic Braiding Fibonacci 6q, Topological Charge Pump 8q, MultiControlled-Z 5q, Hyper Inversion 8q, Deep Topological Unified 8q
+
+---
+
+## 7. VQE Engine & ADAM Optimizer
+
+### Positional Parameter Injection
+
+Because the `QASMParser` tokenizes all parameter literals to `0.0` in the AST for maximum JIT throughput, the VQE engine uses a **positional injection** strategy:
+
+1. Scan the AST and count parametric gates (`rx`, `ry`, `rz`, `u1`, `p`, `cp`, `crz`) — this gives `n_params`.
+2. Allocate `θ ∈ ℝⁿ` initialized uniformly in `[-π, π]`.
+3. On each epoch, inject `θ[i]` sequentially by gate appearance order in the AST via `risolvi_qasm()`.
+
+This makes the engine compatible with any valid OpenQASM 2.0 custom circuit without pre-labelling parameters.
+
+### Hellmann-Feynman Gradient
+
+The gradient is computed analytically via JAX automatic differentiation through the `QMMMForceEngine`:
+
+```
+∂E/∂θᵢ = ⟨ψ(θ)| ∂H/∂θᵢ |ψ(θ)⟩
+```
+
+where the QM/MM Hamiltonian includes classical electrostatic contributions from atomic positions `r`, charges `q`, and orbital centers.
+
+The gradient norm `‖∇L‖` per epoch is logged to `df_vqe_telemetry['Gradient']`.
+
+### ADAM Update Rule
+
+```
+mₜ = β₁ · mₜ₋₁ + (1 − β₁) · g
+vₜ = β₂ · vₜ₋₁ + (1 − β₂) · g²
+m̂ₜ = mₜ / (1 − β₁ᵗ)
+v̂ₜ = vₜ / (1 − β₂ᵗ)
+θ  ← θ − α · m̂ₜ / (√v̂ₜ + ε)
+```
+
+`Theta_Correction` per epoch = `‖α · m̂ₜ / (√v̂ₜ + ε)‖` — logged to `df_vqe_telemetry['Theta_Correction']`.
+
+### Telemetry Columns
+
+| Column | Unit | Description |
+|---|---|---|
+| `VQE_Energy` | Ha | `⟨ψ|H|ψ⟩` expectation value |
+| `Entropy` | bit | Von Neumann entropy S = −Tr(ρ log₂ ρ) |
+| `Purity` | — | Tr(ρ²) ∈ [1/d, 1] |
+| `Gradient` | — | `‖∇L‖` Euclidean norm of parameter gradient |
+| `Noise_Factor` | — | Fidelity-derived noise proxy (heuristic) |
+| `Theta_Correction` | rad | ADAM step norm per epoch |
+
+### Fallback Mock
+
+If the circuit has no parametric gates (`n_params == 0`), the engine falls back to `_run_vqe_mock_simulation()`, which generates physically plausible synthetic telemetry curves for demonstration purposes. The output DataFrame has the same schema as the analytical run.
+
+---
+
+## 8. Hamiltonian Library
+
+Real chemical Hamiltonians derived from molecular integrals. Automatically filtered by qubit count to prevent shape mismatch errors.
+
+| Molecule | Qubits | Bond length | E₀ (Ha) |
 |---|---|---|---|
-| CPU (Colab Free) | 24 | 120-5000x+ | Tested configuration |
-| CPU (High RAM) | 26 | 120-5000x+ | 16+ GB recommended |
-| NVIDIA GPU | 28+ | 10000x+* | CUDA-enabled, estimated |
-| TPU | 28+ | 20000x+* | Google Cloud, estimated |
+| H₂ (Hydrogen) | 2 | 0.74 Å (equilibrium) | −1.13 |
+| H₃⁺ (Trihydrogen cation, linear) | 3 | 0.85 Å | −1.28 |
+| LiH (Lithium hydride) | 4 | 1.40 Å (minimum) | −2.31 |
+| H₂O (Water, embedding core) | 5 | 0.96 Å | −4.12 |
+
+Custom Hamiltonians are accepted as JSON arrays of diagonal energy eigenvalues (length must equal `2^n_qubits`):
+
+```json
+[-4.12, -3.79, -3.47, -3.15, -2.83, -2.51, -2.18, -1.85,
+ -1.52, -1.19, -0.86, -0.53, -0.20, 0.13, 0.46, 0.79,
+ 1.12, 1.45, 1.78, 2.11, 2.44, 2.77, 3.10, 3.43,
+ 3.76, 4.09, 4.42, 4.75, 5.08, 5.41, 5.74, 6.07]
+```
+
+---
 
-*GPU/TPU speedups are projected based on JAX scaling characteristics and will be benchmarked in future releases.
+## 9. Noise Models
 
-## Why These Results?
+All models are applied as Kraus channels to the full statevector after circuit execution.
 
-   1. JAX JIT Compilation: Circuit operations compiled to optimized XLA code, eliminating Python interpreter overhead
-   2. Kernel Fusion: Multiple gate operations fused into single GPU/CPU kernels
-   3. Memory Layout: Contiguous statevector storage optimized for vectorized operations
-   4. Caching: Compiled functions cached and reused across executions
+| Model | Kraus operators | Physical process |
+|---|---|---|
+| `ideal` | Identity | Noiseless simulation |
+| `depolarizing` | {√(1−p)I, √(p/3)X, √(p/3)Y, √(p/3)Z} | Equiprobable Pauli errors |
+| `amplitude_damping` | {K₀, K₁} | Energy relaxation T₁ decay |
+| `phase_damping` | {K₀, K₁} | Dephasing T₂ decay |
 
-## Contribute Benchmarks
-Found better (or worse) results on your hardware? Open an issue or PR with:
+**Fidelity metrics computed on every noisy run:**
 
-* Hardware specs (CPU/GPU, RAM)
-* Benchmark code
-* Timing results
+- **Bhattacharyya Fidelity**: `F = Σᵢ √(pᵢ · qᵢ)` where p = ideal distribution, q = noisy distribution
+- **Total Variation Distance**: `TVD = ½ Σᵢ |pᵢ − qᵢ|`
+- **Theoretical depolarizing fidelity**: `F(p,n) = (1 − p(d−1)/d)ⁿ` where d = 2ⁿ, shown as an inset curve in the Noise Analysis panel
+
+**Dtype alignment note:** The engine enforces a consistent dtype across all Kraus branches before `jax.lax.cond` evaluation to prevent `TypeError: cond branches must have equal output types`. The alignment patch is injected automatically via `de.patch_dense_parametric()` on startup.
+
+---
 
-Help us optimize Dense-Evolution for your use case!
+## 10. Molecular Dynamics
+
+The MD module (`run_md_simulation_dummy`) simulates quantum-classical (QM/MM) dynamics and populates two globals:
+
+- `df_md_telemetry` — per-step DataFrame with the same six telemetry columns as VQE
+- `matrice_correlazione` — Pearson correlation matrix across all telemetry variables
+
+Convergence validation (1500-epoch stress test at 5 K) confirms:
+
+- Hellmann-Feynman gradient decays rigorously to zero at the molecular energy minimum (e.g., −4.1200 Ha for H₂O), certifying geometric stability.
+- Activating `depolarizing` or `amplitude_damping` noise introduces coherent micro-jitter on entropy and stabilizes purity below the ideal threshold — consistent with real noisy-chip behavior.
+
+---
+
+## 11. Visualization Panels
+
+### Overview (8-row layout)
+
+| Row | Left | Right |
+|---|---|---|
+| 0 | Header bar: circuit name, qubit count, gate count, wall time, RAM, noise parameters | — |
+| 1 | Probability distribution P(\|n⟩) with custom cyan→rose colormap, dominant state highlighted | Top-12 states ranked by probability, plasma colormap |
+| 2 | Wavefunction helix 3D: amplitude-colored scatter on (Re(ψ), Im(ψ), \|n⟩) | Simulation metrics table: 13 key values |
+| 3 | Noise Analysis: model label, p-gauge, fidelity/TVD table, theoretical F(p) curve inset | NISQ Shot Histogram with expected distribution overlay and σ annotation |
+| 4 | VQE Energy (Ha) — convergence epoch marked | Von Neumann Entropy (bit) |
+| 5 | State Purity Tr(ρ²) — ideal reference at 1.0 | ‖∇L‖ Gradient Norm — barren plateau detection |
+| 6 | Noise Factor — reference at 1.0 | θ Correction (rad) — reference at 0.0 |
+| 7 | Pearson Correlation Matrix (full width) — masked upper triangle, RdBu_r diverging colormap | — |
+
+**Barren plateau detection (Row 5, gradient panel):** epochs where `|g| < 0.01 · max|g|` are highlighted with an `axvspan` region and labeled inline.
+
+**Value badges:** every VQE telemetry panel carries a top-right badge showing the final epoch value (e.g., `Eₙ = −1.1302 Ha`).
+
+### VQE Results
+
+Dedicated 6-subplot panel showing all six telemetry columns from `df_vqe_telemetry` with the same enhanced rendering as Overview rows 4–6: fill-under area, rolling mean overlay, convergence annotations, and value badges.
+
+### MD Simulation Results
+
+Six time-series plots for `df_md_telemetry` plus a full-width masked Pearson correlation heatmap. Font size on the heatmap annotations is automatically scaled to `72 / n_variables` to remain legible at any matrix size.
+
+---
+
+## 12. Export & Provenance
+
+### JSON Provenance
+
+Triggered by **💾 Export Provenance**. Saves to `provenance_rnd42.json` (configurable in `dashboard.toml`):
+
+```json
+{
+  "run_id": "uuid4",
+  "timestamp": "2026-05-30T14:22:11Z",
+  "circuit": "Grover_3q_Oracle_111",
+  "n_qubits": 3,
+  "entropy": 1.584962,
+  "dominant_state": "111",
+  "p_dominant": 0.970312,
+  "noise_model": "depolarizing",
+  "noise_p": 0.005,
+  "shots": 4096,
+  "seed": 42,
+  "wall_time_ms": 3.14,
+  "ram_mb": 0.000064,
+  "vqe_epochs": 100,
+  "adam_lr": 0.01,
+  "annotation": "optional user note"
+}
+```
+
+### PNG Export
+
+Triggered by **📄 Paper-Ready PNG** is work in progress...wain next upgrade
+
+---
+
+## 13. Technical Reference
+
+### `core_calcolo_quantistico()`
+
+Main compute function. Parses the QASM string, builds `comandi_beast_mode[]`, runs `DenseSVSimulator.run_circuit_jit_beast_mode()`, optionally applies noise, and returns `res{}`.
+
+**Return dict keys:**
+
+| Key | Type | Description |
+|---|---|---|
+| `prob` | ndarray | Measurement probability distribution |
+| `prob_ideal` | ndarray | Noiseless probability distribution |
+| `noise_factor` | ndarray | 100-point fidelity decay curve |
+| `fidelity` | float | Bhattacharyya fidelity (ideal vs noisy) |
+| `n_qubits` | int | Allocated qubit count |
+| `entropy` | float | Shannon entropy (bit) |
+| `idx_max` | int | Index of dominant computational basis state |
+| `stato_dominante` | str | Binary string of dominant state |
+| `tempo` | float | Wall-clock time (seconds) |
+| `ram` | float | Statevector RAM (MB) |
+| `nome` | str | Circuit name |
+| `porte_count` | int | Executed gate count |
+| `shots_data` | ndarray | Sampled measurement outcomes |
+| `sim` | DenseSVSimulator | Live simulator instance |
+| `parser` | QASMParser | Reusable parser instance |
+
+### `estrai_valore_puro(elemento)`
+
+Recursive deep-unwrapper for AST tokens. Handles callables, objects with `.index` or `.value` attributes, numpy scalars, and plain Python numerics. Returns a pure `int`, `float`, or `str`. Required because the `QASMParser` can return heterogeneous token types depending on gate context.
+
+### `risolvi_qasm(parametric_commands, param_dict, n_qubits, theta_params, current_param_counter)`
+
+Converts raw AST command dicts to the `[gate_name, target, control_or_param, ...]` list format accepted by `run_circuit_jit_beast_mode()`. Injects `theta_params[i]` sequentially into parametric gates via positional counter.
+
+### Global Telemetry Variables
+
+| Variable | Type | Description |
+|---|---|---|
+| `df_vqe_telemetry` | DataFrame | VQE per-epoch telemetry, index = Step |
+| `df_md_telemetry` | DataFrame | MD per-step telemetry, index = Step |
+| `matrice_correlazione` | DataFrame | Pearson correlation matrix |
+| `CRONOLOGIA_RUNS` | list[dict] | Run history log |
+
+---
+
+## 14. Troubleshooting
+
+**`TypeError: cond branches must have equal output types`**
+
+Occurs when the simulator's 1-qubit branch produces `complex128` while the 2-qubit branch produces `complex64`. Fixed automatically by `de.patch_dense_parametric(de.DenseSVSimulator)` on startup. If the error persists, check that the `dense-evolution` version is ≥ 8.0.4 and that the patch call succeeded in the startup cell.
+
+**VQE telemetry is empty / plots show `[VQE_Energy — no data]`**
+
+Either the **Enable VQE Settings** checkbox is unchecked, or the circuit has no parametric gates and `_run_vqe_mock_simulation` could not be found. Check that all dashboard cells have been executed top-to-bottom in order.
+
+**Custom Hamiltonian size mismatch warning**
+
+The JSON array length must equal `2^n_qubits` exactly. For a 4-qubit circuit, supply exactly 16 values. The dashboard prints a warning and falls back to a random Hamiltonian rather than crashing.
+
+**Barren plateau span not visible on gradient plot**
+
+Triggered only when more than 3 consecutive epochs have `|g| < 0.01 · max|g|`. With short runs (< 50 epochs) or fast-converging circuits, the threshold may never be crossed. Increase epochs or reduce the learning rate.
+
+**`display(dashboard_unificata)` shows nothing in JupyterLab**
+
+Ensure `ipywidgets` is enabled: `jupyter labextension install @jupyter-widgets/jupyterlab-manager`. In Google Colab this is pre-installed.
+
+**Memory error on high-qubit circuits**
+
+The statevector for n qubits requires `2ⁿ × 16 bytes` (`float64` complex). At 24 qubits: 268 MB. At 33 qubits: 536 GB — only feasible with high-RAM runtimes or GPU backends. Use `use_float32=True` to halve memory at reduced precision.
+
+---
+
+## 15. License
+
+Dense Evolution is licensed under the **Business Source License 1.1 (BSL 1.1)**.
+
+- **Non-commercial use:** unrestricted.
+- **Commercial use:** permitted up to 24 allocated qubits and 1000 distinct circuits / 10,000 shots per circuit per day without a separate commercial license.
+- **Change date:** 1 June 2029 — the software converts permanently to **Apache License 2.0** on that date.
+- **Attribution required:** all copies or derivatives must carry `© 2026 Salvatore Pennacchio <jtatopenn@libero.it> — Dense Evolution`.
+
+Full license text: [LICENSE.md](LICENSE.md)
+
+---
 
+*© 2026 Salvatore Pennacchio — Dense Evolution v8.0.4*