# tensorplay.functional.multinomial

Source: https://www.tensorplay.cn/docs/generated/tensorplay.functional.multinomial.html

```python
tensorplay.functional.multinomial(input, num_samples, replacement=False, *, generator=None, out=None) → LongTensor
```

Returns a tensor where each row contains num_samples indices sampled
from the multinomial (a stricter definition would be multivariate,
refer to [tensorplay.distributions.multinomial.Multinomial](/docs/generated/tensorplay.distributions.Multinomial.html#tensorplay.distributions.Multinomial) for more details)
probability distribution located in the corresponding row
of tensor input.

> **Note**
>
> The rows of input do not need to sum to one (in which case we use the values as weights), but must be non-negative, finite and have a non-zero sum.

Indices are ordered from left to right according to when each was sampled
(first samples are placed in first column).

If input is a vector, out is a vector of size num_samples.

If input is a matrix with m rows, out is an matrix of shape
$(m \times \text{num\_samples})$.

If replacement is True, samples are drawn with replacement.

If not, they are drawn without replacement, which means that when a
sample index is drawn for a row, it cannot be drawn again for that row.

> **Note**
>
> When drawn without replacement, num_samples must be lower than number of non-zero elements in input (or the min number of non-zero elements in each row of input if it is a matrix).

Parameters:

- input ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the input tensor containing probabilities

- num_samples ([int](https://docs.python.org/3/builtins/functions.html#int)) – number of samples to draw

- replacement ([bool](https://docs.python.org/3/builtins/functions.html#bool), optional) – whether to draw with replacement or not

Keyword Arguments:

- generator ([tensorplay.Generator](/docs/generated/tensorplay.Generator.html#tensorplay.Generator), optional) – a pseudorandom number generator for sampling

- out ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor), optional) – the output tensor.

Example:

```
>>> weights = tensorplay.tensor([0, 10, 3, 0], dtype=tensorplay.float) # create a tensor of weights
>>> tensorplay.multinomial(weights, 2)
tensor([1, 2])
>>> tensorplay.multinomial(weights, 5) # ERROR!
RuntimeError: cannot sample n_sample > prob_dist.size(-1) samples without replacement
>>> tensorplay.multinomial(weights, 4, replacement=True)
tensor([ 2,  1,  1,  1])
```