DiscreteMeasure(X, w; normalize=true)
DiscreteMeasure(X)

A discrete measure supported on a finite set of points.

Representation

• X::Matrix{T}: a d × n matrix where each column represents a point in ℝ^d.
• w::Vector{T}: a vector of length n representing the weights associated with each point.
• T<:Real: the numeric type of the points and weights.
• When w is provided, weights are normalized to sum to 1 by default; set normalize=false to disable. When w is omitted, uniform weights are used (already normalized).

Examples

X = [0.0 1.0 2.0;
     0.0 0.0 0.0]
w = [1.0, 1.0, 2.0]
μ = DiscreteMeasure(X, w)  # creates a discrete measure with normalized weights
μ_uniform = DiscreteMeasure(X)  # creates a discrete measure with uniform weights

sort_1d(μ::DiscreteMeasure)

Sorts a 1-dimensional discrete measure μ in ascending order of its support points. Returns a tuple (μ_sorted, p) where μ_sorted is the sorted discrete measure and p is the permutation vector such that μ_sorted.X = μ.X[:, p].

sample_directions(M, d; rng=Random.default_rng(), seed=nothing)

Sample M random directions in d dimensions, uniformly from the unit sphere.

Arguments

• M::Integer: Number of directions to sample (must be ≥ 0).
• d::Integer: Dimension of the space (must be > 0).
• rng::AbstractRNG: Random number generator to use (default: Random.default_rng()).
• seed::Union{Integer, Nothing}: If provided, it overrides rng and initializes a new Xoshiro with the given seed.
• T::Type{<:AbstractFloat}: The floating-point type for the output (default: Float64).

Returns

• Z::Matrix{T}: A d x M matrix whose columns are the sampled directions.

radon_project(μ, θ)

Compute the Radon projection of a discrete measure μ along direction θ.

Arguments

• μ::DiscreteMeasure{T}: Discrete measure in ℝ^d.
• θ::AbstractVector{T}: Direction in ℝ^d.

Returns

• pr_μ::DiscreteMeasure{T}: The Radon projection of μ along θ, a discrete measure in ℝ.

radon_project!(pr_X, X, θ)

Compute the Radon projection of points X along direction θ, storing the result in pr_X.

Arguments

• pr_X::AbstractVector{T}: Output vector to store the projected points (must have length equal to the number of columns of X).
• X::AbstractMatrix{T}: Points in ℝ^d (each column is a point).
• θ::AbstractVector{T}: Direction in ℝ^d.

Returns

• pr_X::AbstractVector{T}: The projected points along θ.

OT1d(μ, ν; cost=(x,y)->(x-y)^2, compute_cost=true, compute_edge=false)

Compute the optimal transport between 1-dimensional discrete measures μ and ν.

Returns an OT1dResult whose fields are nothing when not requested. The edge-list fields I, J, Tm represent the transport plan: Tm[k] mass is moved from support point I[k] of μ to support point J[k] of ν.

Arguments

• μ::DiscreteMeasure: Source 1-dimensional measure.
• ν::DiscreteMeasure: Target 1-dimensional measure.
• cost::F: Cost function (default: squared distance).
• compute_cost::Bool=true: Compute the optimal transport cost.
• compute_edge::Bool=false: Compute the transport plan as an edge list.

Returns

An OT1dResult{T} with:

• cost: optimal transport cost, or nothing.
• I, J: source/target indices of each transported edge, or nothing.
• Tm: transported masses per edge, or nothing.

OT1dResult{T<:Real}

Result returned by OT1d.

Fields

• cost: optimal transport cost, or nothing if not requested.
• I: source indices of each transported edge, or nothing.
• J: target indices of each transported edge, or nothing.
• Tm: transported masses per edge, or nothing.

SOT(μ, ν; M=1000, cost=(x, y) -> (x - y)^2, rng=Random.default_rng(), seed=nothing)

Compute the Sliced Optimal Transport (SOT) distance between two discrete measures μ and ν.

Arguments

