Smoothing#

transport.smooth() blends target centers. Its density and log_density evaluate the forward map’s unnormalized change-of-variables density. pullback(..., candidate=...) instead maps a reference law to source coordinates using the fixed candidate. It returns a Law for sampling and moments. These are distinct constructions: the forward density is not the pullback law’s PDF. See the mathematical guide for examples and formulas.

Transport.smooth(temperature=None)[source]#

Return a SmoothMap that blends target centres instead of choosing one.

temperature must be positive, in the units of potential. Larger values give a smoother map. None uses 100 times the median winning margin over targets at a different radius, retaining margins greater than 1e-10 in potential units. Probes resample the sources with 2% covariance-scaled Gaussian jitter (at least 4000 points, seed 0). The choice is cached; if no margin qualifies, use 0.05 times the source scale. An explicit temperature bypasses this calculation.

class yemale.ot.smoothing.SmoothMap[source]#

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.

__call__(point)[source]#

Map each source point to a softmax average of target centres.

\[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.

potential(point)[source]#

Return the smooth potential; its gradient is this map.

\[\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.

jacobian(point)[source]#

Differentiate the map with respect to original source coordinates.

\[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.

map_jacobian(point)[source]#

Return (self(point), self.jacobian(point)) with shared computation.

log_density(points)[source]#

Return the log of density for one point or a batch.

density(points)[source]#

Evaluate the smooth density in source coordinates.

\[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.

reference_distribution(point)[source]#

Return the reference-cell mixture weighted by the smooth map at one point.

Requires a Reference target; samples stay in reference coordinates.

inverse(target, *, candidate)[source]#

Map reference points to a softmax average of all augmented sources.

\[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.

pullback(target_law, *, candidate)[source]#

Map a reference law through the augmented dual map at one candidate.

\[\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.