# 4. Python API Reference

This chapter describes the rocRAND Python module API.

## 4.1. class PRNG

class rocrand.PRNG(rngtype=400, seed=None, offset=None, stream=None)

  Creates a new pseudo-random number generator.

  A new pseudo-random number generator of type rngtype is initialized with given seed, offset and stream.

  Values of rngtype:

  - `DEFAULT`

  - `XORWOW`

  - `MRG31K3P`

  - `MRG32K3A`

  - `MTGP32`

  - `MT19937`

  - `PHILOX4_32_10`

  - `LFSR113`

  - `THREEFRY2_32_20`

  - `THREEFRY2_64_20`

  - `THREEFRY4_32_20`

  - `THREEFRY4_64_20`

  Parameters:

    - rngtype – Type of pseudo-random number generator to create

    - seed – Initial seed value

    - offset – Initial offset of random numbers sequence

    - stream – HIP stream for all kernel launches of the generator

  Example:

      import rocrand
      import numpy as np

      gen = rocrand.PRNG(rocrand.PRNG.PHILOX4_32_10, seed=123456)
      a = np.empty(1000, np.int32)
      gen.poisson(a, 10.0)
      print(a)

  DEFAULT = 400

    Default pseudo-random generator type, `XORWOW`

  LFSR113 = 406

    LFSR113 pseudo-random generator type

  MRG31K3P = 405

    MRG31k3p pseudo-random generator type

  MRG32K3A = 402

    MRG32k3a pseudo-random generator type

  MT19937 = 407

    Mersenne Twister pseudo-random generator type

  MTGP32 = 403

    Mersenne Twister MTGP32 pseudo-random generator type

  PHILOX4_32_10 = 404

    PHILOX_4x32 (10 rounds) pseudo-random generator type

  THREEFRY2_32_20 = 408

    THREEFRY2_32_20 pseudo-random generator type

  THREEFRY2_64_20 = 409

    THREEFRY2_64_20 pseudo-random generator type

  THREEFRY4_32_20 = 410

    THREEFRY4_32_20 pseudo-random generator type

  THREEFRY4_64_20 = 411

    THREEFRY4_64_20 pseudo-random generator type

  XORWOW = 401

    XORWOW pseudo-random generator type

  generate(ary, size=None)

    Generates uniformly distributed integers.

    Generates size (if present) or ary.size uniformly distributed integers and saves them to ary.

    Supported dtype of ary: `numpy.uint32`, `numpy.int32`.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - size – Number of samples to generate, default to ary.size

  lognormal(ary, mean, stddev, size=None)

    Generates log-normally distributed floats.

    Generates size (if present) or ary.size log-normally distributed floats and saves them to ary.

    Supported dtype of ary: `numpy.float32`, `numpy.float64`.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - mean – Mean value of log normal distribution

      - stddev – Standard deviation value of log normal distribution

      - size – Number of samples to generate, default to ary.size

  normal(ary, mean, stddev, size=None)

    Generates normally distributed floats.

    Generates size (if present) or ary.size normally distributed floats and saves them to ary.

    Supported dtype of ary: `numpy.float32`, `numpy.float64`.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - mean – Mean value of normal distribution

      - stddev – Standard deviation value of normal distribution

      - size – Number of samples to generate, default to ary.size

  property offset

    Mutable attribute of the offset of random numbers sequence.

    Setting this attribute resets the sequence.

  poisson(ary, lmbd, size=None)

    Generates Poisson-distributed integers.

    Generates size (if present) or ary.size Poisson-distributed integers and saves them to ary.

    Supported dtype of ary: `numpy.uint32`, `numpy.int32`.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - lmbd – lambda for the Poisson distribution

      - size – Number of samples to generate, default to ary.size

  property seed

    Mutable attribute of the seed of random numbers sequence.

    Setting this attribute resets the sequence.

  uniform(ary, size=None)

    Generates uniformly distributed floats.

    Generates size (if present) or ary.size uniformly distributed floats and saves them to ary.

    Supported dtype of ary: `numpy.float32`, `numpy.float64`.

    Generated numbers are between 0.0 and 1.0, excluding 0.0 and including 1.0.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - size – Number of samples to generate, default to ary.size

## 4.2. class QRNG