• μ::DiscreteMeasure: First discrete measure in ℝ^d.
• ν::DiscreteMeasure: Second discrete measure in ℝ^d.
• M::Integer=1000: Number of random projections to use.
• cost::Function=(x, y) -> (x - y)^2: Cost function to use in 1D optimal transport.
• rng::AbstractRNG=Random.default_rng(): Random number generator to use.
• seed::Union{Integer, Nothing}=nothing: If provided, it overrides rng and initializes a new Xoshiro with the given seed.

Returns

• d::Float64: The estimated SOT distance between μ and `ν

grad(μ, ν; M=1000, rng=Random.default_rng(), seed=nothing)

Compute the gradient of the Sliced Optimal Transport quadratic cost between two discrete measures μ and ν with respect to the support points of μ.

Arguments

• μ::DiscreteMeasure: First discrete measure.
• ν::DiscreteMeasure: Second discrete measure.
• M::Integer=1000: Number of random projections to use.
• rng::AbstractRNG=Random.default_rng(): Random number generator.
• seed::Union{Integer, Nothing}=nothing: Seed for the random number generator. If provided, it overrides rng.

Returns

• ∇::Array{Float64,2}: Gradient of the Sliced Optimal Transport quadratic cost with respect to the support points of μ.

References

• K. Nguyen, "An Introduction to Sliced Optimal Transport", 2023, Remark 4.2

SWBarycenters_free_supp(measures; η=nothing, w=nothing, n_supp=nothing, n_supp_max=500, n_supp_min=1, itmax=100, tol=1e-6, M=500, rng=Random.default_rng(), seed=nothing, normalize=true, save_it=false)

Compute the Sliced-Wasserstein barycenter of a set of discrete measures with free support using stochastic gradient descent.

Arguments

• measures::AbstractVector: Vector of discrete measures.
• η::Union{Real, Nothing}=nothing: Learning rate. If nothing, it is set automatically based on the measures.
• w::Union{AbstractVector{<:Real}, Nothing}=nothing: Weights
• n_supp::Union{Integer, Nothing}=nothing: Number of support points of the barycenter. If nothing, it is set automatically based on the measures.
• n_supp_max::Union{Integer, Nothing}=500: Maximum number of support

points if n_supp is not provided.

• n_supp_min::Union{Integer, Nothing}=1: Minimum number of support points if n_supp is not provided.
• itmax::Integer=100: Maximum number of iterations.
• tol::Real=1e-6: Tolerance for the stopping criterion.
• M::Integer=500: Number of random projections to use in the gradient computation.
• rng::AbstractRNG=Random.default_rng(): Random number generator.
• seed::Union{Integer, Nothing}=nothing: Seed for the random number generator. If provided, it overrides rng.
• normalize::Bool=true: Whether to normalize the barycenter measure.
• save_it::Bool=false: Whether to save the support points at every 20 iterations.

Returns

• DiscreteMeasure: The computed Sliced-Wasserstein barycenter.

If save_it is true, returns a tuple (iterations, barycenter) where iterations is a vector of support points at every 20 iterations.

SWk_means(measures, k; itmax=50, M_SOT=1000, M_bary=500, itmax_bary=100, tol_bary=1e-6, rng=Random.default_rng(), seed=nothing)

Performs k-means clustering of the input discrete measures using the Sliced Wasserstein distance.

Arguments

• measures::AbstractVector{DiscreteMeasure}: Vector of discrete measures to cluster.
• k::Integer: Number of clusters.
• itmax::Integer=50: Maximum number of k-means iterations.
• M_SOT::Integer=1000: Number of random projections for SOT distance computation.
• M_bary::Integer=500: Number of random projections for barycenter computation.
• itmax_bary::Integer=100: Maximum number of iterations for barycenter computation.
• tol_bary::Real=1e-6: Tolerance for barycenter computation.
• rng::AbstractRNG=Random.default_rng(): Random number generator.
• seed::Union{Integer, Nothing}=nothing: Seed for the random number generator. If provided, it overrides rng.

Returns

• assignments::Vector{Int}: Vector indicating the cluster assignment for each measure.
• centroids::Vector{DiscreteMeasure}: Vector of computed cluster centroids (barycenters).

print_full(μ)
print_full(μs)

Print a DiscreteMeasure (or a vector of them) without truncating the support.