AOCL-RNG - 5.0 English - 57404

AOCL User Guide (57404)
Document ID
57404
Release Date
2024-12-14
Version
5.0 English

9. AOCL-RNG#

AOCL-RNG is a high-performance implementation of vector based Random Number Generator library which provides a set of pseudo-random number generators, quasi-random number generator and statistical distribution functions optimized for AMD “Zen”-based processors.

Statistical distribution functions include continuous as well as discrete type. This library provides random numbers of type Integer, Single Precision and Double Precision. This library provides seven base generators and twenty-three distribution functions.

Furthermore, customization is possible to use a custom-built generator as the base generator for all distribution generators.

This library depends on other libraries AOCL-LibM and Single-threaded AOCL-BLAS.

AOCL-RNG provides following base generators and distribution functions:

  • Pseudo-Random Number Generator

    • NAG Basic Generator

    • Wichmann-Hill Generators

    • L’Ecuyer’s Combined Recursive (MRG32K3A) Generator

    • Mersenne Twister Generator

    • SIMD-oriented Fast Mersenne Twister (SFMT) Generator

    • Blum-Blum-Shub Generator (deprecated)

  • Quasi-Random Number Generator

    • Sobol Generator

  • Statistical continuous distribution functions

    • Beta Distribution

    • Cauchy Distribution

    • Chi-square Distribution

    • Exponential Distribution

    • Gamma Distribution

    • Gaussian or Normal Distribution

    • Lognormal Distribution

    • Uniform Distribution

    • Weibull Distribution

    • F-Distribution

    • Logistic Distribution

    • Students T Distribution

    • Triangular Distribution

    • VonMises Distribution

    • Multivariate Gaussian or Normal Distribution

    • Multivariate Students T Distribution

  • Statistical discrete distribution functions

    • Binomial Distribution

    • Geometric Distribution

    • Hypergeometric Distribution

    • Negative Binomial Distribution

    • Poisson Distribution

    • Uniform Distribution

    • Multinomial Distribution

Refer RNG documentation for more information.

Note

  1. Behavior might be undefined if AVX512 is disabled in the BIOS configuration on the Zen5 platform.

9.1. Installation#

AOCL-RNG can be installed from pre-built binaries only.

AOCL-RNG library has runtime dependency on AOCL-LibM and Single-threaded AOCL-BLAS libraries so these libraries must also be installed along with AOCL-RNG.

Table 9.1 Library name for AOCL-RNG#

Library

Linux

Windows

Dynamic

Static

Dynamic

Static

AOCL-RNG

librng_amd.so

librng_amd.a

rng_amd.dll rng_amd.lib

rng_amd-static.lib

9.1.1. Using Pre-Built Libraries on Linux#

AOCL-RNG binary can be installed along with AOCL-LibM and AOCL-BLAS from AOCL master installer tar file available under AOCL Download section.

The master installer tar file could be used to install any standalone or whole package of pre-built AOCL libraries as explained in Using Master Package.

Local environment may use library after executing below command,

$ source $HOME/aocl/<version>/<gcc-or-aocc>/amd-libs.cfg

Alternatively, AOCL-RNG can also be installed using standalone package available under AOCL-RNG Download section.

Other dependencies should also be downloaded from standalone packages available under respective library pages AOCL-LibM Download section and Single-threaded AOCL-BLAS Download section.

9.1.2. Using Pre-Built Libraries on Windows#

AOCL-RNG binary for Windows can only be installed from AOCL windows installer exe file available under AOCL Download section.

The windows master installer could be used to install whole package of pre-built AOCL libraries as explained in Using Windows Packages.

Local environment may use library after setting PATH like below,

> set "PATH=C:\Program Files\AMD\AOCL-Windows\amd-rng\lib\LP64;%PATH%"
> set "PATH=C:\Program Files\AMD\AOCL-Windows\amd-secrng\lib\LP64;%PATH%"
> set "PATH=C:\Program Files\AMD\AOCL-Windows\amd-libm\lib;%PATH%"
> set "PATH=C:\Program Files\AMD\AOCL-Windows\amd-blis\lib\LP64;%PATH%"

9.2. Using AOCL-RNG Library#

