mindspore.mint.multinomial

mindspore.mint.multinomial(input, num_samples, replacement=False, *, generator=None)

根据输入生成一个多项式分布的Tensor。

多项式分布是一种概率分布，把二项分布公式推广至多种状态，就得到了多项式分布。在多项式分布中，每个事件都有一个固定的概率，这些概率的和为1。

mindspore.mint.multinomial 接口的作用是对输入 input 进行 num_samples 次抽样，输出的Tensor则为每一次抽样时输入Tensor的索引，其中 input 中的值为每次抽样取到对应索引的概率。

这里我们给一个相对极端的用例方便理解，我们给定一个输入概率值Tensor，值为 Tensor([90 / 100, 10 / 100, 0], mindspore.float32) ，代表我们一共可以对三个索引进行抽样，分别为索引0，索引1，索引2，它们被抽中的概率分别为90%，10%，0%，我们对其进行n次抽样，抽样的结果序列则为多项式分布的计算结果，计算结果长度与抽样次数一致。

在样例代码case 1中，我们对其进行两次不放回抽样（replacement 为 False），那我们的计算结果则大概率为 [0, 1] ，小概率为 [1, 0]， 由于每次抽样抽到索引0的概率为90%，因此抽到的结果序列中，第一次大概率是抽到索引0，由于抽到索引2的概率为0，因此抽样两次结果不可能出现索引2，那第二次结果一定是索引1，因此结果序列为 [0, 1]。

在样例代码case 2中，我们对其进行10次放回抽样（replacement 为 True），可以看到计算结果中大概有90%的抽样结果为抽到索引0，符合预期。

在样例代码case 3中，我们将输入扩展为2维，可以看到抽样结果在每一个维度中结果也符合我们抽样预期。

说明

输入的行不需要求和为1（当使用值作为权重的情况下），但必须是非负的、有限的，并且和不能为0。在使用值作为权重的情况下，可以理解为对输入沿最后一维进行了归一化操作，以此保证概率和为1。

警告

这是一个实验性API，后续可能修改或删除。

参数：

• input (Tensor) - 输入的概率值Tensor，必须是一维或二维，数据类型为float32。

• num_samples (int) - 采样的次数。

• replacement (bool, 可选) - 是否是可放回的采样，默认值： False 。

关键字参数：

• generator (generator，可选) - MindSpore随机种子。默认值： None。

返回：

Tensor，数据类型为int64。 如果 input 是向量， 输出数据shape是 num_samples 的向量。 如果 input 是 m 行矩阵，输出数据shape是 m * num_samples 大小的矩阵。

异常：

• TypeError - 如果 input 不是数据类型不是float16、float32、float64或bfloat16的Tensor。

• TypeError - 如果 num_samples 不是一个int，或元素为int的是Scalar, 或shape为(1, ) 仅有一个int元素的Tensor。

• RuntimeError - \(\text{num_samples} <= 0\)。

• RuntimeError - replacement 为 False 时， \(\text{num_samples} > input\) 最后一维的shape。

• RuntimeError - input 最后一维的shape超过 2^24。

支持平台：

Ascend

样例：

>>> import mindspore
>>> from mindspore import Tensor, mint
>>> from mindspore import dtype as mstype
>>> # case 1: The output is random, and the length of the output is the same as num_sample.
>>> # replacement is False.
>>> input1 = Tensor([90 / 100, 10 / 100, 0], mindspore.float32)
>>> input2 = Tensor([90, 10, 0], mindspore.float32)
>>> # input1 and input2 have the same meaning.
>>> output1 = mint.multinomial(input1, 2)
>>> output2 = mint.multinomial(input2, 2)
>>> # print(output1)
>>> # [0 1]
>>> # print(output2)
>>> # [0 1]
>>> print(len(output1))
2
>>> print(len(output2))
2
>>> # case 2: The output is random, and the length of the output is the same as num_sample.
>>> # replacement is True.
>>> output3 = mint.multinomial(input1, 10, replacement=True)
>>> # print(output3)
>>> # [0 0 1 0 0 0 0 0 0 0]
>>> print(len(output3))
10
>>> # case 3: The output is random, and the length of the output is the same as num_sample.
>>> # replacement is True.
>>> # rank is 2
>>> input4 = Tensor([[90, 10, 0], [10, 90, 0]], mstype.float32)
>>> output4 = mint.multinomial(input4, 10, replacement=True)
>>> # print(output4)
>>> # [[0 0 0 0 0 0 0 0 1 0]
>>> #  [1 1 1 1 1 0 1 1 1 1]]