random123

Counter-based Random Number Generators
git clone git://git.meso-star.com/random123.git
Log | Files | Refs | README | LICENSE

README (6737B)

      1 This file is examples/README and is also linked to from the doxygen main page.
      2 
      3 /**
      4 @page TestsREADME Tests and Benchmarks
      5 
      6 The tests/ directory contains tests and timing
      7 harnesses for the components of the Random123 library.
      8 
      9 <b>See @ref ExamplesREADME "../examples" for examples</b> of how to
     10 use the Random123 APIs in different contexts.
     11 
     12 The code in this directory (tests/) is not exemplary because it
     13 sacrifices readability to support many different generators (philox,
     14 threefry, ARS), programming models (C, C++, CUDA, OpenCL, Metal),
     15 compilers (gcc, clang, icc), hardware (Intel, ARM, NVidia), and
     16 operating systems (Linux, Windows, OSX).
     17 
     18 @section building Compiling and Running the code
     19 
     20 Installing and using Random123 requires only the use
     21 of the header files, and  has no prerequisites other than
     22 a reasonable C99 or C++98 compiler.
     23 
     24 With a modern GNU make (3.80 or newer), building and running the core tests
     25 and examples can be as easy as running gmake with no arguments.
     26 Note, though, that the provided tests/GNUmakefile intentionally avoids setting
     27 any of the standard make variables:  CC, CXX, CPPFLAGS, CFLAGS,
     28 CXXFLAGS, TARGET_ARCH, LDFLAGS,  LOADLIBES, LDLIBS.  GNU make
     29 will inherit settings for these variables from the environment,
     30 or they may be set on the command line.  If none  are set,
     31 compilation will proceed using system-wide default flags, generally
     32 without advanced optimization, architectural tuning, warnings, or other
     33 common options.  
     34 
     35 Before putting the Random123 library to use in an application,
     36 it is important to test it using the same compiler flags and
     37 features that the application will use.  In other words,
     38 the conventional make variables should be set
     39 the same way when testing the library as they will be set when the
     40 library is actually compiled into your application.
     41 Something like:
     42 @code
     43 gmake CFLAGS="-std=c99" CXXFLAGS="-std=c++0x" CPPFLAGS="/alternate/location/include -O3 -Wall -Wstrict-aliasing=2" TARGET_ARCH="-march=native"
     44 @endcode
     45 would confirm that all is well with optimization on, and output targeted at
     46 an architecture with the same capabilities as the machine running the compilation.
     47 
     48 Very old versions of GNU make (pre-2002) or non-GNU
     49 make will not work with tests/GNUmakefile.. Lacking a suitably modern GNU make,
     50 our advice is to invoke the
     51 C or C++ compiler directly on the source files in the tests/ directory.
     52 The file tests/BUILD.LOG contains a list of sample build commands.  They
     53 will almost certainly need to be adapted to the target system.
     54 For Windows users, BUILDVC.BAT invokes the Microsoft
     55 Visual Studio compiler.  Edit it as needed for your platform.
     56 
     57 
     58 @section tests Tests
     59 
     60 It is recommended that Random123 be tested <b> on the target system,
     61 with the target compiler, intended optimization levels, options,
     62 target architectures, etc.</b>
     63 before relying it.  The library
     64 uses architecture- and compiler-specific intrinsics,
     65 features and assembly language.  We have seen  cases where
     66 one compiler (open64 version 4.2.4) masquerades as another compiler (it defines __GNUC__) accepts extensions
     67 specific to the other compiler (__uint128_t)
     68 without error or warning, and then silently produces incorrect code.
     69 The only way to guard against this kind of misbehavior is to
     70 compile and run the tests with the compiler and options that you intend to use and
     71 the platform that you intend to run on.
     72 
     73 @subsection kat Known Answer Tests
     74 
     75 Testing that your compiled code computes the same "Known Answers" as the
     76 reference implementation which has been subjected to the Crush batteries of
     77 statistical tests is critically important.
     78 
     79 The file \c tests/kat_vectors contains a few dozen "Known Answer
     80 Test" vectors, i.e., tuples of (method, counter, key, answer).  The
     81 source file katc.c is incorporated into kat_c.c (C),
     82 kat_cpp.cpp (C++), kat_cuda.cu (CUDA) and kat_opencl.c
     83 (OpenCL), which are compiled into kat_c, kat_cpp, kat_cuda
     84 and kat_opencl, respectively.  Each of these will read kat_vectors
     85 and verify that the compiled code obtains the same "known answers".
     86 
     87 The kat vectors are not language-specific.  Implementations of CBRNGs in
     88 other languages could also be validated against \c kat_vectors.  The
     89 kat vectors are also byte-order independent.  In other
     90 words, the CBRNGs in the library should produce the same numerical
     91 results on little-endian and big-endian hardware, but this behavior
     92 is largely untested.
     93 
     94 @subsection ut Unit Tests
     95 
     96 tests/ also contains tests of specific components of the library.  While not
     97 exhaustive, these tests verify that a variety of invariants are satisfied
     98 by the public methods (e.g., that incr(N) is the same as incr() N times).  They
     99 also serve to verify some of the compile-time feature-test logic which, if incorrect can
    100 lead to mysterious errors (e.g., is it necessary to <c>#include <smmintrin.h></c>).
    101 Unit tests include:
    102 
    103 <ul>
    104 <li> ut_features - verifies compile-time feature-test logic.
    105 <li> ut_carray - verifies the capabilities of the @ref arrayNxW "r123arrayNxW" types.
    106 <li> ut_M128 - verifies the capabilities of the r123m128i type (only when SSE2 is available).
    107 <li> ut_ReinterpretCtr - verifies the r123::ReinterpretCtr wrapper template.
    108 <li> ut_Engine - verifies the capabilities of the r123::Engine wrapper template.
    109 <li> ut_aes - verifies that the @ref AESNI "AESNI" cbrngs match known answers from FIPS-197.
    110 <li> ut_gsl - tests the @ref GSL_CBRNG adapter <b>Requires the GNU Scientific Library</b>.
    111 </ul>
    112 
    113 @section timers Measuring performance
    114 
    115 We include some timing harnesses that can be used to measure
    116 the performance of these CBRNGs on various platforms. They report aggregate throughput
    117 in GB/sec:  a direct
    118 measure of performance, but one that depends on clock speed
    119 and number of cores being used.  They also report cpB (cycles-per-byte)
    120 if they are invoked with an environment variable.  For example, 
    121 <pre>
    122 <code>
    123    env TIME_SERIAL_CPU_GHZ=3.2 ./time_serial
    124 </code>
    125 </pre>
    126 will report cpB assuming a 3.2GHz clock.
    127 
    128 <ul>
    129 <li> time_serial - uses the C API and reports performance for a
    130 single core.
    131 <li> timers - uses the C++ API, and is the only tool that reports
    132 AESNI1xm128i and ARS1xm128i performance (if your CPU supports the AES-NI instruction
    133 extensions).
    134 <li> time_thread - uses the C API and pthreads to report
    135 multithreaded performance.  Uses TIME_THREAD_NTHREADS (or 12 if unset) threads.
    136 <li> time_cuda - uses the C API within NVIDIA CUDA to run on NVIDIA GPUs.
    137 <li> time_opencl - uses the C API within OpenCL to run on GPUs or CPUs.
    138 </ul>
    139 
    140 time_serial, time_thread, time_cuda, time_opencl all use a common 
    141 kernel defined in time_random123.h.  They all use various 
    142 util_* header files for utility functions and platform-related
    143 boilerplate (also used by the pi_* examples).
    144 
    145 */