Compare finite probability measures

Exact methods target the unregularized transport problem. Sinkhorn uses `cost + epsilon * sum(plan * (log(plan) - 1))`; the transport component and full regularized objective are returned separately. A rooted regularized transport component is not an exact Wasserstein distance or a metric. The network-simplex backend normalizes active costs internally and returns objectives and potentials in the supplied cost units. Its normalized dual checks use the maximum active cost (one when all active costs are zero) and total mass as scales; these checks do not promise relative accuracy with respect to an arbitrarily small optimum within a large cost matrix.

Usage

ot_distance(
  x,
  y,
  p = 2,
  method = c("auto", "exact", "sinkhorn", "1d"),
  epsilon = 0.1,
  cost = NULL,
  control = list(),
  return_plan = FALSE
)

Arguments

x, y

Finite measures or inputs convertible by `as_ot_measure()`.

p

Wasserstein order, at least one.

method

`auto` uses monotone transport for scalar supports and network simplex otherwise; `exact`, `sinkhorn`, and `1d` select explicit backends.

epsilon

Positive entropy coefficient for Sinkhorn.

cost

Optional explicit `ot_cost()` object.

control

Named controls. Exact: `maxiter`. Sinkhorn: `maxiter`, `atol`. The finite 1D backend has no iteration controls.

return_plan

Whether to retain the plan in the R result. This does not promise a matrix-free solver or avoid internal dense allocations.

Value

A `t4transport_comparison` with objective components, method, status, residuals, and optional plan. Non-success produces a warning and an explicit failed/limited result, with no claimed exact Wasserstein distance.

Examples

x <- ot_measure(c(0, 2), c(1, 3))
y <- ot_measure(c(0, 3), c(1, 1))
ot_distance(x, y)
#> Transport comparison | 1d | euclidean | order 2 
#> Status: SUCCESS ( finite_monotone_transport )
#> Transport cost: 1.5 
#> Wasserstein distance: 1.224745 
ot_distance(x, y, method = "sinkhorn", epsilon = 0.5)
#> Transport comparison | sinkhorn | euclidean | order 2 
#> Status: SUCCESS ( marginal_tolerance )
#> Transport cost: 1.5 
#> Rooted transport component: 1.224745 
#> Regularized objective: 0.4801396