Kernel Dynamics Viewer (v0.6)

1D / 2D / 3D / 4D kernels · transport × coherence two-axis classification · isotropic S(k, ω) via Hankel / spherical-Bessel · sliding-window regime tracking · real quantum example data bundled · NumPy + SciPy + Matplotlib only · MIT

Install

git clone https://github.com/HeliCorgi/kernel-dynamics-viewer
cd kernel-dynamics-viewer
pip install -e .          # Python >= 3.9
kernel-viewer demo        # try it in 10 seconds

Version history

• v0.1 — 1D kernels, two-axis classifier, real XXZ/Ising data
• v0.2 — 2D (radial reduction + full-2D moments, anisotropy A/c4)
• v0.3 — 3D (FA/Q4), isotropic S(k,ω) via Hankel J0 / spherical Bessel j0
• v0.4 — unified compute_structure_factor API, dispersion validation
• v0.5 — 4D (generalized FA/Q4, zonal basis 2J1(x)/x, wavefront-dilution notes)
• v0.6 — sliding-window regime tracking (track), coherence-change detection

A small Python toolkit for regime diagnostics of spatiotemporal kernels K(r, t) from non-equilibrium many-body systems (quantum or classical).

You measured or simulated a dynamic correlation function K(r, t) = <O(r, t) O(0, 0)> — a spreading profile over space and time. This tool turns it into a small set of measurable shape features and a two-axis regime classification, with publication-style plots, in one command:

kernel-viewer analyze data.npz

No theory, no interpretation — only numerical shape descriptors.

What it computes

feature	definition	meaning
transport exponent p	late-window slope of log sigma^2(t) vs log t, boundary-contaminated tail excluded	1 = diffusive, 2 = ballistic
unimodality score	1 / n_peaks of the symmetrized profile (prominence-filtered)	1.0 = single peak
ring strength E(t)	(max_{r>0} K - K(0)) / K(0)	> 0: the maximum sits off the source
violation V(t)	strongest positive step of the profile, relative to K(0)	0 = monotone profile
tail shape	gaussian / exponential / power-law, decided on the outer half of the profile via log-log curvature	power-law = heavy (Levy-like) tail
S(k, omega)	double cosine transform (Hann window)	central ridge = relaxational, off-axis ridge = propagating

Two-axis classification

Axis 1 — transport (from the exponent + tail): DIFFUSIVE / SUPERDIFFUSIVE / BALLISTIC / SUBDIFFUSIVE / LEVY

Axis 2 — coherence (from the ring history E(t)): MONOTONE / RING_TRANSIENT / RING_PERSISTENT / RING_RECURRENT

The axes are deliberately independent, because they are in the data: ballistic kernels can be unimodal, and diffusive systems can show transient rings. "Chaotic vs integrable" is typically an axis-2 distinction (transient vs recurrent rings), not an axis-1 one — that is why there is no CHAOTIC transport class.

Two failure modes this design avoids:

• unimodality ~ 1 does not imply diffusive (early ballistic kernels are unimodal too) — transport is read from sigma^2(t), never from peak counts;
• sigma^2 ~ t does not rule out Levy (for power-law tails the second moment is dominated by the finite window) — heavy tails are detected separately and promote the regime to LEVY.

Quickstart

python -m kernel_viewer.cli demo            # 4 synthetic kernels -> reports + dashboards
python -m kernel_viewer.cli analyze examples/xxz_Sx_integrable.npz
python -m kernel_viewer.cli classify examples/ising_q_chaotic.npz -o report.json

Data format: .npz with K plus optional axes — 1D: K (T, R) with r (R,), t (T,); 2D: K (T, Y, X) with x (X,), y (Y,), t (T,); 3D: K (T, Z, Y, X) with x, y, z, t; 4D: K (T, W, Z, Y, X) with x, y, z, w, t. The time axis is always first. (Bare .npy works too; integer axes are then assumed.) The loader dispatches on dimensionality automatically — no --dim flag is needed.

from kernel_viewer import load_kernel, classify
rep = classify(load_kernel("data.npz"))
print(rep.summary())

2D kernels

2D input K(x, y, t) is handled by radial reduction with full-2D moments:

