zkit.mwigner.current

zkit.mwigner.current — the Wigner (phase-space) current computed from the marginal Wigner function W(x, p_x) produced by zkit.mwigner.transform.get_wigner_research().

The Wigner function obeys a continuity equation in phase space,

∂_t W(x, p) + ∂_x J_x(x, p) + ∂_p J_p(x, p) = 0 ,

with the exact (approximation-free) x-streaming current

J_x(x, p) = p * W(x, p) .

For a potential V(x) the p-current is

J_p(x, p) = -V’(x) * W(x, p) + Q(x, p) ,

where Q is the non-local Moyal quantum-force term. For free motion (V=0) and for any QUADRATIC potential (e.g. the harmonic oscillator) the quantum force Q vanishes IDENTICALLY (the Wigner function then obeys the classical Liouville equation), which makes these the natural analytical known solutions to benchmark against.

The current is therefore as accurate as the Wigner transform itself: J_x is an exact algebraic product of W with the momentum grid p, and the only numerical ingredient is the divergence (∂_x, ∂_p), taken with spectral (FFT) derivatives for machine-precision accuracy on band-limited states.

The Moyal quantum force Q for a general (non-quadratic) potential is added with moyal_quantum_force(); see that function. It is NOT needed for the analytical benchmarks (free, harmonic oscillator).

NOTE: this module consumes the marginal Wigner (y integrated out), so it recovers only x- and p_x-dependent currents. A full 4D Wigner would be needed for y- or p_y-currents.

zkit.mwigner.current.deriv_x(F, dx)

zkit.mwigner.current.deriv_p(F, dp)

zkit.mwigner.current.current_x(W, p)

J_x(x, p) = p * W(x, p) — exact, no approximation. p is the 1D momentum grid; it broadcasts over the columns of W.

zkit.mwigner.current.current_p_classical(W, x, Vp)

J_p(x, p) = -V’(x) * W(x, p) — the classical force term. Valid (exact) for free motion and any quadratic potential (Q=0 there). Vp = dV/dx(x).

zkit.mwigner.current.current_p(W, x, Vp=None, moyal_terms=None)

Full p-current. With Vp given, returns the classical force term (-V’(x) W). If moyal_terms (a dict of V derivatives, see moyal_quantum_force) is supplied, the non-local quantum force is added. For free / quadratic V the quantum force is zero, so this equals the classical term.

zkit.mwigner.current.moyal_quantum_force(W, x, p, V_derivs)

Non-local quantum-force contribution Q(x, p) to J_p for a general V(x).

From the Moyal/Wigner equation (hbar=1, m=1), d_t W = -p d_x W + V’(x) d_p W + R_Q , where R_Q = moyal_residual(…) is the Moyal odd-derivative series. In the continuity form d_t W + d_x(p W) + d_p J_p = 0 one identifies J_p = -V’(x) W + Q , with d_p Q = -R_Q . Hence Q is the (spectral) p-antiderivative of -R_Q. For a p-localised Wigner the physically-correct integration constant makes int_p Q dp = 0 (the quantum force carries no net p-momentum), so we subtract the p-mean of the antiderivative.

V_derivs: dict {‘Vp’: dV/dx, ‘V3’: d3V/dx3, ‘V5’: d5V/dx5, ‘V7’: …} (only odd derivatives enter). Returns Q with the same shape as W.

zkit.mwigner.current.moyal_residual(W, x, p, V_derivs)

Quantum residual R_Q(x, p) = ∂_t W - (-p ∂_x W + V’(x) ∂_p W) for a general V.

V_derivs is a dict {‘Vp’: dV/dx, ‘V3’: d³V/dx³, ‘V5’: d⁵V/dx⁵, …} (only the odd derivatives enter; even derivatives vanish by antisymmetry of the Moyal bracket). Implemented with spectral ∂_p derivatives (machine accuracy).

For free (V=const) and quadratic (V’’’=V⁵=…=0) potentials this is EXACTLY ZERO, which is the benchmark that proves the classical current is sufficient there. For cubic/quartic/etc. potentials it is non-zero and captures the non-locality of the Wigner dynamics.

zkit.mwigner.current.continuity_residual(W, x, p, dWdt, Vp=None, moyal_derivs=None)

Compute the continuity-equation residual

R(x, p) = ∂_t W + ∂_x(p W) + ∂_p J_p ,

which must be ~0 for a correctly computed current. dWdt is the analytic (or reliably computed) time derivative of W. Vp = dV/dx for the classical p-current; if moyal_derivs is given, the Moyal quantum residual is added so that the full equation is checked for arbitrary V.

For the analytical benchmarks (free, harmonic oscillator) Vp is None or the HO force, moyal_derivs is None, and R should be ~1e-10 or better.

zkit.mwigner.current.compute_current(W, x, p, dWdt=None, Vp=None, moyal_derivs=None)

Return a dict with Jx, Jp, and (optionally) the continuity residual.

zkit.mwigner.current.linf_norm(F)