Source code for yemale.ot.smoothing

"""Smooth transport, augmented dual maps, and source distributions."""

from dataclasses import dataclass
from functools import cached_property

import numpy as np

from yemale._array import restore, rows

from ._core import smooth
from .law import Law
from .transport import Transport


[docs] @dataclass(eq=False) class SmoothMap: """A smooth transport that blends target centres instead of choosing one. Create with ``transport.smooth()``. Source queries follow Transport's shape conventions. ``inverse`` blends the fitted sources and a supplied candidate. """ _transport: Transport _tau: float # Public temperature divided by the fitted source scale. def __repr__(self): temperature = self._tau * self._transport._source_scale return f"SmoothMap(transport={self._transport!r}, temperature={temperature})"
[docs] def __call__(self, point): r"""Map each source point to a softmax average of target centres. .. math:: T_\tau(z)=\sum_{j=1}^{n+1}p_{\tau,j}(z)m_j,\qquad p_{\tau,j}(z)= \frac{e^{(\langle z,m_j\rangle-\phi_j)/\tau}} {\sum_k e^{(\langle z,m_k\rangle-\phi_k)/\tau}}. Here m_j are the targets, phi_j are the fitted offsets, and tau is ``temperature``. Accept ``(d,)`` or ``(..., d)``; keep the input shape. """ points, shape = self._transport._query(point) value = smooth.read( points, self._transport._centered_target, self._transport._affine_offsets, self._tau, ) return restore(value + self._transport._target_center, shape)
[docs] def potential(self, point): r"""Return the smooth potential; its gradient is this map. .. math:: \Phi_\tau(z)=\tau\log\sum_{j=1}^{n+1} e^{(\langle z,m_j\rangle-\phi_j)/\tau}. Here tau is ``temperature``, m_j are the targets, and phi_j the fitted offsets. Use original source coordinates; return one value per point. """ points, shape = self._transport._query(point) value = smooth.potential( points, self._transport._centered_target, self._transport._affine_offsets, self._tau, ) return restore(self._transport._scale_potential(points, value), shape)
def _statistics(self, point): """Return target points, Jacobians in normalized source coordinates, and shape.""" points, shape = self._transport._query(point) mapped, jacobian = smooth.map_jacobian( points, self._transport._centered_target, self._transport._affine_offsets, self._tau, ) mapped += self._transport._target_center return mapped, jacobian, shape
[docs] def jacobian(self, point): r"""Differentiate the map with respect to original source coordinates. .. math:: DT_\tau(z)=\frac1\tau\mathrm{Cov}_{p_\tau(z)}(m_j). The covariance uses the target centres and their softmax weights; tau is ``temperature``. Return ``(d, d)`` for one point or ``(..., d, d)`` for a batch. """ _, jacobian, shape = self._statistics(point) return restore(jacobian / self._transport._source_scale, shape)
[docs] def map_jacobian(self, point): """Return ``(self(point), self.jacobian(point))`` with shared computation.""" mapped, jacobian, shape = self._statistics(point) return restore(mapped, shape), restore( jacobian / self._transport._source_scale, shape )
def _density_coordinates(self, point): mapped, jacobian, shape = self._statistics(point) sign, logdet = np.linalg.slogdet(jacobian) # D_z T = D_x T / source_scale, with x the normalized source point. logdet -= jacobian.shape[-1] * np.log(self._transport._source_scale) # The exact Jacobian is positive definite; nonpositive determinants give zero density. return mapped, np.where(sign > 0.0, logdet, -np.inf), shape @cached_property def _target_rank(self): centered = self._transport._centered_target scale = np.abs(centered).max() return np.linalg.matrix_rank(centered / scale) if scale > 0 else 0
[docs] def log_density(self, points): """Return the log of ``density`` for one point or a batch.""" reference = self._transport._require_reference() if self._target_rank < reference.dimension: raise ValueError( "smooth density requires targets that affinely span the space" ) mapped, logdet, shape = self._density_coordinates(points) value = np.asarray(reference.logpdf(mapped)).reshape(-1) # Mask zero density first: reference logpdf can be +inf at the origin. valid = (value != -np.inf) & (logdet != -np.inf) value[~valid] = -np.inf value[valid] += logdet[valid] return restore(value, shape)
[docs] def density(self, points): r"""Evaluate the smooth density in source coordinates. .. math:: p_\tau(z)=p_\nu(T_\tau(z))|\det DT_\tau(z)|. Its integral is nu(K), not one, where K is the convex hull of the target centres. No normalization is applied. Requires a Reference target whose centres affinely span the space. Accept ``(d,)`` or ``(..., d)`` and return one value per point. """ with np.errstate(over="ignore", under="ignore"): return np.exp(self.log_density(points))
[docs] def reference_distribution(self, point): """Return the reference-cell mixture weighted by the smooth map at one point. Requires a Reference target; samples stay in reference coordinates. """ reference = self._transport._require_reference() points, _ = self._transport._query(point) if len(points) != 1: raise ValueError( f"reference_distribution expects one point; got {len(points)}. " "Call reference_distribution once per point." ) weight = smooth.weights( points, self._transport._centered_target, self._transport._affine_offsets, self._tau, )[0] return Law(reference, weights=weight)
[docs] def inverse(self, target, *, candidate): r"""Map reference points to a softmax average of all augmented sources. .. math:: Q_\tau(u;z)=\frac{\sum_{i=1}^{n+1} e^{(\langle u,\zeta_i\rangle-\Phi(\zeta_i))/\tau}\zeta_i} {\sum_{i=1}^{n+1} e^{(\langle u,\zeta_i\rangle-\Phi(\zeta_i))/\tau}}. Here zeta consists of the fitted observations followed by ``candidate``; Phi is the hard transport potential. Supply one candidate in source coordinates. ``target`` uses reference coordinates, with shape ``(d,)`` or ``(..., d)``; keep the input batch shape. This dual-side map is defined everywhere, not a numerical inverse of the forward smooth map. """ return self._augmented_inverse(candidate)(target)
def _augmented_inverse(self, candidate): """Bind one candidate and its hard potential to the dual softmax.""" transport = self._transport point, _ = transport._query(candidate) if len(point) != 1: raise ValueError( f"candidate must be one source point; got {len(point)} points" ) potential = transport._internal_potential(point, transport._maximize(point)) sites = np.concatenate((transport._normalized_sources, point)) offsets = np.r_[transport._source_potential, potential] def inverse(target): targets, shape = rows(target, sites.shape[1], "target") if not np.isfinite(targets).all(): raise ValueError("target must be finite") mapped = smooth.read( targets - transport._target_center, sites, offsets, self._tau ) return restore( transport._source_center + transport._source_scale * mapped, shape ) return inverse
[docs] def pullback(self, target_law, *, candidate): r"""Map a reference law through the augmented dual map at one candidate. .. math:: \Pi_\tau(\,\cdot\,;z)=Q_\tau(\,\cdot\,;z)_\#\nu. ``target_law`` is a Reference or Law. The candidate stays fixed across samples and expectations. Return a Law providing sample, expect, moment, mean and cov through this map. Selecting reference cells gives the corresponding component laws. """ target_law = target_law if isinstance(target_law, Law) else Law(target_law) if target_law.reference.dimension != self._transport._target.shape[1]: raise ValueError( f"target law dimension must be {self._transport._target.shape[1]}; " f"got {target_law.reference.dimension}" ) return target_law._map(self._augmented_inverse(candidate))