• transport moments (sigma^2, edge fraction, conservation) are computed on the full 2D array — radially averaged profiles would miss the r dr measure;
• shape metrics (unimodality, ring, violation, tail) run on the radially averaged profile P(r, t), binned in unit annuli up to the inscribed circle only (square-window corners sample angles unevenly);
• two anisotropy diagnostics are added: the covariance anisotropy A(t) (quadrupole; blind to 4-fold patterns) and the angular harmonic c4(t) computed on pixels with r >= 2 (the nearest-neighbour shell of a square lattice is itself 4-fold and would fake c4 ~ 1 for any narrow kernel).

Coherence axis reads differently in 2D. A propagating mode's wavefront is a circle, so RING_* on the radial profile means "a coherent propagating front is present" — generic for wave-like transport in 2D, and not by itself a sign of integrability (that reading was calibrated on 1D chains).

python -m kernel_viewer.cli demo2d   # 6 cases incl. an MC random walk and a lattice wave equation
python -m kernel_viewer.cli analyze examples/wave2d_lattice.npz

examples/wave2d_lattice.npz (leapfrog 2D wave equation: circular front, C4 lattice anisotropy, interference recurrences) and examples/randomwalk2d_mc.npz (200k-walker Monte-Carlo diffusion with real sampling noise) are dynamically generated, not closed forms.

3D kernels (v0.3)

3D input K(x, y, z, t) follows the 2D design: spherical-shell radial reduction with full-3D moments (sigma^2 = <x^2+y^2+z^2>, verified = 6 D t exactly on Gaussian ground truth), statistics up to the inscribed sphere only, and true voxel bin counts carried with the profile. Anisotropy diagnostics: FA(t) (fractional anisotropy of the covariance, DTI convention; blind to cubic patterns) and Q4(t) = <n_x^4+n_y^4+n_z^4> - 3/5 on voxels with r >= 2 (+0.4 = axis-aligned; the nearest-neighbour shell of a cubic lattice is 6-fold and would fake Q4 = +0.4 for any narrow kernel). Reports include dimensionality and isotropy_score.

python -m kernel_viewer.cli demo3d
python -m kernel_viewer.cli analyze examples/randomwalk3d_mc.npz

Memory note: K (T, Z, Y, X) is held as float64 in RAM — a 13 x 41^3 kernel is ~90 MB. Store float32 on disk and keep L moderate.

S(k, omega) for isotropic 2D/3D kernels (v0.3)

spectrum now works for 2D and 3D via the dimensionally correct radial transform — Hankel (J0) in 2D and spherical Bessel (j0 = sin(x)/x) in 3D — weighted by the true lattice bin counts (more faithful than the continuum 2 pi r dr / 4 pi r^2 dr measure on small grids), followed by the windowed cosine transform in time:

python -m kernel_viewer.cli spectrum data_2d.npz   # no flag needed

Validated against the exact Gaussian symbol C(k,t) = W exp(-D k^2 t) to ~10% (integer-bin discretization). Isotropy is assumed: the command prints the isotropy_score and warns below 0.9; anisotropic vector-k spectra are NOT implemented.

Unified structure-factor API (v0.4)

from kernel_viewer.metrics.fourier import compute_structure_factor
sp = compute_structure_factor(kernel)        # Kernel / Kernel2D / Kernel3D
sp.transform_type   # "cosine" / "hankel_j0" / "spherical_bessel_j0"
sp.warnings         # e.g. anisotropy warning (radial S mixes directions)

One entry point dispatching to the dimensionally correct transform, with the isotropy check built in (below isotropy_threshold=0.9 a warning is attached). save_spectrum() writes k, omega, S_kw, transform_type to .npz; plot_structure_factor() adds the dispersion overlay.

Physics validation (in the test suite): for a moving-shell kernel the dispersion omega_peak(k) = v k is recovered — 2D slope within ~11% of the true v (corr 0.998). 3D caveat: a sharp shell's radial transform is j0(kvt) ~ sin(kvt)/(kvt); the 1/t surface-dilution envelope turns S(k, omega) into a plateau with an edge at omega = v k, so the peak estimator is linear in k but systematically below v (textbook, not a bug). Kernels built from rectified amplitudes (|u|, e.g. the bundled wave2d_lattice) carry no phase information — their dispersion cannot be recovered from S(k, omega) at all.

4D kernels (v0.5)

