Multinomial doubly stochastic matrices

AbstractMultinomialDoublyStochastic{N} <: AbstractEmbeddedManifold{ℝ, DefaultIsometricEmbeddingType}

A common type for manifolds that are doubly stochastic, for example by direct constraint MultinomialDoubleStochastic or by symmetry MultinomialSymmetric, as long as they are also modeled as DefaultIsometricEmbeddingType AbstractEmbeddedManifolds.

MultinomialDoublyStochastic{n} <: AbstractMultinomialDoublyStochastic{N}

The set of doubly stochastic multinomial matrices consists of all $n×n$ matrices with stochastic columns and rows, i.e.

where $\mathbf{1}_n$ is the vector of length $n$ containing ones.

The tangent space can be written as

where $\mathbf{0}_n$ is the vector of length $n$ containing zeros.

More details can be found in Section III^{[DouikHassibi2019]}.

Constructor

MultinomialDoubleStochastic(n)

Generate the manifold of matrices $\mathbb R^{n×n}$ that are doubly stochastic and symmetric.

check_manifold_point(M::MultinomialDoubleStochastic, p)

Checks whether p is a valid point on the MultinomialDoubleStochastic(n) M, i.e. is a matrix with positive entries whose rows and columns sum to one.

check_tangent_vector(M::MultinomialDoubleStochastic p, X; check_base_point = true, kwargs...)

Checks whether X is a valid tangent vector to p on the MultinomialDoubleStochastic M. This means, that p is valid, that X is of correct dimension and sums to zero along any column or row.

The optional parameter check_base_point indicates, whether to call check_manifold_point for p.

manifold_dimension(M::MultinomialDoubleStochastic{n}) where {n}

returns the dimension of the MultinomialDoubleStochastic manifold namely

project(
    M::AbstractMultinomialDoublyStochastic,
    p;
    maxiter = 100,
    tolerance = eps(eltype(p))
)

project a matrix p with positive entries applying Sinkhorn's algorithm. Note that this projct method – different from the usual case, accepts keywords.

project(M::MultinomialDoubleStochastic{n}, p, Y) where {n}

Project Y onto the tangent space at p on the MultinomialDoubleStochastic M, return the result in X. The formula reads

where $⊙$ denotes the Hadamard or elementwise product and $\mathbb{1}_n$ is the vector of length $n$ containing ones. The two vectors $α,β ∈ ℝ^{n×n}$ are computed as a solution (typically using the left pseudo inverse) of

where $I_n$ is the $n×n$ unit matrix and $\mathbf{1}_n$ is the vector of length $n$ containing ones.

retract(M::MultinomialDoubleStochastic, p, X, ::ProjectionRetraction)

compute a projection based retraction by projecting $p\odot\exp(X⨸p)$ back onto the manifold, where $⊙,⨸$ are elementwise multiplication and division, respectively. Similarly, $\exp$ refers to the elementwise exponentiation.

vector_transport_to(M::MultinomialDoubleStochastic, p, X, q)

transport the tangent vector X at p to q by projecting it onto the tangent space at q.