mixle.stats.rankings.low_rank_permutation module

Low-rank assignment (first-order Fourier) model over permutations.

A permutation Gibbs model that scores an ordering by a low-rank item-by-rank score matrix:

p(sigma) = exp( sum_r S[sigma[r], r] ) / Z, S = U V^T (rank r << n), Z = permanent(exp(S)).

This is the maximum-entropy distribution matching first-order (item-at-rank) marginals – the first-order term of the Fourier / coset expansion on the symmetric group – and the low-rank factorization S = U V^T is the structured, O(n r)-parameter version of the full MatchingDistribution. The normalizer is a permanent (#P-hard), so probability-distribution construction is limited by an explicit exact-computation cap. Sinkhorn is exposed separately as a transport relaxation; it is never substituted for the model normalizer or marginals. Fitting uses exact model marginals and records optimization diagnostics.

Data type: List[int] – a full ordering, a permutation of 0..n-1 with x[r] the item at rank r (best first).

class LowRankPermutationDistribution(u, v, name=None, keys=None, max_exact=12, sinkhorn_iter=200, fit_diagnostics=None)

Bases: SequenceEncodableProbabilityDistribution

Permutation Gibbs model with a low-rank item-by-rank score matrix S = U V^T.

Parameters:

• u (np.ndarray)

• v (np.ndarray)

• name (str | None)

• keys (str | None)

• max_exact (int)

• sinkhorn_iter (int)

• fit_diagnostics (LowRankPermutationFitDiagnostics | None)

classmethod compute_capabilities()

Declare the NumPy and numba execution path used by low-rank permutation kernels.

density(x)

Return the probability of one ordering.

Parameters:

x (Sequence[int])

Return type:

float

log_density(x)

Return the log-probability of one ordering.

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)

Return vectorized log-probabilities for encoded orderings.

Parameters:

x (ndarray)

Return type:

ndarray

marginals()

Return exact model marginals P[item, rank].

Return type:

ndarray

sinkhorn_relaxation()

Return an explicitly approximate doubly-stochastic transport relaxation.

Return type:

ndarray

sampler(seed=None)

Return an exact conditional-permanent sampler.

Parameters:

seed (int | None)

Return type:

LowRankPermutationSampler

estimator(pseudo_count=None)

Return an exact-marginal estimator with this dimension and rank.

Parameters:

pseudo_count (float | None)

Return type:

LowRankPermutationEstimator

dist_to_encoder()

Return the full-ranking encoder used by vectorized methods.

Return type:

LowRankPermutationDataEncoder

class LowRankPermutationSampler(dist, seed=None)

Bases: DistributionSampler

Draw iid orderings from exact conditional permanent ratios.

Parameters:

• dist (LowRankPermutationDistribution)

• seed (int | None)

sample(size=None, *, batched=True)

Draw one ordering or size exact iid orderings.

Parameters:

• size (int | None)

• batched (bool)

Return type:

list[int] | list[list[int]]

class LowRankPermutationAccumulator(dim, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate the item-by-rank count matrix C[item, rank] – the first-order sufficient statistic.

Parameters:

• dim (int)

• keys (str | None)

update(x, weight, estimate)

Update item-by-rank counts from one weighted ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Initialize item-by-rank counts from one weighted ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Update item-by-rank counts from encoded orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Initialize item-by-rank counts from encoded orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge observation weight and item-by-rank count statistics.

Return type:

LowRankPermutationAccumulator

value()

Return accumulated observation weight and item-by-rank counts.

from_value(x)

Restore accumulator state from value output.

Return type:

LowRankPermutationAccumulator

acc_to_encoder()

Return the encoder compatible with item-by-rank sufficient statistics.

Return type:

LowRankPermutationDataEncoder

class LowRankPermutationAccumulatorFactory(dim, keys=None)

Bases: StatisticAccumulatorFactory

Create accumulators for low-rank permutation sufficient statistics.

Parameters:

• dim (int)

• keys (str | None)

make()

Create an empty low-rank permutation accumulator.

Return type:

LowRankPermutationAccumulator

class LowRankPermutationEstimator(dim, rank=2, max_exact=12, sinkhorn_iter=200, max_iter=300, lr=0.5, tol=1.0e-6, pseudo_count=None, prior_marginals=None, require_convergence=True, name=None, keys=None)

Bases: ParameterEstimator

Fit U, V by Sinkhorn-marginal gradient ascent toward the empirical item-by-rank marginals.

Parameters:

• dim (int)

• rank (int)

• max_exact (int)

• sinkhorn_iter (int)

• max_iter (int)

• lr (float)

• tol (float)

• pseudo_count (float | None)

• prior_marginals (np.ndarray | None)

• require_convergence (bool)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return a factory for low-rank permutation sufficient-statistic accumulators.

Return type:

LowRankPermutationAccumulatorFactory

estimate(nobs, suff_stat)

Estimate low-rank score factors from item-by-rank marginal counts.

Parameters:

nobs (float | None)

Return type:

LowRankPermutationDistribution

class LowRankPermutationDataEncoder(dim=None)

Bases: DataSequenceEncoder

Encode a sequence of orderings (permutations of 0,…,n-1) into an (N, n) integer array.

Parameters:

dim (int | None)

seq_encode(x)

Validate and encode full orderings as a dense integer matrix.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray

class LowRankPermutationFitDiagnostics(converged, iterations, gradient_norm, regularized, pseudo_count, marginal_algorithm='exact_log_permanent')

Bases: object

Optimization evidence attached to an estimated low-rank permutation law.

Parameters:

• converged (bool)

• iterations (int)

• gradient_norm (float)

• regularized (bool)

• pseudo_count (float)

• marginal_algorithm (str)

class LowRankPermutationComputationDiagnostics(normalizer_algorithm='exact_log_permanent', normalizer_exact=True, marginal_algorithm='exact_log_permanent_ratios', marginals_exact=True, sampler_algorithm='exact_conditional_permanent', sampler_exact=True, optional_relaxation='sinkhorn_bethe_transport')

Bases: object

Exactness and algorithm provenance for the represented probability law.

Parameters:

• normalizer_algorithm (str)

• normalizer_exact (bool)

• marginal_algorithm (str)

• marginals_exact (bool)

• sampler_algorithm (str)

• sampler_exact (bool)

• optional_relaxation (str)