Random Number Generation

Random Number Generation#

MatX provides the capability to generate random numbers on the host and device using the random() and randomi() operators. Both host and device generation is supported through the cuRAND library.

When random() or randomi() is assigned directly into a CUDA tensor, MatX uses a low-memory direct fill path that avoids allocating per-element RNG state:

(A = random<float>(A.Shape(), NORMAL, 1234)).run(exec);

The direct CUDA fill path is reproducible for the same seed, tensor shape, layout, type, and distribution. Contiguous floating-point tensors use a cuRAND bulk-generation path, while non-contiguous views, rank-0 tensors, integer tensors, and some tail cases use a local Philox fill path, so fixed-seed values are not guaranteed to match across those layouts or paths.

For complex random() output, alpha scales both real and imaginary components, while scalar beta shifts only the real component.

Generic CUDA expressions containing random operators materialize one temporary value buffer per random operator during PreRun instead of allocating per-element RNG state. Repeated accesses to the same random operator inside one expression read the same materialized values; use separate random operators and seeds for independent draws.

When CUDAJITExecutor is used with -DMATX_EN_MATHDX=ON, floating-point and complex random() operators can be fused into the generated kernel with cuRANDDx if the random output has at most 1024 elements. This JIT path avoids the temporary value buffer and generates values from Philox inside the fused kernel. Larger random tensors and randomi() are not JIT-fused; use a normal CUDA executor for those expressions.

  • random() only generates random distribution for float data types

  • randomi() only generates random distributions for integral data types

Please see the documentation for each function for a full list of supported types

Added in version 0.1.0.

template<typename T, typename ShapeType, typename LowerType = typename inner_op_type_t<T>::type>
__MATX_INLINE__ auto matx::random(ShapeType &&s, Distribution_t dist, uint64_t seed = 0, LowerType alpha = 1, LowerType beta = 0)#

Return a random number with a specified shape.

Supported Types: float, double, complex<float>, complex<double>

Template Parameters:

  • ShapeType – Shape type

  • T – Type of output

  • LowerType – Either T or the inner type of T if T is complex*

Parameters:

  • s – Shape of operator

  • dist – Distribution (either NORMAL or UNIFORM)

  • seed – Random number seed

  • alpha – Value to multiply by each number

  • beta – Value to add to each number

Returns:

Random number operator

template<typename T, int RANK, typename LowerType = typename inner_op_type_t<T>::type>
__MATX_INLINE__ auto matx::random(const index_t (&s)[RANK], Distribution_t dist, uint64_t seed = 0, LowerType alpha = 1, LowerType beta = 0)#

Return a random number with a specified shape.

Supported Types: float, double, complex<float>, complex<double>

Template Parameters:

  • RANK – Rank of operator

  • T – Type of output

  • LowerType – Either T or the inner type of T if T is complex

Parameters:

  • s – Array of dimensions

  • dist – Distribution (either NORMAL or UNIFORM)

  • seed – Random number seed

  • alpha – Value to multiply by each number

  • beta – Value to add to each number

Returns:

Random number operator

template<typename T, typename ShapeType, typename LowerType = typename inner_op_type_t<T>::type>
__MATX_INLINE__ auto matx::randomi(ShapeType &&s, uint64_t seed = 0, LowerType min = 0, LowerType max = 100)#

Return a random number with a specified shape.

Supported types: uint32_t, int32_t, uint64_t, int64_t

Template Parameters:

  • ShapeType – Shape type

  • T – Type of output

  • LowerType – Either T or the inner type of T if T is complex*

Parameters:

  • s – Shape of operator

  • seed – Random number seed

  • min – min of generation range

  • max – max of generation range

Returns:

Random number operator

template<typename T, int RANK, typename LowerType = typename inner_op_type_t<T>::type>
__MATX_INLINE__ auto matx::randomi(const index_t (&s)[RANK], uint64_t seed = 0, LowerType min = 0, LowerType max = 100)#

Return a random number with a specified shape.

Supported types: uint32_t, int32_t, uint64_t, int64_t

Template Parameters:

  • RANK – Rank of operator

  • T – Type of output

  • LowerType – Either T or the inner type of T if T is complex

Parameters:

  • s – Array of dimensions

  • seed – Random number seed

  • min – min of generation range

  • max – max of generation range

Returns:

Random number operator

Examples#

index_t count = 50;

tensor_t<TestType, 3> t3f({count, count, count});

(t3f = (TestType)-1000000).run(this->exec);
(t3f = random<TestType>({count, count, count}, UNIFORM)).run(this->exec);

index_t count = 50;

tensor_t<TestType, 3> t3f({count, count, count});
TestType minBound = std::numeric_limits<TestType>::min(); 
TestType maxBound = std::numeric_limits<TestType>::max(); 

(t3f = (TestType)0).run(this->exec);
(t3f = randomi<TestType>({count, count, count}, 0, minBound, maxBound )).run(this->exec);
Contents