---
title: "ClikaRT::ops::multinomial"
sidebar_label: "multinomial"
description: "Categorical sampling: draws num_samples category indices per row of a weight tensor."
---

<!-- Generated by tools/doxygen2mdx from Doxygen XML. Do not edit. -->

<span class="api-kind api-kind--function">function</span>

## multinomial() {#multinomial}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`multinomial`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`Tensor`](../Tensor.md) `probabilities`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int64_t` `num_samples`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`bool` `replacement` `=` `false`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `device` `=` `{}`<br />
)

</div>

Categorical sampling: draws `num_samples` category indices per row of a weight tensor.

`probabilities` holds non-negative weights (they need not sum to 1), typically `[batch, num_categories]`; the output replaces the category axis with `num_samples` and is `Int64`. Without `replacement` each row samples distinct categories.

**Parameters**

- `probabilities`: non-negative category weights `[.., C]`.
- `num_samples`: draws per row; without replacement must be \<= `C`.
- `replacement`: sample with replacement; default false.
- `device`: stream or device; default = the input's.

**Returns:** `Int64` category indices, `[.., num_samples]`.

**Throws**

- `ClikaRT::Error`: (`INVALID_ARGUMENT`) when a weight is negative or `num_samples` exceeds `C` without replacement.

```cpp
auto next = ClikaRT::ops::multinomial(probs, 1);   // one token per row
```

<div class="api-declared">

Declared in `ClikaRT/compute/ops.h`, line 4145

</div>