From c601f7dae9491285fb3749c706ed1ab608ce58fa Mon Sep 17 00:00:00 2001 From: Evan Palmer Date: Tue, 10 Nov 2026 15:14:43 -0800 Subject: [PATCH] Add heuristics for estimating bandwidths --- lrax/common/kernels.py | 89 ++++++++++++++++++++++++++++++++++++++++++ pyproject.toml | 2 +- uv.lock | 2 +- 3 files changed, 91 insertions(+), 2 deletions(-) diff --git a/lrax/common/kernels.py b/lrax/common/kernels.py index 435d6e9..9d3d235 100644 --- a/lrax/common/kernels.py +++ b/lrax/common/kernels.py @@ -463,3 +463,92 @@ def kernel(x: Point, y: Point) -> Scalar: return jax.tree.reduce(jnp.multiply, values) return kernel + + +def median_heuristic( + xs: Shaped[Point, "n"], + *, + coordinatewise: bool = False, + distance: DistanceFn = _euclidean, +) -> Float[Array, "?*sigma"]: + r"""Median heuristic for the bandwidths of a kernel. + + - "A Kernel Two-Sample Test", Arthur Gretton, Karsten M. Borgwardt, Malte J. Rasch, + Bernhard Schölkopf, and Alexander Smola. + - "Large Sample Analysis of the Median Heuristic", Damien Garreau, Wittawat + Jitkrittum, and Motonobu Kanagawa. + + .. math:: + + \sigma = \operatorname{median}_{i < j} \left\|d(x_{i}, x_{j})\right\|_{2} + + where :math:`d` is the distance function. The coordinatewise variant takes the + median of each coordinate's magnitude :math:`|d_{k}(x_{i}, x_{j})|` instead. + + Parameters + ---------- + - `xs`: The samples, with a leading sample axis on each leaf. + - `coordinatewise`: Whether to give each coordinate of the distance its own + bandwidth. Keyword-only argument. + - `distance`: See `gaussian`. Keyword-only argument. + + Returns + ------- + The bandwidths, a scalar or an array matching the output of `distance` when + `coordinatewise` is set. + """ + n = jnp.shape(jax.tree.leaves(xs)[0])[0] + + if n < 2: + raise ValueError(f"`xs` must hold at least two samples. Got {n}.") + + rows, cols = jnp.triu_indices(n, k=1) + + def pick(indices: Array) -> Point: + return jax.tree.map(lambda leaf: jnp.asarray(leaf)[indices], xs) + + distances = jax.vmap(distance)(pick(rows), pick(cols)) + + if coordinatewise: + return jnp.median(jnp.abs(distances), axis=0) + + return jnp.median(jnp.linalg.norm(distances.reshape(rows.size, -1), axis=-1)) + + +def transition_heuristic( + trajectories: Shaped[Point, "n steps"], + *, + distance: DistanceFn = _euclidean, +) -> Float[Array, "?*sigma"]: + r"""Transition heuristic for the bandwidths of a kernel on the states of a + trajectory. + + .. math:: + + \sigma_{k} = \operatorname{std}_{i, t}\, d_{k}(x_{i, t + 1}, x_{i, t}) + + where :math:`d_{k}` is the :math:`k`th coordinate of the distance function and the + standard deviation pools the one-step increments over every trajectory and step. + + Parameters + ---------- + - `trajectories`: The trajectories, with leading trajectory and step axes on each + leaf. + - `distance`: See `gaussian`. Keyword-only argument. + + Returns + ------- + The bandwidths, matching the output of `distance`. + """ + steps = jnp.shape(jax.tree.leaves(trajectories)[0])[1] + + if steps < 2: + raise ValueError(f"`trajectories` must hold at least two steps. Got {steps}.") + + def pool(leaf: ArrayLike, start: int, stop: int) -> Array: + leaf = jnp.asarray(leaf)[:, start:stop] + return leaf.reshape(-1, *leaf.shape[2:]) + + current = jax.tree.map(lambda leaf: pool(leaf, 0, steps - 1), trajectories) + following = jax.tree.map(lambda leaf: pool(leaf, 1, steps), trajectories) + return jnp.std(jax.vmap(distance)(following, current), axis=0) diff --git a/pyproject.toml b/pyproject.toml index d06fcf7..fcbbd8f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi" [project] name = "lrax" -version = "0.5.0" +version = "0.6.0" description = "JAX library for robotics learning research" readme = "README.md" requires-python = ">=3.12" diff --git a/uv.lock b/uv.lock index b5a4fb1..ef47ad0 100644 --- a/uv.lock +++ b/uv.lock @@ -1095,7 +1095,7 @@ wheels = [ [[package]] name = "lrax" -version = "0.5.0" +version = "0.6.0" source = { editable = "." } dependencies = [ { name = "equinox" },