torchcell.losses.distributional.pit_ks

pit_ks(pit: Tensor) → Tensor

Kolmogorov-Smirnov distance between the PIT distribution and Uniform(0,1).

One scalar for the whole PIT histogram – the sup-norm gap between the empirical CDF of the pooled PIT values and the uniform CDF that perfect calibration implies:

\[D = \sup_{u\in[0,1]} \big| F_N(u) - u \big| = \max_{i=1..N} \max\!\Big(\tfrac{i}{N} - p_{(i)},\; p_{(i)} - \tfrac{i-1}{N}\Big),\]

with \(p_{(1)}\le\dots\le p_{(N)}\) the sorted PIT values. 0 is perfect; larger is worse, in either direction (it is a distance, so it does not say WHICH way – read coverage() or the histogram shape for that).

Comparable WITHIN a head, not ACROSS distributional modes. A calibrated quantile head on the default tau in [0.05, 0.95] grid parks ~5% of its PIT mass exactly at 0 and ~5% exactly at 1 (see _quantile_pit()), which alone forces \(D \approx 0.05\) even when the head is perfect. A parametric head has no such floor. Comparing pit_ks between a quantile arm and a Gaussian arm therefore measures the grid, not the model. Use coverage() for cross-mode comparison – it evaluates the CDF at interior points where no mode has a structural artifact – and use pit_ks to track one head across epochs or hyperparameters.

Parameters:

pit – PIT values, any shape (all entries are pooled and flattened).

Returns:

Scalar KS distance in [0, 1].