AOCL-RNG release package contains examples directory, which includes reference applications to demonstrate using APIs provided by library. CMake script is also provided to build and execute the programs. Provided CMake script works on both Linux as well as Windows. Refer examples/README.md file for more information.

Simple reference application is provided below to demonstrate about using AOCL-RNG.

  1. Include rng.h header file in your program.

  2. Link the appropriate version of libraries in your program.

  3. AOCL-RNG depends on AOCL-LibM and Single-threaded AOCL-BLAS libraries so link them all to your program.

  4. AOCL-RNG also depends on AOCL-SecureRNG library -lamdsecrng so same should be linked as well.

Listing 9.1 get_random.c#
 1#include <stdio.h>
 2#include <stdlib.h>
 3#include <rng.h>
 4
 5#define N          10
 6#define NAG_GENID  1
 7#define NAG_SUBID  0
 8#define SEED       123456
 9
10/*
11 * Base Generator : NAG Basic Generator
12 * Distribution   : Uniform Distribution
13 * RN Precision   : Double Precision
14 */
15
16int main()
17{
18  rng_int_t genid, subid, lseed, lstate, info;
19  rng_int_t seed[1] = {SEED};
20  rng_int_t *state  = NULL;
21  double a=0.0, b=1.0;
22  double rnum[N];
23
24  genid  = NAG_GENID;
25  subid  = NAG_SUBID;
26  lseed  = 1;
27  lstate = -1;
28
29  drandinitialize(genid, subid, seed, &lseed, state, &lstate, &info);
30  if (info < 0) {
31    printf("Error Code: %d \n", info);
32    exit(0);
33  }
34
35  state = (rng_int_t *) malloc(lstate * sizeof(rng_int_t));
36  /* skipping mem error check */
37
38  drandinitialize(genid, subid, seed, &lseed, state, &lstate, &info);
39  dranduniform(N, a, b, state, rnum, &info);
40  /* skipping error check */
41
42  for (int i=0; i<N; i++) {
43    printf("%10.4f \n", rnum[i]);
44  }
45
46  free(state);
47  return 0;
48}

9.2.1. Using on Linux#

AOCL-RNG should be installed as instructed in Using Pre-Built Libraries on Linux.

Use following commands to build your application.

$ source $HOME/aocl/<version>/<gcc-or-aocc>/amd-libs.cfg
$ CC get_random.c -o get_random -lrng_amd -lamdsecrng
                       OR
$ CC get_random.c -o get_random -lrng_amd -lamdsecrng -lamdlibm -lblis -lm -lgfortran
$ ./get_random

Notes:
  1. CC can be 'gcc' or 'clang'.
  2. If 'clang', AOCL environment setting should be done after AOCC.

9.2.2. Using on Windows#

AOCL-RNG should be installed as instructed in Using Pre-Built Libraries on Windows.

Complete the following steps to use AOCL-RNG library on Windows:

  1. Create a 64-bit console app project in Visual Studio 17 2022.

  2. Use the following navigation to select Clang-cl compiler: Project > Properties > Configuration Properties > General > Platform Toolset > LLVM(Clang-cl)

  3. Use get_random.c as a reference application.

  4. Copy the AOCL-RNG header file rng.h and AOCL-RNG dll library rng_amd.dll and rng_amd.lib to the same project folder.

  5. Copy AOCL-LibM DLL library libalm.dll and libalm.lib to the same project folder.

  6. Copy AOCL-BLAS single-threaded DLL library AOCL-LibBlis-Win-dll.dll and AOCL-LibBlis-Win-dll.lib to the same project folder.

  7. Use the following navigation to add WIN64 preprocessor definition: Project > Properties > C/C++ > Preprocessor > Preprocessor Definitions

  8. Compile and then run the application.

  9. You may create Fortran based project in similar manner and compile it using ifort compiler.

  10. You can also compile your application using AOCL-RNG static library rng_amd-static.lib.

9.3. Using AOCL-RNG Library Features#

  • AOCL-RNG supports dynamic dispatch. This feature enables using the same binary with different code paths optimized for different Instruction Set Architecture (ISA).

  • AOCL-RNG also supports the environment variable AOCL_ENABLE_INSTRUCTIONS that enables users to dispatch to the preferred ISA-specific code path. Refer to the AOCL Performance Tuning Guide for more information.