Edit

DML_RANDOM_GENERATOR_OPERATOR_DESC structure (directml.h)

  • Article

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.

Syntax

struct DML_RANDOM_GENERATOR_OPERATOR_DESC {
  const DML_TENSOR_DESC     *InputStateTensor;
  const DML_TENSOR_DESC     *OutputTensor;
  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 DimensionCount and Sizes.

Tensor support

DML_FEATURE_LEVEL_4_0 and above

Tensor Kind Dimensions Supported dimension counts Supported data types
InputStateTensor Input { [1], [1], [1], [1], [1], [1], [1], 6 } 1 to 8 UINT32
OutputTensor Output { [D0], [D1], [D2], [D3], [D4], [D5], [D6], D7 } 1 to 8 UINT32
OutputStateTensor Optional output { [1], [1], [1], [1], [1], [1], [1], 6 } 1 to 8 UINT32

DML_FEATURE_LEVEL_3_0 and above

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

Requirement Value
Minimum supported client Windows 10 Build 20348
Minimum supported server Windows 10 Build 20348
Header directml.h