# Multinomial

Source: https://www.tensorplay.cn/docs/generated/tensorplay.distributions.Multinomial.html

```python
class tensorplay.distributions.Multinomial(total_count: int = 1, probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)
```

Creates a Multinomial distribution parameterized by total_count and
either probs or logits (but not both). The innermost dimension of
probs indexes over categories. All other dimensions index over batches.

Note that total_count need not be specified if only log_prob() is
called (see example below)

> **Note**
>
> The probs argument must be non-negative, finite and have a non-zero sum, and it will be normalized to sum to 1 along the last dimension. probs will return this normalized value. The logits argument will be interpreted as unnormalized log probabilities and can therefore be any real number. It will likewise be normalized so that the resulting probabilities sum to 1 along the last dimension. logits will return this normalized value.

- sample() requires a single shared total_count for all parameters and samples.

- log_prob() allows different total_count for each parameter and sample.

Example:

```
>>> # xdoctest: +SKIP("FIXME: found invalid values")
>>> m = Multinomial(100, tensorplay.tensor([ 1., 1., 1., 1.]))
>>> x = m.sample()  # equal probability of 0, 1, 2, 3
tensor([ 21.,  24.,  30.,  25.])

>>> Multinomial(probs=tensorplay.tensor([1., 1., 1., 1.])).log_prob(x)
tensor([-4.1338])
```

Parameters:

- total_count ([int](https://docs.python.org/3/builtins/functions.html#int)) – number of trials

- probs ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event probabilities

- logits ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event log probabilities (unnormalized)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

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

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.