Periphery functions and classes

Some functions that can be used, for instance, for post-processing of optimal solutions. This includes numerical approximation of the displacement interpolation.

Data structures for couplings and weighted point clouds

First two sparse data structures for storing kernel / coupling matrix information. They are implementations of the scipy.sparse.csr_matrix and coo_matrix formats. Coupling information in these data structures can usually be obtained from a Sinkhorn solver object after solving by calling the appropriate method.

class MultiScaleOT.TSparseCSRContainer

Sparse container for coupling data, using the scipy.sparse.csr_matrix format.

__init__(self: MultiScaleOT.TSparseCSRContainer, data: numpy.ndarray[numpy.float64], indices: numpy.ndarray[numpy.int32], indptr: numpy.ndarray[numpy.int32], xres: int, yres: int) → None
getDataTuple(self: MultiScaleOT.TSparseCSRContainer) → tuple

Return list of non-zero entries, column indices, and row separation indices.

class MultiScaleOT.TSparsePosContainer

Sparse container for coupling data, using the scipy.sparse.coo_matrix format.

__init__(self: MultiScaleOT.TSparsePosContainer, mass: numpy.ndarray[numpy.float64], posX: numpy.ndarray[numpy.int32], posY: numpy.ndarray[numpy.int32], xres: int, yres: int) → None
getDataTuple(self: MultiScaleOT.TSparsePosContainer) → tuple

Return list of non-zero values, row and column indices.

The next data structure is for a list of particles. For example, such objects are generated by the displacement interpolation methods from coupling data objects.

class MultiScaleOT.TParticleContainer

Container for list of mass particles, contains an array of masses and an array for locations.

__init__(self: MultiScaleOT.TParticleContainer, mass: numpy.ndarray[numpy.float64], pos: numpy.ndarray[numpy.float64]) → None
Parameters:

  • mu – 1d double array of particle masses

  • pos – 2d double array of particle locations

getDataTuple(self: MultiScaleOT.TParticleContainer) → tuple

Return list of masses and positions.

Displacement interpolation

MultiScaleOT.interpolateEuclidean(couplingData: MultiScaleOT.TSparsePosContainer, posX: numpy.ndarray[numpy.float64], posY: numpy.ndarray[numpy.float64], t: float) → MultiScaleOT.TParticleContainer

Compute displacement interpolation for Wasserstein-p distance in Euclidean space.

Parameters:

  • couplingData – TSparsePosContainer containing non-zero entries of coupling in sparse POS format

  • posX – 2d numpy.float64 array containing positions of first marginal points

  • posY – 2d numpy.float64 array containing positions of second marginal points

  • t – float in [0,1], gives time at which to compute interpolation. t=0: first marginal, t=1: second marginal, t=0.5: midpoint.

MultiScaleOT.interpolateEuclideanHK(couplingData: MultiScaleOT.TSparsePosContainer, muXEff: numpy.ndarray[numpy.float64], muYEff: numpy.ndarray[numpy.float64], muX: numpy.ndarray[numpy.float64], muY: numpy.ndarray[numpy.float64], posX: numpy.ndarray[numpy.float64], posY: numpy.ndarray[numpy.float64], t: float, HKscale: float) → MultiScaleOT.TParticleContainer

Compute displacement interpolation for Hellinger–Kantorovich distance in Euclidean space.

Parameters:

  • couplingData – TSparsePosContainer containing non-zero entries of coupling in sparse POS format

  • muXEff – first marginal of coupling (which can be different from input measure on first marginal)

  • muYEff – second marginal of coupling

  • muX – input measure on first marginal

  • muY – input measure on second marginal

  • posX – 2d numpy.float64 array containing positions of first marginal points

  • posY – 2d numpy.float64 array containing positions of second marginal points

  • t – float in [0,1], gives time at which to compute interpolation. t=0: first marginal, t=1: second marginal, t=0.5: midpoint.

  • HKscale – scale parameter determining trade-off between transport and mass change. Maximal travelling distance is given by pi/2*HKscale.

MultiScaleOT.projectInterpolation(particles: MultiScaleOT.TParticleContainer, img: numpy.ndarray[numpy.float64]) → None

Projects a TParticleContainer object (usually storing a displacement interpolation) to a grid via bi-linear interpolation.

Parameters:

  • particles – TParticleContainer storing positions and locations of a list of particles in d dimensions

  • img – d-dimensional numpy.float64 array to which the particles should be rasterized

The mass of each particle is split to the nearest pixels of img, weighted by the relative position along each axis.