4D input follows the same design: hyperspherical-shell radial reduction with full-4D moments (sigma^2 = <x^2+y^2+z^2+w^2>, verified = 8 D t exactly: 2 d D t with d = 4), inscribed hypersphere only, true voxel bin counts (shell occupancy grows ~ 2 pi^2 r^3). Anisotropy: generalized FA (sqrt(d/(d-1) ...)) and Q4 = <sum n_i^4> - 3/(d+2) = <...> - 1/2 (+0.5 = axis-aligned; the 8-fold nearest-neighbour shell is excluded via r >= 2 as in 2D/3D). S(k, omega) uses the d=4 zonal basis 2 J1(kr)/(kr) ("generalized_hankel_j1"), validated against the exact Gaussian symbol to ~4%.

python -m kernel_viewer.cli demo4d

Physics note — wavefront dilution vs dimension. A sharp ballistic front dilutes as 1/r^{d-1}: in 4D the source-site value of a shell kernel dies as ~ t^{-3} and the radial transform's oscillation envelope decays ~ t^{-3/2}, so S(k, omega) front edges are even softer than the 3D plateau and omega_peak underestimates the front velocity more strongly. Practically: front kernels in high d have very short clean windows (the E/V underflow masking and edge-fraction guards do the bookkeeping), and a true ballistic shell can read as superdiffusive if the window only covers the width transient sigma^2 = (vt)^2 + w^2. Diffusive classification is unaffected (sigma^2 ~ t is dimension-independent); the return probability K(0,t) ~ t^{-d/2} just decays faster.

Sliding-window regime tracking (v0.6)

kernel-viewer track data.npz --window 28 --stride 6

track_regimes(kernel, window, stride) classifies rolling time windows and flags windows where the coherence class changes -- e.g. a broadband/monotone kernel developing a long-lived recurrent coherent mode. This is generic change detection: the reliable signal is the coherence axis; the transport exponent inside a short window is indicative only, and a window must span >= 2 oscillation periods before RING_RECURRENT can be called. The synthetic coherent_onset2d model and a regression test pin this behavior.

Bundled real data

examples/ ships four kernels measured by exact dynamical typicality (sparse Krylov, no tensor-network truncation) on quantum spin chains:

file	system	classifier output
xxz_Sz_diffusive.npz	XXZ Delta=1.5, conserved Sz, N=16	superdiffusive (p=1.21, still descending toward diffusion), MONOTONE
xxz_Sx_integrable.npz	same chain, non-conserved Sx	RING_RECURRENT (integrable revivals)
ising_q_chaotic.npz	tilted-field Ising energy density, N=12	RING_TRANSIENT (chaotic: the ring heals)
longrange_Sz_a1.5.npz	long-range XXZ alpha=1.5, conserved Sz, N=16	ballistic-window + RING_RECURRENT (prethermal coherence)

These four span the coherence taxonomy with real quantum data and double as regression tests.

Honest limitations

• 1D and 2D kernels on uniform grids only (no 3D, no irregular sampling).
• 2D: radial bins at small r contain few pixels (noisy P(0), P(1)); statistics stop at the inscribed circle, so the usable radial range is min(Lx, Ly)/2; strongly anisotropic kernels make the radial profile a mixture of directions — ring/monotonicity calls then carry a warning but can still be smearing artifacts; S(k, omega) is not implemented for 2D (the radial transform is a Hankel, not a cosine, transform).
• 2D/3D/4D memory: kernels are held in RAM as float64 (store float32 on disk). 4D is large: an 11 x 25^4 kernel is ~34 MB plus distance grids; keep L <= ~25. The inscribed-hypersphere radial range is short (r_max = L//2), so 4D tail discrimination often returns UNKNOWN.
• Radial S(k, omega) assumes isotropy and carries ~10% binning accuracy; anisotropic spectra are not implemented. Frequency resolution is ~ pi / t_max in all dimensions.
• 3D ballistic shells: the width transient sigma^2 = (vt)^2 + w^2 biases short-window exponents downward — slow fronts in small boxes can read as superdiffusive.
• E(t) and V(t) are normalized by K(0, t): for oscillatory kernels the source-site value passes through zero (wave nodes) and both spike — read the episode structure, not the spike magnitudes.
• The transport exponent is the exponent of your time window — short windows report transients (the bundled XXZ data is a documented example).
• S(k, omega) resolution is ~ pi / t_max: short series give coarse frequency peaks.
• Tail discrimination needs spatial range; profiles with < ~6 usable radii return UNKNOWN.
• Boundary effects are flagged via the edge fraction (default cut 0.3) and excluded from fits, but small systems simply have small clean windows.

MIT license.