inFairness.utils.plackett_luce module

This file implements Plackett-Luce distribution and is taken from the following source:

Source: Github PyTorch PR#50362 - Add Plackett-Luce Distribution URL: https://github.com/pytorch/pytorch/pull/50362/ Author: Jeremy Salwen (https://github.com/jeremysalwen)

class inFairness.utils.plackett_luce.PlackettLuce(logits: Tensor, permutation_sizes: Tensor | None = None, validate_args=None)

Bases: Distribution

Creates a Plackett-Luce distribution over permutations, parameterized by :attr: logits.

The Plackett-Luce distribution defines a probability distribution over permutations by assigning a score a_i to each element, and repeatedly choosing the next element by sampling from the remaining elements with a probability proportional to their score.

If logits is 1-dimensional with length-K, each element is the log-score of the object at that index.

If logits is N-dimensional, the first N-1 dimensions are treated as a batch of log-score vectors.

This distribution supports batched operations with permutations of different sizes, by using the :attr: permutation_sizes attribute to specify the permutation size of each score vector in the batch. If the permutation_size is N for a given index of the batch, the first N entries of the resulting sample will be a permutation of the number 1 through N, while the remainder have unspecified values.

Example:

>>> m = PlackettLuce(torch.tensor([[0, 1, -1], [0, 1, 2]]), torch.tensor([3, 2], dtype=torch.int64))
>>> m.sample()
tensor([[ 1,  0,  2],
        [ 0,  1,  2]])

Parameters:

• logits (Tensor) – The log of the Plackett-Luce distribution scores a_i.

• permutation_sizes (Tensor) – Optional sizes of the permutations sampled by the distribution. Should match the shape of the logits, with the last dimension stripped.

arg_constraints = {'logits': Real()}

expand(batch_shape, _instance=None)

Returns a new distribution instance (or populates an existing instance provided by a derived class) with batch dimensions expanded to batch_shape. This method calls expand on the distribution’s parameters. As such, this does not allocate new memory for the expanded distribution instance. Additionally, this does not repeat any args checking or parameter broadcasting in __init__.py, when an instance is first created.

Parameters:

• batch_shape (torch.Size) – the desired expanded size.

• _instance – new instance provided by subclasses that need to override .expand.

Returns:

New distribution instance with batch dimensions expanded to batch_size.

log_prob(value: Tensor)

Returns the log of the probability density/mass function evaluated at value.

Parameters:

value (Tensor) –

sample(sample_shape=())

Generates a sample_shape shaped sample or sample_shape shaped batch of samples if the distribution parameters are batched.

support = IntegerInterval(lower_bound=-1, upper_bound=9223372036854775807)