README.md

metadata

license: mit
tags:
  - quantum-computing
  - molecular-simulation
  - shadow-spectroscopy
  - regression
  - pytorch
library_name: pytorch

molecular-shadows-h4

The H4 direct-observable regressor for fermionic shadow spectroscopy on linear $\mathrm{H_4}$ / STO-3G. Given an equal nearest-neighbor bond length $R$ and a propagation time $t$, it predicts the length-120 vector of time-evolved Majorana expectation values

$$D_{\mu }(R,t)=⟨{\psi }_0(R)\mathrm{\mid }{\mathrm{\Gamma }}_{\mu }(t)\mathrm{\mid }{\psi }_0(R)⟩,{\mathrm{\Gamma }}_{\mu }(t)=e^{iH(R)t}{\mathrm{\Gamma }}_{\mu }{e}^{-iH(R)t},D\_\backslash mu(R,\; t)\; =\; \backslash langle\; \backslash psi\_0(R)\; \backslash ,|\backslash ,\; \backslash Gamma\_\backslash mu(t)\; \backslash ,|\backslash ,\; \backslash psi\_0(R)\; \backslash rangle,\; \backslash qquad\; \backslash Gamma\_\backslash mu(t)\; =\; e^\{iH(R)t\}\backslash ,\backslash Gamma\_\backslash mu\backslash ,e^\{-iH(R)t\},$$

which feed the downstream matchgate-shadow spectroscopy post-processing (FFT $\to$ peaks $\to$ energy gaps). This is the four-hydrogen model; a single-reference $\mathrm{H_2}$ companion exists separately.

What's new vs the earlier H4 release. This model uses an explicit-amplitude composition head and adaptive Fourier bandwidth, with chemically-informed orbital-energy inputs. Short-bond accuracy — the structural weak spot of the earlier release ($R < 1.0$ Å, $r \approx 0.40$) — is now strong ($r \approx 0.90$). Overall held-out Pearson $0.83 \to 0.93$.

Architecture

A linear-in-time Fourier head with geometry-conditioned frequencies and an explicit amplitude/phase factorization (no nonlinear trunk):

$${\widehat{y}}_{\mu }(R,t)=\sum _{k=1}^{256}{a}_{k\mu }(R)\cos ({\omega }_k(R)t)+b_{k\mu }(R)\sin ({\omega }_k(R)t)+{\mathrm{d}\mathrm{c}}_{\mu }(R),\backslash hat\{y\}\_\backslash mu(R,\; t)\; =\; \backslash sum\_\{k=1\}^\{256\}\; a\_\{k\backslash mu\}(R)\backslash cos(\backslash omega\_k(R)\backslash ,\; t)\; +\; b\_\{k\backslash mu\}(R)\backslash sin(\backslash omega\_k(R)\backslash ,\; t)\; +\; \backslash mathrm\{dc\}\_\backslash mu(R),$$

with geometry-conditioned, bandwidth-limited frequencies

$${\omega }_k(R)={\omega }_{\mathrm{o}\mathrm{p}}(R)\cdot \sigma \text{\hspace{0.17em}⁣}(\mathrm{f}\mathrm{r}\mathrm{e}\mathrm{q}\mathrm{\_}\mathrm{n}\mathrm{e}\mathrm{t}(\epsilon (R)){)}_k,\backslash omega\_k(R)\; =\; \backslash omega\_\{\backslash mathrm\{op\}\}(R)\backslash cdot\; \backslash sigma\backslash !\backslash big(\backslash mathrm\{freq\backslash \_net\}(\backslash varepsilon(R))\backslash big)\_k,$$

where $\varepsilon(R)$ are the HF orbital energies and $\omega_{\mathrm{op}}(R)$ is the per-geometry operational frequency ceiling (soft-floored at 8.0). The amplitude tensors $a_{k\mu}, b_{k\mu}$ are low-rank factorized (rank 16).

(R, t) + HF orbital energies ε(R)
      │
      ├── freq_net(ε(R)) ─ sigmoid ─ × ω_op(R)  → 256 frequencies ω_k(R)   (adaptive bandwidth)
      │
      ├── amp_net(ε(R)) → low-rank a_kμ(R), b_kμ(R), dc_μ(R)   (rank 16)
      │
      └── y_μ(R,t) = Σ_k a_kμ cos(ω_k t) + b_kμ sin(ω_k t) + dc_μ   (explicit-amplitude head)

