.. _op_ai_onnx_Multinomial:

Multinomial
===========

- **Domain**: ``ai.onnx``
- **Since version**: 22

Generate a tensor of samples from a multinomial distribution according to the probabilities
of each of the possible outcomes.

**Inputs**

- **input** (*T1*): Input tensor with shape [batch_size, class_size], where class_size is the number of all possible outcomes. Each value along the axis zero represents the unnormalized log-probability of each corresponding outcome in a batch.

**Outputs**

- **output** (*T2*): Output tensor with shape [batch_size, sample_size], where sample_size is the number of times to sample. Each value along the axis zero represents the outcome of the corresponding sample in a batch.

**Attributes**

- **dtype** (*int*): (Optional) The data type for the elements of the output tensor, if not specified, we will use int32.
- **sample_size** (*int*): Number of times to sample.
- **seed** (*float*): (Optional) Seed to the random generator, if not specified we will auto generate one.

**Type Constraints**

- **T1**: Constrain input types to float tensors.
  Allowed types: tensor(bfloat16), tensor(double), tensor(float), tensor(float16).
- **T2**: Constrain output types to integral tensors.
  Allowed types: tensor(int32), tensor(int64).

Examples
--------

**test_cc_multinomial**

.. code-block:: text

    Node:
      Multinomial(x) -> (y)

.. code-block:: text

    Inputs:
      x: shape=(2, 3), dtype=float32
        [[ 0.,  0.,  0.],
         [-5., -5.,  5.]]

    Outputs:
      y: shape=(2, 1), dtype=int32
        [[1],
         [2]]

**test_cc_multinomial_int64**

.. code-block:: text

    Node:
      Multinomial(x) -> (y)
      Attributes:
        sample_size = 4
        dtype = 7

.. code-block:: text

    Inputs:
      x: shape=(1, 3), dtype=float32
        [[1., 1., 1.]]

    Outputs:
      y: shape=(1, 4), dtype=int64
        [[1, 2, 2, 2]]

**test_cc_multinomial_seeded**

.. code-block:: text

    Node:
      Multinomial(x) -> (y)
      Attributes:
        sample_size = 5
        seed = 42.0

.. code-block:: text

    Inputs:
      x: shape=(2, 4), dtype=float32
        [[1.    , 2.    , 3.    , 4.    ],
         [0.5   , 0.25  , 0.125 , 0.0625]]

    Outputs:
      y: shape=(2, 5), dtype=int32
        [[3, 2, 3, 3, 3],
         [0, 1, 1, 0, 2]]

Differences with previous version (7)
-------------------------------------

**SchemaDiff**: ``Multinomial`` (domain ``'ai.onnx'``)

* old version: 7
* new version: 22
* breaking: no

**Type constraints:**

* changed 'T1': added types: ['tensor(bfloat16)']

Version History
---------------

- :doc:`Version 7 <Multinomial-7>`