# DML_RANDOM_GENERATOR_OPERATOR_DESC structure (directml.h)

Fills an output tensor with deterministically-generated, pseudo-random, uniformly-distributed bits. This operator optionally may also output an updated internal generator state, which can be used during subsequent executions of the operator.

This operator is deterministic, and behaves as if it were a pure function—that is, its execution produces no side-effects, and uses no global state. The pseudo-random output produced by this operator is solely dependent on the values supplied in the *InputStateTensor*.

The generators implemented by this operator are not cryptographically secure; therefore, this operator should not be used for encryption, key generation, or other applications which require cryptographically secure random number generation.

Important

This API is available as part of the DirectML standalone redistributable package (see Microsoft.AI.DirectML. Also see DirectML version history.

## Syntax

```
struct DML_RANDOM_GENERATOR_OPERATOR_DESC
{
const DML_TENSOR_DESC* InputStateTensor;
const DML_TENSOR_DESC* OutputTensor;
_Maybenull_ const DML_TENSOR_DESC* OutputStateTensor;
DML_RANDOM_GENERATOR_TYPE Type;
};
```

## Members

`InputStateTensor`

Type: **const DML_TENSOR_DESC***

An input tensor containing the internal generator state. The size and format of this input tensor depends on the DML_RANDOM_GENERATOR_TYPE.

For **DML_RANDOM_GENERATOR_TYPE_PHILOX_4X32_10**, this tensor must be of type **UINT32**, and have sizes `{1,1,1,6}`

. The first four 32-bit values contain a monotonically increasing 128-bit counter. The last two 32-bit values contain the 64-bit key value for the generator.

```
Element 0 1 2 3 4 5
(32-bits each) |-------|-------|-------|-------|-------|-------|
<--------128-bit counter------> <-64-bit key-->
```

When initializing the generator's input state for the first time, typically the 128-bit counter (the first four 32-bit UINT32 values) should be initialized to 0. The key can be arbitrarily chosen; different key values will produce different sequences of numbers. The value for the key is usually generated using a user-provided *seed*.

`OutputTensor`

Type: **const DML_TENSOR_DESC***

An output tensor which holds the resulting pseudo-random values. This tensor can be of any size.

`OutputStateTensor`

Type: _Maybenull_ **const DML_TENSOR_DESC***

An optional output tensor THAT holds the updated internal generator state. If supplied, this operator uses the *InputStateTensor* to compute an appropriate updated generator state, and writes the result into the *OutputStateTensor*. Typically, callers would save this result and supply it as the input state on a subsequent execution of this operator.

`Type`

Type: **DML_RANDOM_GENERATOR_TYPE**

One of the values from the DML_RANDOM_GENERATOR_TYPE enum, indicating the type of generator to use. Currently the only valid value is **DML_RANDOM_GENERATOR_TYPE_PHILOX_4X32_10**, which generates pseudo-random numbers according to the Philox 4x32-10 algorithm.

## Remarks

On each execution of this operator, the 128-bit counter should be incremented. If the *OutputStateTensor* is supplied, THEN this operator increments the counter with the correct value on your behalf, and writes the result into the *OutputStateTensor*. The amount it should be incremented by depends on the number of 32-bit output elements generated, and the type of the generator.

For **DML_RANDOM_GENERATOR_TYPE_PHILOX_4X32_10**, the 128-bit counter should be incremented by `ceil(outputSize / 4)`

on each execution, where `outputSize`

is the number of elements in the *OutputTensor*.

Consider an example where the value of the 128-bit counter is currently `0x48656c6c'6f46726f'6d536561'74746c65`

, and the OutputTensor's size is `{3,3,20,7219}`

. After executing this operator once, the counter should be incremented by 324,855 (the number of output elements generated divided by 4, rounded up) resulting in a counter value of `0x48656c6c'6f46726f'6d536561'746f776e`

. This updated value should then be supplied as an input for the next execution of this operator.

## Availability

This operator was introduced in `DML_FEATURE_LEVEL_3_0`

.

## Tensor constraints

`InputStateTensor`

and `OutputStateTensor`

must have the same *Sizes*.

## Tensor support

Tensor | Kind | Dimensions | Supported dimension counts | Supported data types |
---|---|---|---|---|

InputStateTensor | Input | { 1, 1, 1, 6 } | 4 | UINT32 |

OutputTensor | Output | { D0, D1, D2, D3 } | 4 | UINT32 |

OutputStateTensor | Optional output | { 1, 1, 1, 6 } | 4 | UINT32 |

## Requirements

Header |
directml.h |