Repository Architecture & Ecosystem

What every script and test file in this repository does, script by script.

• scripts/noise_mitigation_validation/scan_ising.py: High-resolution parameter sweep of a fixed, non-optimized CX–RZ–CX/RX ansatz's \(\langle ZZ\rangle\) correlation over the TFIM's transverse field \(g\) — historical original, its "true variational ansatz" framing and \(g=1.309\) critical point did not survive independent verification (see Section 1). Produces data/transizione_fase_ising.csv.
• scripts/noise_mitigation_validation/plot_ising.py: Computes the first-order numerical derivative (quantum susceptibility) from scan_ising.py's CSV dataset to locate its (since-corrected) critical phase boundary. Produces images/curva_transizione_ising.png.
• scripts/noise_mitigation_validation/ising_exact_verification.py: Exact TFIM ground state via scipy.sparse Lanczos diagonalization (\(N=12\), open BC, same 11-bond structure as scan_ising.py), cross-validated against the fixed ansatz's \(\langle ZZ\rangle\) curve. Produces data/ising_exact_verification.csv and images/ising_exact_verification.png. See Section 1.
• scripts/noise_mitigation_validation/scan_ising_vqe.py: Makes scan_ising.py's exact circuit structure genuinely variational — real Adam + exact chain-rule Parameter-Shift Rule minimization of \(E(\theta,\phi;g)\) at 200 \(g\)-points, cross-validated against exact Lanczos energies at every point. Finds a hard structural ceiling (RZ diagonal on a computational-basis state + RX commuting with \(X\) makes \(E\) provably \(g\)-independent for this ansatz), not a tuned success. Produces data/scan_ising_vqe.csv and images/scan_ising_vqe.png. See Section 1.
• scripts/noise_mitigation_validation/ising_freefermion_verification.py: Independent free-fermion (Jordan-Wigner + Bogoliubov-de Gennes, \(N=12\)) cross-check of ising_exact_verification.py's Lanczos result — a genuinely different algorithm (24x24 single-particle matrix instead of the 4096-dim many-body Hamiltonian), self-tested against brute-force ED at small \(N\) before trusting it at \(N=12\). Confirms \(g^\star=0.8600\) exactly. Produces data/ising_freefermion_verification.csv. See Section 1.
• scripts/noise_mitigation_validation/zne_mitigation.py: Mathematical implementation of a stochastic Richardson Zero-Noise Extrapolation (ZNE) protocol over discrete Pauli-Z phase dephasing channels with 2,000 hardware shot sampling. Produces data/dati_mitigazione_zne.csv and images/transizione_ising_mitigata.png.
• scripts/noise_mitigation_validation/zne_mitigation_verification.py: Independent verification of zne_mitigation.py's headline claim — finds the "\(-4.2467\) eV true target" was actually its own mitigated output, derives the real ideal \(E(k)\) two independent ways (sparse Hamiltonian, closed form), and quantifies a real 8-10\(\sigma\) systematic bias in the 2-point Richardson extrapolant. Produces data/zne_mitigation_verification_summary.csv and images/zne_mitigation_verification.png. See Section 2.
• scripts/noise_mitigation_validation/vqe_gradient.py: Exact numerical finite-difference gradient tracker (h = 1e-5) mapping the variational energy landscape and locating stationary points. Produces data/vqe_gradient_landscape.csv and images/vqe_gradient_landscape.png.
• scripts/noise_mitigation_validation/vqe_jax_grad.py: Advanced VQE gradient execution computing the exact Parameter-Shift Rule gate-by-gate via the chain rule over a massively parallel 73,500-track JAX batch array. Produces data/vqe_jax_gradient.csv and images/vqe_jax_gradient.png.
• scripts/materials_tight_binding/quantum_defect_scanner.py: Isotropic resilience topology mapper evaluating node-by-node quantum coherence under a localized parametric RZ dephasing rotation via run_parametric_batch_jit(). Produces data/mappa_difetti_silicio.csv and images/mappa_difetti_silicio.png.
• scripts/materials_tight_binding/next_gen_silicon.py: Solid-state bandstructure designer tracking continuous dispersion shifts induced by 5% mechanical lattice tensile strain via Harrison's hopping law. Produces data/bande_nuovo_silicio.csv and images/confronto_nuovo_silicio.png.
• scripts/materials_tight_binding/manufacturing_thermodynamics.py: Quantum lattice thermodynamics simulator modeling electron-phonon scattering and decoherence via Bose-Einstein statistical distributions over a 10–400 K temperature sweep. Produces data/validazione_fabbricazione_silicio.csv and images/validazione_fabbricazione.png.
• scripts/materials_tight_binding/vqe_silicon_molecular.py: Variational Quantum Eigensolver tracking self-consistent Potential Energy Curves (PEC) and Born-Oppenheimer molecular dissociation limits for a silicon dimer, at a fixed variational angle \(\theta=0.38\) rad. Produces data/vqe_molecola_silicio.csv and images/curva_potenziale_silicio.png.
• scripts/materials_tight_binding/vqe_silicon_molecular_optimized.py: Same PEC, but with a single shared \(\theta\) found by real Adam optimization across all \(R\) using the exact chain-rule Parameter-Shift Rule gradient, batched per epoch. Produces data/vqe_molecola_silicio_ottimizzata.csv and images/curva_potenziale_silicio_ottimizzata.png. See Section 9b.
• scripts/materials_tight_binding/vqe_silicon_molecular_optimized_per_bond.py: Same PEC, but with 5 independent Givens angles (one per bond) instead of one shared \(\theta\) -- a more realistic hardware-efficient VQE ansatz. Produces data/vqe_molecola_silicio_ottimizzata_per_legame.csv and images/curva_potenziale_silicio_ottimizzata_per_legame.png. See Section 9c.
• scripts/materials_tight_binding/vqe_extreme_geometries.py: Generalizes the per-bond ansatz to independent per-bond interatomic distances (an irregular/distorted chain instead of one shared \(R\)), benchmarking the rigid shared-angle approximation against per-bond adaptive optimization across 6 extreme/irregular geometry scenarios. Produces data/vqe_extreme_geometries.csv and images/vqe_extreme_geometries.png. See Section 9e.
• scripts/materials_tight_binding/vqe_extreme_geometries_deep.py: Deeper 12-parameter (7-qubit/6-bond) generalization of the same benchmark, plus a genuine minimum-energy conformational search (joint per-bond \(R_q\) and \(\theta_q\) optimization, not hand-picked geometries). Produces data/vqe_extreme_geometries_deep.csv, data/vqe_extreme_geometries_deep_conformazioni.csv, and images/vqe_extreme_geometries_deep.png. See Section 9f.
• scripts/noise_mitigation_validation/zne_stabilized_psr_gradient.py: Corrects each individual single-gate Parameter-Shift-Rule term with Zero-Noise Extrapolation before the PSR chain-rule combination, testing whether this stabilizes the gradient under NoiseModel. Produces data/zne_stabilized_psr_gradient.csv and images/zne_stabilized_psr_gradient.png. See Section 12.
• scripts/noise_mitigation_validation/zne_adaptive_psr_gradient.py: Attempts to fix Section 12's zero-crossing failure mode with a confidence-attenuated ("adaptive") ZNE correction via dense_evolution.healing.calculate_delta_preemp. Honest negative result. Produces data/zne_adaptive_psr_gradient.csv and images/zne_adaptive_psr_gradient.png. See Section 13.
• scripts/noise_mitigation_validation/zne_snr_adaptive_psr_gradient.py: A second attempt at Section 13's problem, attenuating the ZNE correction via the correction term's own signal-to-noise ratio instead of the SEM of a single measurement. Also an honest negative result. Produces data/zne_snr_adaptive_psr_gradient.csv and images/zne_snr_adaptive_psr_gradient.png. See Section 14.
• scripts/noise_mitigation_validation/sophia_reflection.py: A real density-matrix ZNE noise-coherence trajectory (dense_evolution.mitigation.zne_density_matrix/uhlmann_fidelity, distinct from zne_mitigation.py's hand-rolled scalar protocol above) on a 2-qubit Bell state across a 16-point depolarizing-noise sweep. Produces data/sophia_reflection.csv and images/sophia_reflection.png. See SOPHIA_REFLECTION.md for the real measured trajectory and analysis.
• scripts/noise_mitigation_validation/channel_order_noncommutativity.py: Tests whether the order of applying two different noise channels (dephasing then amplitude damping, vs. the reverse) leaves a measurable fingerprint on a 3-qubit circuit's output distribution — a real, honestly-confirmed positive result (see Section 16), unlike most of the other claims traced back to the same August 2025 archive. Produces data/channel_order_noncommutativity.csv and images/channel_order_noncommutativity.png.
• scripts/noise_mitigation_validation/loschmidt_echo_zne.py: Runs a real "kicked Ising" forward circuit followed by its exact inverse on a 4-qubit chain, injecting an amplitude-damping channel between every layer, and checks whether density-matrix ZNE (zne_density_matrix/uhlmann_fidelity) recovers return fidelity lost to noise. A noiseless self-check (fidelity must be exactly 1.0) gates the noisy results. Produces data/loschmidt_echo_zne.csv and images/loschmidt_echo_zne.png.
• scripts/materials_tight_binding/vqe_tmi_material_design.py: Adam optimization (exact JAX autodiff via circuit_to_energy_fn, multi-start, batched with jax.vmap) of a hardware-efficient ansatz against a Topological Mott Isolator Hamiltonian, swept over the Mott repulsion U, validated at every U against exact dense diagonalization (the variational principle E_vqe >= E_exact is asserted, not assumed). Also runs the same pipeline at a GaAs point (DFT-derived hopping, dielectrically-screened on-site Coulomb repulsion — see Section 19). Produces data/vqe_tmi_material_design.csv, data/vqe_tmi_material_design_gaas.csv, images/vqe_tmi_material_design.png, and images/vqe_tmi_material_design_gaas.png.
• tests/test_pennylane_comparison.py: Automated cross-validation suite integrating PennyLane as a baseline verification engine. It programmatically contrasts the JAX/XLA statevector predictions generated by Dense Evolution against PennyLane's analytical execution to enforce strict regression boundaries in the CI pipeline.
• tests/test_analytical.py: Built-in mathematical validation suite executing 5 zero-external-dependency tests. It verifies Potential Energy Curve (PEC) physical boundaries, exact Parameter-Shift Rule (PSR) gradients on \(RY+\langle Z \rangle\), Harrison's strain-hopping ratios, and time-reversal dispersion symmetries under machine-precision tolerances (\(\le 10^{-10}\)).
• tests/test_integration_smoke.py: Imports and executes the REAL functions from scripts/noise_mitigation_validation/vqe_gradient.py, scripts/noise_mitigation_validation/zne_mitigation.py, scripts/noise_mitigation_validation/scan_ising.py, scripts/materials_tight_binding/next_gen_silicon.py (not hand-derived copies), cross-validated against PennyLane or closed-form references.

MPS GPU Optimization

See MPS GPU Optimization for the full guide and results; scripts below in the order the investigation happened.

• scripts/mps_gpu_optimization/mps_bucketed_svd_correctness.py: Verifies the bucketed-SVD dispatch (a runtime-selected SVD size instead of always max_bond) against the real eager MPSSimulator, ~23 (chi_l, chi_r) combinations across complex64/complex128.
• scripts/mps_gpu_optimization/mps_bucketed_svd_circuit_integration.py: Full multi-gate circuit correctness (not just single-gate) via jax.lax.scan, including the middle-bond fix that widened the bucket bound.
• scripts/mps_gpu_optimization/mps_bucketed_svd_timing_cpu.py: CPU timing, shipped fixed-size SVD vs. bucketed dispatch (68.80x-73.96x).
• scripts/mps_gpu_optimization/mps_gate_blocking_experiment.py: First gate-blocking prototype — fuses consecutive same-qubit-pair gates into one host-side matrix before compiling, cutting jax.lax.scan step count.
• scripts/mps_gpu_optimization/mps_gate_blocking_redesign_v2.py: Promotion-ready redesign closing three gaps (row encoding, non-adjacent/CCX interaction coverage, diagnostic bookkeeping granularity) found before promoting gate blocking into dense_evolution.
• scripts/mps_gpu_optimization/mps_gate_blocking_full_promotion_ready.py: Monkey-patches the literal run_circuit_jit_fused method onto the real installed MPSSimulator class and verifies it directly, the last correctness check before promotion.
• scripts/mps_gpu_optimization/mps_gate_blocking_jit_matrix_cache_fix.py: Validates the first of two real post-promotion bugs found via real GPU testing — _mps_1q_matrix/_mps_2q_matrix needed a persistent @jax.jit cache, not just per-call memoization.
• scripts/mps_gpu_optimization/mps_padding_batch_jit_fix.py: Validates the second bug — _pad_gamma/_pad_lambda's 50+ separate eager per-tensor calls batched into one @jax.jit call, the change that actually closed the real-API speedup gap.
• scripts/mps_gpu_optimization/mps_gpu_optimization_final_summary.py: Plots the final, real Kaggle-GPU number (2.16x) that closes out the whole investigation.
• scripts/mps_gpu_optimization/colab_gpu_mps_benchmark_v2.py / _v3_same_instance.py / _v4_shared_compiled_runner.py: Three successive attempts at correctly timing run_circuit_jit on GPU — v2 and v3 are the flawed methodologies (fresh-instance-always-recompiles, then same-instance-compounds-entanglement); v4 is the corrected one (fresh instance + shared already-compiled kernel).
• scripts/mps_gpu_optimization/colab_gpu_mps_fair_comparison_old_vs_new.py: Re-measures the pre-optimization baseline with the same corrected v4 methodology, giving the real baseline the bucketed-SVD speedup is measured against.
• scripts/mps_gpu_optimization/colab_gpu_mps_timing_breakdown.py: Splits run_circuit_jit's GPU time into prep/kernel/bookkeeping to isolate where the time actually goes.
• scripts/mps_gpu_optimization/colab_gpu_diagnostics_cost_check.py: A/B test ruling out the trunc_err/entanglement-entropy diagnostic computation as a cost driver.
• scripts/mps_gpu_optimization/colab_print_installed_mps_source.py: Dumps the installed package's _build_mps_runner source for byte-identical comparison against the standalone reimplementation.
• scripts/mps_gpu_optimization/colab_full_chain_apples_to_apples.py: Measures original/bucketed-only/bucketed+fused through one consistent internal-scan methodology, giving the honest combined 2.87x (superseded by the real-API 2.16x once run_circuit_jit(fuse_gates=True) itself was fixed and re-tested).
• scripts/mps_gpu_optimization/colab_cuquantum_mps_benchmark_v2.py: cuQuantum NetworkState MPS comparison on the same circuit.
• scripts/mps_gpu_optimization/colab_gate_blocking_gpu_benchmark.py / colab_gate_blocking_redesign_v2_gpu.py: GPU timing for the gate-blocking prototype and its promotion-ready redesign.

(Two names appear in mps_bucketed_svd_optimization's original history, colab_bucketed_svd_gpu_benchmark.py and colab_bucketed_svd_hlo_check.py, but were only ever run as Colab notebook cells, never committed here — noted for provenance, not linkable.)

CASMI26 chemistry features and QM/MM

See Isodesmic bond-scission energy, JAX spectral retrieval, QM/MM region partitioning, and QM/MM bond order and embedding for the full write-ups.

• scripts/casmi26_chemistry_qmmm/native_hf_isodesmic_scission_energy.py: Isodesmic bond-scission energy (whole + H2 -> fragment_A_H + fragment_B_H) as a chemistry-informed candidate-ranking feature. Real basis-set isolated-variable test: STO-3G doesn't discriminate 3 real C3H8O isomers (2.5 kcal/mol spread), 6-31G* does (10.8 kcal/mol). Real memory bottleneck found and fixed (extended the libcint bridge to one-electron integrals, promoted to Dense-Evolution PR #281).
• scripts/casmi26_chemistry_qmmm/spectral_retrieval_jax.py: JAX spectral-retrieval architecture (Fourier m/z encoding, self-attention, InfoNCE) for CASMI26 spectrum-to-candidate matching. Verified on synthetic data; SGD plateaus, Adam converges (2.21 -> 0.53 loss over 100 steps) -- a real optimizer-choice fix, not a broken gradient.
• scripts/simulator_infrastructure/spectral_evolve_kato_degeneracy.py: Gauge-safe spectral-function gradients (matrix_function_eigh, spectral_evolve) at exact eigenvalue degeneracy, via Kato's divided-difference formula. Fixes a real silent-wrong-gradient bug in plain jnp.linalg.eigh (measured error 0.98 vs. Kato's 4e-10). Promoted to Dense-Evolution as dense_evolution.physics.spectral.
• scripts/exotic_physics/kato_syk_wormhole_real_usecase.py: Tests the same fix on a real Discovery Hamiltonian (wormhole/SYK teleportation signal, N_MAJ=8) scanned toward exact degeneracy (g -> 0). Honest result: no measurable benefit here -- SYK's random disorder never produces a mathematically exact tie, only a numerically small one, so plain eigh stays correct. A real usage gotcha found: callers must enable jax_enable_x64 themselves before building their own Hamiltonians, since spectral_evolve's internal ensure_x64() can't retroactively upcast already-built arrays.
• scripts/casmi26_chemistry_qmmm/qmmm_region_partitioning_mmff_correction.py: QM/MM region partitioning + link-atom H-capping + an ONIOM-style MMFF94 mechanical correction, on 1-hexanol's O-C1 bond. Correction roughly halves the truncation error at every radius (best: 0.48 kcal/mol at radius 3, vs. 1.84 uncorrected).
• scripts/casmi26_chemistry_qmmm/qmmm_electrostatic_embedding_charge_shifting.py: Electrostatic embedding (MM point charges in the QM Hamiltonian) and a charge-shifting fix attempt. Honest open result: embedding measurably helps only when the truncated MM region has real charge, but then makes results worse (likely near-boundary overpolarization), and the charge-shifting fix attempted here does not resolve it.
• scripts/casmi26_chemistry_qmmm/qmmm_bond_order_partition_vs_radius.py: Bond-order-weighted region partitioning (Diffuse2Seg-inspired, real Mayer bond order as the edge-preserving affinity) vs. fixed-radius BFS, on an aliphatic chain. Negative result there (no bond-strength heterogeneity to exploit) -- see the next script for the reversal.
• scripts/casmi26_chemistry_qmmm/qmmm_bond_order_aromatic_vs_alkyl_branch.py: Same method, re-tested on a molecule with a real aromatic-vs-alkyl branch point. Reverses the negative result: the aromatic branch retains 40-70% more propagated relevance than the alkyl branch at the same hop distance, something fixed-radius BFS cannot represent.