zkit.mwigner.covariance

zkit.mwigner.covariance — phase-space covariance analysis of the 2D electron wavefunction, integrated into zkit.

This module implements ONLY the technically-sound parts of a proposed “high-dimensional entanglement” extension. Deliberately EXCLUDED: * the “Symplectic Principal Component (SPC) qubit” — a single linear quadrature Q = v . R is a continuous variable, NOT a two-level system; projecting a CV state onto Q>0 / Q<0 does not define a qubit, and the proposed orthogonal rotation is not a symplectic (canonical) transformation, so the slice-FFT recipe is not a valid coordinate change. The correct CV diagnostic is the symplectic spectrum of the covariance matrix below. * any “qubit / ququart capacity limit” comparison — the von Neumann entropy of a continuous-variable reduced state has no d-level bound; such a limit applies only to discrete-d systems.

Provided

compute_4d_covariance(psi_2d, dx, dy) -> Sigma (4x4, ordered x,px,y,py) symplectic_eigenvalues(Sigma) -> symplectic spectrum (>= 1/2 for a physically-allowed state; = 1/2 iff the (4D) state is pure) effective_schmidt_rank(eigenvalues) -> N_eff = 1 / sum(lambda_i^2) schmidt_spectrum(rho_or_eigs) -> the reduced-state Schmidt eigenvalues (for plotting)

All momentum expectation values use the SPECTRAL (FFT) derivative method <p_x> = -i ∫ Ψ* ∂_x Ψ dx dy <p_x^2> = -∫ Ψ* ∂_x^2 Ψ dx dy which is exact to machine precision on a uniform grid for the band-limited (Gaussian-decaying) states encountered here, in contrast to the O(dx^2) central-difference error of a finite-difference gradient. The covariance matrix therefore matches its closed-form analytic value to ~1e-14 regardless of grid spacing.

NOTE (spatially-varying mass): the TDSEZ wavefunctions consumed here are already propagated with the mass-corrected kinetic operator T = -∫ ε(x,y) ∇B_j · ∇B_i dx dy , ε(x,y) = m(x,y) = 1 - 0.84 exp(-…) (poisson_bsp.cpp). The stored ψ(r) is therefore the physical wavefunction in the m(x,y) geometry, and the flat -i∇ momentum operator used below is the appropriate one for that stored field – no separate mass correction is applied or required. (An earlier caveat warning of a flat-mass approximation in the dot core is withdrawn: the mass physics is already contained in the wfs.)

zkit.mwigner.covariance.compute_4d_covariance(psi_2d, dx, dy)

4x4 covariance matrix of R = (x, p_x, y, p_y).

Ordered [x, p_x, y, p_y]. Built from the wavefunction normalised to unit 2D probability. Momentum moments use the GRADIENT method (p_x = -i ∂_x, p_x^2 = -∂_x^2), avoiding FFT phase/origin artifacts.

The covariance is the centred, symmetrised matrix Sigma_ij = 1/2 <{R_i, R_j}> - <R_i> <R_j> , with R = (x, p_x, y, p_y). For a pure 2D Gaussian this gives symplectic eigenvalues nu = 1/2 exactly; mixed/delocalised states have nu > 1/2 (never < 1/2, by the uncertainty principle).

Returns:

Sigma

Return type:

(4, 4) real symmetric covariance matrix.

Parameters:

psi_2d (ndarray)
dx (float)
dy (float)

zkit.mwigner.covariance.symplectic_eigenvalues(Sigma)

Symplectic eigenvalues ν_k of the 4x4 covariance matrix.

For a 4D phase space they come in pairs; a physically-allowed state has ν_k >= 1/2 (in ħ=1 units), and ν_k = 1/2 for ALL k iff the state is pure. Mixedness / entanglement with the traced-out mode shows up as ν_k > 1/2. This is the rigorous continuous-variable diagnostic (replacing the invalid “SPC qubit” construction).

Sigma is ordered [x, p_x, y, p_y]; the symplectic form must pair (x, p_x) and (y, p_y), i.e. it is block-diagonal with a 2x2 [[0, 1], [-1, 0]] block on each pair (NOT the [[0,I],[-I,0]] block form, which would pair the two coordinates instead of coordinate with its conjugate momentum).

Parameters:: Sigma (ndarray)
Return type:: ndarray

