class_docstr: Plackett-Luce distribution over permutations.
  
  The Plackett-Luce distribution is defined over permutations of
  fixed length. It is parameterized by a positive score vector of same length.
  
  This class provides methods to create indexed batches of PlackettLuce
  distributions. If the provided `scores` is rank 2 or higher, for
  every fixed set of leading dimensions, the last dimension represents one
  single PlackettLuce distribution. When calling distribution
  functions (e.g. `dist.log_prob(x)`), `scores` and `x` are broadcast to the
  same shape (if possible). In all cases, the last dimension of `scores, x`
  represents single PlackettLuce distributions.
  
  #### Mathematical Details
  
  The Plackett-Luce is a distribution over permutation vectors `p` of length `k`
  where the permutation `p` is an arbitrary ordering of `k` indices
  `{0, 1, ..., k-1}`.
  
  The probability mass function (pmf) is,
  
  ```none
  pmf(p; s) = prod_i s_{p_i} / (Z - Z_i)
  Z = sum_{j=0}^{k-1} s_j
  Z_i = sum_{j=0}^{i-1} s_{p_j} for i>0 and 0 for i=0
  ```
  
  where:
  
  * `scores = s = [s_0, ..., s_{k-1}]`, `s_i >= 0`.
  
  Samples from Plackett-Luce distribution are generated sequentially as follows.
  
  Initialize normalization `N_0 = Z`
  For `i` in `{0, 1, ..., k-1}`
  
    1. Sample i-th element of permutation
       `p_i ~ Categorical(probs=[s_0/N_i, ..., s_{k-1}/N_i])`
    2. Update normalization
      `N_{i+1} = N_i-s_{p_i}`
    3. Mask out sampled index for subsequent rounds
       `s_{p_i} = 0`
  
  Return p
  
  Alternately, an equivalent way to sample from this distribution is to sort
  Gumbel perturbed log-scores [1].
  
  ```none
  p = argsort(log s + g) ~ PlackettLuce(s)
  g = [g_0, ..., g_{k-1}], g_i~ Gumbel(0, 1)
  ```
  
  #### Examples
  
  ```python
  scores = [0.1, 2., 5.]
  dist = PlackettLuce(scores)
  ```
  
  Creates a distribution over permutations of length 3, with the 3rd index
  likely to appear first in the permutation.
  The distribution function can be evaluated on permutations as follows.
  
  ```python
  # permutations same shape as scores.
  permutations = [2, 1, 0]
  dist.prob(permutations) # Shape []
  
  # scores broadcast to [[0.1, 2.3, 5.], [0.1, 2.3, 5.]] to match permutations.
  permutations = [[2, 1, 0], [1, 0, 2]]
  dist.prob(permutations) # Shape [2]
  
  # scores broadcast to shape [5, 7, 3] to match permutations.
  permutations = [[...]]  # Shape [5, 7, 3]
  dist.prob(permutaions)  # Shape [5, 7]
  ```
  
  Creates a 2-batch of 3-class distributions.
  
  ```python
  scores = [[0.1, 2.3, 5.], [4.2, 0.5, 3.1]]  # Shape [2, 3]
  dist = PlackettLuce(scores)
  
  # permutations broadcast to [[2, 1, 0], [2, 1, 0]] to match shape of scores.
  permutations = [2, 1, 0]
  dist.prob(permutations) # Shape [2]
  ```
  
  #### References
  
  [1]: Aditya Grover, Eric Wang, Aaron Zweig, Stefano Ermon. Stochastic
  Optimization of Sorting Networks via Continuous Relaxations. ICLR 2019.
