qdiffusivity.density

Kernel density estimator for transverse density profiles.

This module provides an Epanechnikov-kernel 1-D KDE with mirror-reflection boundary handling and a Sheather-Jones plug-in bandwidth, packaged as AnalysisBase classes so it can be applied to any AtomGroup along the confined axis of a nanoconfined simulation. Both number-density and mass-density profiles are provided; the mass density follows MDAnalysis’s LinearDensity convention of returning g/cm³.

The reusable KDE machinery (bandwidth selection, kernel evaluation, boundary mirroring, Kish effective sample size) is generalised from the per-project script zn-el/analysis/dens_kde/kde_density.py; species selection, residue COM pooling, mass-density conversion and plotting glue are left to the caller.

Theory

For evaluation point \(z_0\) and pooled samples \(\{z_j\}_{j=1}^{N}\),

\[\hat\rho(z_0) = \frac{1}{N}\sum_j K_h(z_0 - z_j),\]

with the Epanechnikov kernel

\[K_h(x) = \frac{3}{4h}\Bigl(1 - (x/h)^2\Bigr)\;\; \text{for } |x| < h, \quad 0 \text{ otherwise}.\]

\(\hat\rho\) integrates to 1 over the unbounded support.

  • Bandwidth. "auto" uses a Sheather-Jones plug-in (an Epanechnikov pilot density is built on a fine grid, its second derivative estimated by central differences, and the oracle bandwidth \(h^* = (\|K\|^2 / (N\,\mu_2(K)^2\,\widehat{\int[\hat f'']^2}))^{1/5}\) evaluated with the Epanechnikov constants \(\|K\|^2 = 3/5\), \(\mu_2(K) = 1/5\)); the Silverman rule of thumb is the fallback. "silverman" uses the rule of thumb directly, and a float fixes the bandwidth.

  • Boundary handling. Particles cannot cross the confined-region boundaries, so kernel mass that would leak beyond \([z_{\mathrm{bot}}, z_{\mathrm{top}}]\) is mirrored back inside. For each sample at \(z_j\), mirror copies at \(2z_{\mathrm{bot}} - z_j\) and \(2z_{\mathrm{top}} - z_j\) are added before kernel evaluation.

  • Effective sample size. The Kish effective sample size \(N_{\mathrm{eff}}(z_0) = (\sum_j K_h)^2 / \sum_j K_h^2\) is returned at each grid point so unreliable regions (small local sample size) can be masked.

  • Evaluation grid. n_points cell-centred points uniformly across the confined region, \(z_m = z_{\mathrm{bot}} + (m + 0.5)(z_{\mathrm{top}} - z_{\mathrm{bot}})/M\) for \(m = 0, \ldots, M-1\).

Converting the normalised KDE \(\hat\rho\) (1/length, integrates to 1) to a number density is the caller’s responsibility; for a simulation with cross-sectional area \(A\) and \(N_f\) analysis frames,

\[n(z) = \frac{N_{\mathrm{total}}}{N_f\,A}\,\hat\rho(z),\]

and a mass density follows by multiplying by \(M_{\mathrm{mol}}/N_A\) (with the appropriate \(10^{24}\) factor for Å → cm).

Functions

epanechnikov_kernel(x, h)

Epanechnikov kernel \(K_h(x) = \frac{3}{4h}(1 - (x/h)^2)\) for \(|x| < h\), zero otherwise.

kde_1d(z_data, z_eval, h, z_bot, z_top, *[, ...])

1-D Epanechnikov KDE with mirror-reflection boundary handling.

select_bandwidth(z_data, z_lo, z_hi[, method])

Select the KDE bandwidth.

sheather_jones_bw(z_data, z_lo, z_hi)

Simplified Sheather-Jones plug-in bandwidth for the Epanechnikov kernel.

silverman_bw(z_data)

Silverman's rule of thumb.

Classes

TransverseMassDensityQKDE(atomgroup, *[, ...])

Epanechnikov KDE transverse mass-density profile.

TransverseNumDensityQKDE(atomgroup, *[, ...])

Epanechnikov KDE transverse number-density profile.