class rocrand.QRNG(rngtype=500, ndim=None, offset=None, stream=None)

  Creates a new quasi-random number generator.

  A new quasi-random number generator of type rngtype is initialized with given ndim, offset and stream.

  Values of rngtype:

  - `DEFAULT`

  - `SOBOL32`

  - `SCRAMBLED_SOBOL32`

  - `SOBOL64`

  - `SCRAMBLED_SOBOL64`

  Values of ndim are 1 to 20000.

  Parameters:

    - rngtype – Type of quasi-random number generator to create

    - ndim – Number of dimensions

    - offset – Initial offset of random numbers sequence

    - stream – HIP stream for all kernel launches of the generator

  Example:

      import rocrand
      import numpy as np

      gen = rocrand.QRNG(rocrand.QRNG.SOBOL32, ndim=4)
      a = np.empty(1000, np.float32)
      gen.normal(a, 0.0, 1.0)
      print(a)

  DEFAULT = 500

    Default quasi-random generator type, `SOBOL32`

  SCRAMBLED_SOBOL32 = 502

    Scrambled Sobol32 quasi-random generator type

  SCRAMBLED_SOBOL64 = 505

    Scrambled Sobol64 quasi-random generator type

  SOBOL32 = 501

    Sobol32 quasi-random generator type

  SOBOL64 = 504

    Sobol64 quasi-random generator type

  generate(ary, size=None)

    Generates uniformly distributed integers.

    Generates size (if present) or ary.size uniformly distributed integers and saves them to ary.

    Supported dtype of ary: `numpy.uint32`, `numpy.int32`.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - size – Number of samples to generate, default to ary.size

  lognormal(ary, mean, stddev, size=None)

    Generates log-normally distributed floats.

    Generates size (if present) or ary.size log-normally distributed floats and saves them to ary.

    Supported dtype of ary: `numpy.float32`, `numpy.float64`.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - mean – Mean value of log normal distribution

      - stddev – Standard deviation value of log normal distribution

      - size – Number of samples to generate, default to ary.size

  property ndim

    Mutable attribute of the number of dimensions of random numbers sequence.

    Supported values are 1 to 20000. Setting this attribute resets the sequence.

  normal(ary, mean, stddev, size=None)

    Generates normally distributed floats.

    Generates size (if present) or ary.size normally distributed floats and saves them to ary.

    Supported dtype of ary: `numpy.float32`, `numpy.float64`.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - mean – Mean value of normal distribution

      - stddev – Standard deviation value of normal distribution

      - size – Number of samples to generate, default to ary.size

  property offset

    Mutable attribute of the offset of random numbers sequence.

    Setting this attribute resets the sequence.

  poisson(ary, lmbd, size=None)

    Generates Poisson-distributed integers.

    Generates size (if present) or ary.size Poisson-distributed integers and saves them to ary.

    Supported dtype of ary: `numpy.uint32`, `numpy.int32`.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - lmbd – lambda for the Poisson distribution

      - size – Number of samples to generate, default to ary.size

  uniform(ary, size=None)

    Generates uniformly distributed floats.

    Generates size (if present) or ary.size uniformly distributed floats and saves them to ary.

    Supported dtype of ary: `numpy.float32`, `numpy.float64`.

    Generated numbers are between 0.0 and 1.0, excluding 0.0 and including 1.0.

    Parameters:

      - ary – NumPy array (`numpy.ndarray`) or HIP device-side array (`DeviceNDArray`)

      - size – Number of samples to generate, default to ary.size

## 4.3. Exceptions

exception rocrand.RocRandError(value)

  Run-time rocRAND error.

exception rocrand.HipError(value)

  Run-time HIP error.

## 4.4. Utilities

class rocrand.DeviceNDArray(shape, dtype, data=None)

  Create an empty device-side array.

  This class is a limited version of `numpy.ndarray` for device-side arrays.

  Parameters:

    - shape – Shape of the array (see `numpy.ndarray.shape`)

    - dtype – Type of the array (see `numpy.ndarray.dtype`)

    - data – existing HIP device-side memory pointer

  copy_to_host(ary=None)

    Copy from data device memory to host memory.

    If ary is passed then ary must have the same dtype and greater or equal size as self has.

    If ary is not passed then a new `numpy.ndarray` will be created.

    Parameters:

      ary – NumPy array (`numpy.ndarray`)

    Returns:

      a new array or ary

rocrand.empty(shape, dtype)

  Create a new device-side array of given shape and type, without initializing entries.

  This function is a limited version of `numpy.empty()` for device-side arrays.

  Example:

      import rocrand
      import numpy as np

      gen = rocrand.QRNG(ndim=5)
      d_a = rocrand.empty((5, 10000), dtype=np.float32)
      gen.uniform(d_a)
      a = d_a.copy_to_host()
      print(a)

  See `DeviceNDArray`

  Parameters:

    - shape (int or tuple of int) – Shape of the array (see `numpy.ndarray.shape`)

    - dtype – Type of the array (see `numpy.ndarray.dtype`)

rocrand.get_version()

  Returns the version number of the rocRAND library.