Hyperparameter	Value
n_observables	120 (degree-1 Majorana monomials, 8 spin-orbitals)
n_fourier	256
explicit_amplitude / amp_rank	True / 16
adaptive_bandwidth	True ($\omega_{\mathrm{op}}$ floor 8.0, soft)
conditioned_frequencies	True
trunk depth × width	6 × 768
freq_net depth × width	3 × 128
residual trunk	None
n_orb_features	4 (HF spatial-orbital energies of H4/STO-3G)
Parameter count	~12.3 M
Training	150k steps, AdamW, cosine LR $10^{-3}\to10^{-7}$, grad-clip 1.0, seed 42

Chemically-informed inputs

The model conditions on HF orbital energies $\varepsilon(R)$ rather than the bare scalar $R$. On a paired held-out comparison (identical geometries, same architecture, same data), orbital-energy inputs beat geometry-only inputs decisively where multi-reference character lives, and converge with it at dissociation:

$R$ bin (Å)	orbital-energy input	scalar-$R$ input
$<0.74$	0.89	0.57
$[0.74, 1.0)$	0.98	0.71
$[1.0, 1.5)$	0.96	0.88
$[1.5, 2.0)$	0.94	0.89
$\geq 2.0$	0.93	0.94

This repo ships the orbital-energy model.

Held-out evaluation

50 held-out geometries on the dense $R \in [0.5, 3.0]$ Å grid (251 total), per-observable temporal Pearson $r$:

$R$ bin (Å)	pearson_mean
$<0.74$	0.90
$[0.74, 1.0)$	0.97
$[1.0, 1.5)$	0.96
$[1.5, 2.0)$	0.93
$\geq 2.0$	0.92

Aggregate: mean Pearson 0.928 across all 50 held-out geometries; top-1 spectral-peak match 44/50. The result is seed-robust — pooling a second seed ($n=100$) gives overall 0.94 with borderline-bin seed spread $|\Delta| < 0.02$. See eval_results.json for per-$R$ numbers.

Inputs / outputs

• Input. $(R, t)$ — equal nearest-neighbor bond length in Å (linear chain: H atoms at $0, R, 2R, 3R$) and propagation time in a.u.
• Output. Length-120 vector of expectation values $D_\mu(R,t)$ for degree-1 Majorana observables on H4/STO-3G's 8 spin-orbital JW encoding.
• Valid range. $R \in [0.5, 3.0]$ Å, $t \in [0, 300]$ a.u. Accuracy is now reasonably uniform across the curve; the only mild residual deficit is in the long-$R$ time-domain fit, which the spectral post-processing absorbs.

Quickstart

from inference import MolecularShadowsRegressor
import numpy as np

m = MolecularShadowsRegressor.from_hub(
    "aniketdesh/molecular-shadows-h4",
    revision="v18-orb",    # immutable architecture pin
    token="hf_...",
)

t_grid = np.linspace(0, 300, 1500)
y = m.predict_trajectory(R=0.8, t_grid=t_grid)   # (1500, 120) — short bond now reliable

Notes & limitations

Earlier H4 releases were structurally weak at short bond ($R < 1.0$ Å): linear H4 has a multi-reference singlet manifold whose eigenvectors rotate near-discontinuously through avoided crossings as the chain compresses, and the old GELU trunk could not encode that rapid amplitude rotation. The explicit-amplitude head (which factorizes the prediction into per-geometry amplitudes and frequencies) plus orbital-energy conditioning resolve most of this — short-bond Pearson is now $\approx 0.90$. The remaining limitation is a small loss of time-domain fidelity at large $R$ (slowly-varying non-sinusoidal structure the linear-in-time basis cannot represent); because the downstream Chan-style spectral analysis reads off frequencies, not waveforms, this does not degrade recovered energy gaps.

Files in this repo

File	Purpose
regressor.pt	torch payload (state_dict + config + R/t grids)
observable_regressor.py	architecture (single file)
inference.py	loader (MolecularShadowsRegressor)
orbital_energies.npz	R-grid + HF orbital-energy table (+ $\omega_{\mathrm{op}}$)
eval_results.json	per-R held-out metrics (50 geoms)
eval_summary.json	aggregate
history.json	training curves
README.md	this file

Versioning

• v18-orb (current): explicit-amplitude composition + adaptive bandwidth + orbital-energy conditioning, grad-clip 1.0. Mean Pearson 0.928, short-bond recovered. Pin via revision="v18-orb".
• Future architectures push as new commits with new tags; existing pins keep loading the exact committed version.

Citation

Method: matchgate-shadow spectroscopy following arXiv:2212.11036 and matchgate-shadow theory.

License

MIT.