class_docstr_tok: ["Plackett-Luce","distribution","over","permutations",".","The","Plackett-Luce","distribution","is","defined","over","permutations","of","fixed","length",".","It","is","parameterized","by","a","positive","score","vector","of","same","length",".","This","class","provides","methods","to","create","indexed","batches","of","PlackettLuce","distributions",".","If","the","provided","`","scores","`","is","rank","2","or","higher",",","for","every","fixed","set","of","leading","dimensions",",","the","last","dimension","represents","one","single","PlackettLuce","distribution",".","When","calling","distribution","functions","(","e.g",".","`","dist.log_prob","(","x",")","`",")",",","`","scores","`","and","`","x","`","are","broadcast","to","the","same","shape","(","if","possible",")",".","In","all","cases",",","the","last","dimension","of","`","scores",",","x","`","represents","single","PlackettLuce","distributions",".","#","#","#","#","Mathematical","Details","The","Plackett-Luce","is","a","distribution","over","permutation","vectors","`","p","`","of","length","`","k","`","where","the","permutation","`","p","`","is","an","arbitrary","ordering","of","`","k","`","indices","`","{","0",",","1",",","...",",","k-1","}","`",".","The","probability","mass","function","(","pmf",")","is",",","``","`","none","pmf","(","p",";","s",")","=","prod_i","s_","{","p_i","}","\/","(","Z","-","Z_i",")","Z","=","sum_","{","j=0","}","^","{","k-1","}","s_j","Z_i","=","sum_","{","j=0","}","^","{","i-1","}","s_","{","p_j","}","for","i",">","0","and","0","for","i=0","``","`","where",":","*","`","scores","=","s","=","[","s_0",",","...",",","s_","{","k-1","}","]","`",",","`","s_i",">","=","0","`",".","Samples","from","Plackett-Luce","distribution","are","generated","sequentially","as","follows",".","Initialize","normalization","`","N_0","=","Z","`","For","`","i","`","in","`","{","0",",","1",",","...",",","k-1","}","`","1",".","Sample","i-th","element","of","permutation","`","p_i","~","Categorical","(","probs=","[","s_0\/N_i",",","...",",","s_","{","k-1","}","\/N_i","]",")","`","2",".","Update","normalization","`","N_","{","i+1","}","=","N_i-s_","{","p_i","}","`","3",".","Mask","out","sampled","index","for","subsequent","rounds","`","s_","{","p_i","}","=","0","`","Return","p","Alternately",",","an","equivalent","way","to","sample","from","this","distribution","is","to","sort","Gumbel","perturbed","log-scores","[","1","]",".","``","`","none","p","=","argsort","(","log","s","+","g",")","~","PlackettLuce","(","s",")","g","=","[","g_0",",","...",",","g_","{","k-1","}","]",",","g_i~","Gumbel","(","0",",","1",")","``","`","#","#","#","#","Examples","``","`","python","scores","=","[","0.1",",","2.",",","5",".","]","dist","=","PlackettLuce","(","scores",")","``","`","Creates","a","distribution","over","permutations","of","length","3",",","with","the","3rd","index","likely","to","appear","first","in","the","permutation",".","The","distribution","function","can","be","evaluated","on","permutations","as","follows",".","``","`","python","#","permutations","same","shape","as","scores",".","permutations","=","[","2",",","1",",","0","]","dist.prob","(","permutations",")","#","Shape","[","]","#","scores","broadcast","to","[","[","0.1",",","2.3",",","5",".","]",",","[","0.1",",","2.3",",","5",".","]","]","to","match","permutations",".","permutations","=","[","[","2",",","1",",","0","]",",","[","1",",","0",",","2","]","]","dist.prob","(","permutations",")","#","Shape","[","2","]","#","scores","broadcast","to","shape","[","5",",","7",",","3","]","to","match","permutations",".","permutations","=","[","[","...","]","]","#","Shape","[","5",",","7",",","3","]","dist.prob","(","permutaions",")","#","Shape","[","5",",","7","]","``","`","Creates","a","2-batch","of","3-class","distributions",".","``","`","python","scores","=","[","[","0.1",",","2.3",",","5",".","]",",","[","4.2",",","0.5",",","3.1","]","]","#","Shape","[","2",",","3","]","dist","=","PlackettLuce","(","scores",")","#","permutations","broadcast","to","[","[","2",",","1",",","0","]",",","[","2",",","1",",","0","]","]","to","match","shape","of","scores",".","permutations","=","[","2",",","1",",","0","]","dist.prob","(","permutations",")","#","Shape","[","2","]","``","`","#","#","#","#","References","[","1","]",":","Aditya","Grover",",","Eric","Wang",",","Aaron","Zweig",",","Stefano","Ermon",".","Stochastic","Optimization","of","Sorting","Networks","via","Continuous","Relaxations",".","ICLR","2019","."]
code: def _parameter_control_dependencies(self, is_init):
      assertions = []
  
      scores = self._scores
      param, name = (scores, "scores")
  
      # In init, we can always build shape and dtype checks because
      # we assume shape doesn't change for Variable backed args.
      if is_init:
          if not dtype_util.is_floating(param.dtype):
              raise TypeError(
                  "Argument `{}` must having floating type.".format(
                      name
                  )
              )
  
          msg = "Argument `{}` must have rank at least 1.".format(name)
          shape_static = tensorshape_util.dims(param.shape)
          if shape_static is not None:
              if len(shape_static) < 1:
                  raise ValueError(msg)
          elif self.validate_args:
              param = tf.convert_to_tensor(param)
              assertions.append(
                  assert_util.assert_rank_at_least(
                      param, 1, message=msg
                  )
              )
              with tf.control_dependencies(assertions):
                  param = tf.identity(param)
  
          msg1 = "Argument `{}` must have final dimension >= 1.".format(
              name
          )
          msg2 = (
              "Argument `{}` must have final dimension <= {}.".format(
                  name, dtype_util.max(tf.int32)
              )
          )
          event_size = (
              shape_static[-1] if shape_static is not None else None
          )
          if event_size is not None:
              if event_size < 1:
                  raise ValueError(msg1)
              if event_size > dtype_util.max(tf.int32):
                  raise ValueError(msg2)
          elif self.validate_args:
              param = tf.convert_to_tensor(param)
              assertions.append(
                  assert_util.assert_greater_equal(
                      tf.shape(param)[-1], 1, message=msg1
                  )
              )
              # NOTE: For now, we leave out a runtime assertion that
              # `tf.shape(param)[-1] <= tf.int32.max`.  An earlier `tf.shape` call
              # will fail before we get to this point.
  
      if not self.validate_args:
          assert not assertions  # Should never happen.
          return []
  
      if is_init != tensor_util.is_ref(scores):
          scores = tf.convert_to_tensor(scores)
          assertions.extend(
              [
                  assert_util.assert_positive(scores),
              ]
          )
  
      return assertions
  
imports: import tensorflow.compat.v2
  from tensorflow_probability.python.bijectors import softplus
  from tensorflow_probability.python.distributions import distribution
  from tensorflow_probability.python.distributions import gumbel
  from tensorflow_probability.python.internal import assert_util
  from tensorflow_probability.python.internal import dtype_util
  from tensorflow_probability.python.internal import parameter_properties
  from tensorflow_probability.python.internal import prefer_static
  from tensorflow_probability.python.internal import reparameterization
  from tensorflow_probability.python.internal import tensor_util
  from tensorflow_probability.python.internal import tensorshape_util
label_desc: Use image node_id 13 for calling the PlackettLuce obj's underlying member method code with example usage: obj._parameter_control_dependencies(is_init) and returns: assertions, list