Skip to content

Velocity PDFs

The line-of-sight pairwise velocity PDF \(\mathcal{P}(v_\text{los}\mid r_\perp, r_\parallel)\) is the heart of the streaming model — its shape sets the prediction accuracy. liulu provides a ladder of PDFs, all subclasses of VelocityPDF, built from the same PairwiseVelocityMoments.

Each PDF takes the radial–tangential moments, projects them to the line of sight via project_to_los to get the LOS moments at \((r_\perp, r_\parallel)\), then realises a distribution matching those moments.

Gaussian

GaussianPDF — matches the LOS mean and variance only. Fast, robust, and the right baseline, but it cannot capture the skewed, leptokurtic shape of the real pairwise velocity PDF, so it badly over-/under-shoots the \(\xi_2\) Fingers-of-God dip.

Skew-\(t\)

SkewTPDF — the Azzalini–Capitanio skew-\(t\), matching four LOS moments (mean, variance, skewness, excess kurtosis). The moment-matching map \((\gamma_1, \gamma_2) \to (\alpha, \nu)\) has no closed form, so it is pre-tabulated on a \((\gamma_1, \gamma_2)\) grid and cached at liulu/data/skewt_param_table.npz (rebuilt on first use; bump _SKEWT_TABLE_VERSION if the grid format changes). Points where the solver fails fall back to Gaussian automatically.

The generalized-hyperbolic distribution (GHD) is a normal variance–mean mixture: a Gaussian whose variance is itself a generalized-inverse-Gaussian (GIG) random variable. It reproduces the same four moments as the skew-\(t\) but with a sharper peak and semi-heavy exponential tails that match the measured PDF far better — at fixed moments it beats the skew-\(t\) shape.

NIG — the default

NIGPDF is the GHD with class index \(\lambda=-1/2\) (the normal-inverse-Gaussian special case). Its key advantage: the moment→parameter inversion is closed-form, so no tabulation is needed (unlike the skew-\(t\)). Given the LOS mean, variance, skewness \(\gamma_1\) and excess kurtosis \(\gamma_2\) (valid where \(\gamma_2 > \tfrac{5}{3}\gamma_1^2\)):

\[ \rho^2 = \frac{\gamma_1^2}{3\gamma_2 - 4\gamma_1^2}, \quad \zeta = \frac{9\rho^2}{\gamma_1^2}, \quad \alpha = \sqrt{\frac{\zeta}{\sigma^2 (1-\rho^2)^2}}, \quad \beta = \rho\,\alpha, \quad \delta = \frac{\zeta}{\gamma}, \quad \mu = \text{mean} - \frac{\delta\beta}{\gamma}, \]

with \(\gamma=\sqrt{\alpha^2-\beta^2}\). This is NIGPDF — the recommended production default: analytic, no table, and the best four-moment shape.

General \(\lambda\) and tabulation

GeneralizedHyperbolicPDF lets the class index \(\lambda\) be any value (scalar or a callable lam(r_perp, r_par)). Away from \(\lambda=-1/2\) the shape match \((\gamma_1,\gamma_2)\to(\zeta,\rho)\) has no closed form and is solved numerically (a vectorized damped Newton step). The GIG mixing cumulants enter through ratios \(R_n = K_{\lambda+n}(\zeta)/K_\lambda(\zeta)\) of modified Bessel functions; note the mean offset is \(\beta\delta R_1/\gamma\) (with \(R_1=1\) only for NIG).

TabulatedGHPDF makes a scale-dependent \(\lambda(r_\perp,r_\parallel)\) affordable: it solves the expensive shape once on a coarse \((r_\perp, r_\parallel)\) grid and interpolates, taking the first two moments from the exact local projection. Outside the grid it degrades gracefully to analytic NIG. Build a \(\lambda\) table into a callable with scale_dependent_lambda.

Which should I use?

The halo-catalogue validation settled the ranking:

Recommended ladder

  1. NIGPDF — analytic, zero-tuning, the production default. ~10× lower \(\xi_2\)-dip residual than the skew-\(t\) at fixed moments.
  2. A single tuned constant-\(\lambda\) GHD — cheap accuracy upgrade if you can fit one \(\lambda\) to your sample.
  3. A measured-PDF emulator — for the last percent.

A scale-dependent \(\lambda(r)\) is not recommended: calibrated either on the PDF shape or directly on the \(\xi_2\) observable, it at best ties a single tuned constant in-sample and fails to generalise across bias and gravity (overfitting). See the validation for the evidence.