zkit.mwigner.covariance.effective_schmidt_rank(eigenvalues)

Effective Schmidt rank N_eff = 1 / Σ λ_i^2 from the Schmidt eigenvalues λ_i of the reduced density matrix ρ(x,x’).

NOTE: N_eff and the von Neumann entropy S_VN = -Σ λ_i ln λ_i are BOTH functions of the SAME Schmidt spectrum; they are not independent proofs. N_eff is reported as a complementary, intuitive measure of multi-modality (e.g. N_eff ≈ 9 means the reduced state spans ~9 effective modes), not as separate evidence.

Parameters:: eigenvalues (ndarray)
Return type:: float

zkit.mwigner.covariance.schmidt_spectrum(rho_or_eigs, dx=None)

Return the Schmidt eigenvalues λ_i of the reduced density matrix ρ(x,x’) (tracing over y). Accepts either the full rho (dx required to normalise the trace) or pre-computed eigenvalues.

Parameters:: dx (float)
Return type:: ndarray

zkit.mwigner.covariance.gaussian_purity(symplectic_eigs)

Purity of the BEST-FIT GAUSSIAN state, from its symplectic eigenvalues ν_k.

For an n-mode Gaussian state (here n = 2) the Gaussian purity is

μ_G = 1 / ∏_{k=1}^{n} (2 ν_k) .

A pure Gaussian has ν_k = 1/2 for all k, giving μ_G = 1. Any physically-allowed state has μ_G ∈ (0, 1].

IMPORTANT: μ_G is the purity of the Gaussian state with the same covariance matrix, NOT the purity of the true (possibly non-Gaussian) state. To test for non-Gaussian structure compare μ_G against the TRUE purity μ_true = Tr ρ² (from the wavefunction); μ_true < μ_G indicates the real state is “more mixed” than its Gaussian fit — i.e. contains non-Gaussian features (Fock/cat/ higher-order correlations). CAUTION: for the strongly ionised snapshots the symplectic eigenvalues become huge (the electron is delocalised over hundreds of a.u.), so μ_G underflows toward 0 and the comparison μ_true > μ_G is an artefact of the underflow, not a sign of Gaussianity. The diagnostic is meaningful in the near-pure / moderately-mixed regime (early snapshots), not at extreme delocalisation.

Parameters:: symplectic_eigs (ndarray)
Return type:: float

zkit.mwigner.covariance.principal_components(Sigma)

Standard eigendecomposition of the covariance matrix Σ.

Returns (eigvals, eigvecs) with eigvals descending. These are the ordinary (not symplectic) eigenvalues and eigenvectors of Σ: the variances along the uncorrelated normal modes of the phase-space distribution, and the linear combinations of (x, p_x, y, p_y) that realise them. This is the legitimate “true independent modes” diagnostic — it shows whether the dominant spread is along a pure axis (e.g. purely x) or a rotated mixture (e.g. 0.8 x + 0.6 p_y), evidencing continuous-variable (not separable spatial) structure.

NOTE: this is NOT the “symplectic principal component qubit”. A principal component of Σ is a direction of large variance in phase space; it is a continuous variable, not a two-level system, and must not be interpreted as a qubit. The dominant eigenvector is reported only as a descriptive statistic of where the wavepacket’s spread lives.

Parameters:: Sigma (ndarray)
Return type:: tuple

zkit.mwigner.covariance.covariance_diagnostics(psi_2d, dx, dy, rho=None)

One-call bundle of the physically-sound covariance diagnostics for a single 2D wavefunction snapshot.

Returns a dict with: Sigma : 4x4 covariance matrix [x, p_x, y, p_y] diag : variances {Sxx, Syy, Spxpx, Spyy} offdiag : key covariances {Sxpx, Sypy, Sxy, Spxpy, xpy, ypx} nu : symplectic eigenvalues (Williamson) mu_G : Gaussian-fit purity (gaussian_purity) mu_true : true purity Tr rho^2 (from reduced x-density matrix) non_gaussian : mu_true < mu_G (None if mu_G underflowed) pc_evals : principal-component eigenvalues of Sigma (desc) pc_evecs : principal-component eigenvectors (columns) All physics is read from the wavefunction; nothing is hard-coded.

Parameters:

psi_2d (ndarray)
dx (float)
dy (float)
rho (ndarray)

Return type:

dict