mindspore.ops.multinomial

mindspore.ops.multinomial(input, num_samples, replacement=True, seed=None)[source]

Generate a tensor from a multinomial distribution.

The polynomial distribution is a probability distribution that generalizes the binomial distribution formula to multiple states. In the polynomial distribution, each event has a fixed probability, and the sum of these probabilities is 1.

The purpose of this interface is to perform num_samples sampling on the input input, and the output tensor is the index of the input tensor for each sampling. The values in input represent the probability of selecting the corresponding index for each sampling.

Here is an extreme example for better understanding. Suppose we have an input probability tensor with values [90 / 100, 10 / 100, 0], which means we can sample three indices, namely index 0, index 1, and index 2, with probabilities of 90%, 10%, and 0%, respectively. We perform n samplings, and the resulting sequence is the calculation result of the polynomial distribution, with a length equal to the number of samplings.

In case 1 of the sample code, we perform two non-replacement samplings (replacement is False). Since the probability of selecting index 0 is 90% for each sampling, the first result is most likely to be index 0. Since the probability of selecting index 2 is 0, index 2 cannot appear in the sampling result. Therefore, the second result must be index 1, and the resulting sequence is [0, 1].

In case 2 of the sample code, we perform 10 replacement samplings (replacement is True). As expected, about 90% of the sampling results are index 0.

In case 3 of the sample code, we extend the input to 2 dimensions, and the sampling results in each dimension also match our sampling expectations.

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. When using values as weights, it can be understood as normalizing the input along the last dimension.

Warning

The Ascend backend does not support the reproducibility of random numbers, so the seed parameter has no effect.

Parameters

input (Tensor) – The input tensor containing probabilities.
num_samples (int) – Number of samples to draw.
replacement (bool, optional) – Whether to draw with replacement or not. Default True .
seed (int, optional) – Random seed. Default None .

Returns

Tensor

Supported Platforms:: Ascend GPU CPU

Examples

>>> import mindspore
>>> # case 1: The output is random, and the length of the output is the same as num_sample.
>>> # replacement is False.
>>> input1 = mindspore.tensor([90 / 100, 10 / 100, 0])
>>> input2 = mindspore.tensor([90, 10, 0])
>>> # input1 and input2 have the same meaning.
>>> mindspore.ops.multinomial(input1, 2, replacement=False)
Tensor(shape=[2], dtype=Int32, value= [0, 1])
>>> mindspore.ops.multinomial(input2, 2, replacement=False)
Tensor(shape=[2], dtype=Int32, value= [1, 0])
>>>
>>> # case 2: The output is random, and the length of the output is the same as num_sample.
>>> # replacement is True.
>>> mindspore.ops.multinomial(input1, 10)
Tensor(shape=[10], dtype=Int32, value= [0, 0, 1, 0, 0, 0, 0, 0, 0, 0])
>>>
>>> # case 3: The output is random, and the length of the output is the same as num_sample.
>>> # replacement is True.
>>> # rank is 2
>>> input3 = mindspore.tensor([[90, 10, 0], [10, 90, 0]], mindspore.float32)
>>> output = mindspore.ops.multinomial(input3, 10)
>>> print(output)
[[0 0 0 0 0 0 0 0 0 0]
 [1 0 1 1 1 1 1 1 1 1]]