### Dieharder Custom Test Configuration (10 seconds)

Source: https://github.com/martymacgyver/practrand/blob/master/doc/Tests_results.txt

Example command for running Dieharder with the 'dab_monobit2' test for 10 seconds. This configuration is part of a custom test suite setup.

```bash
./RNG_output ranrot32 123456789000000 | dieharder -g 200 -D 504 -D 16384 -d dab_monobit2 -t 100000000
```

--------------------------------

### Dieharder Custom Test Configuration (10 seconds, dab_dct)

Source: https://github.com/martymacgyver/practrand/blob/master/doc/Tests_results.txt

Example command for running Dieharder with the 'dab_dct' test for 10 seconds. This is another part of a custom test suite setup, focusing on a different test.

```bash
./RNG_output ranrot32 123456789000000 | dieharder -g 200 -D 504 -D 16384 -d dab_dct -t 100000
```

--------------------------------

### Build PractRand Library and Executables

Source: https://github.com/martymacgyver/practrand/blob/master/README.md

Commands to compile the PractRand library and test executables using g++ on Linux or MinGW-W64 on Windows. Ensure you have gcc/g++ installed.

```bash
g++ -c src/*.cpp src/RNGs/*.cpp src/RNGs/other/*.cpp -O3 -Iinclude -pthread -std=gnu++11
ar rcs libPractRand.a *.o
g++ -o RNG_test tools/RNG_test.cpp libPractRand.a -O3 -Iinclude -pthread -std=gnu++11
g++ -o RNG_benchmark tools/RNG_benchmark.cpp libPractRand.a -O3 -Iinclude -pthread -std=gnu++11
g++ -o RNG_output tools/RNG_output.cpp libPractRand.a -O3 -Iinclude -pthread -std=gnu++11
```

--------------------------------

### Global RNG Initialization for Multithreading

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_multithreading.txt

Initialize the RNG and seed it with entropy before any threads start or use the RNG. This ensures a consistent starting state for all threads.

```cpp
//inside main(): (or elsewhere, as long as it runs prior to multithreading or RNG use)
  pthread_mutex_init( &thread_startup_lock, NULL);
  entropy_pool.add_entropy_automatically();
  //additional entropy_pool.add_entropy* calls go here if needed
  entropy_pool.flush_buffers();
  rng.seed(entropy_pool);
```

--------------------------------

### Complex Seeding Setup (MSVC)

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_multithreading.txt

Sets up a thread-local RNG, a global critical section for synchronization, and a global entropy pool. This approach offers more control over seeding, especially in complex multithreaded scenarios.

```cpp
//in the .h file:
extern __declspec(thread) PractRand::RNGs::Polymorphic::hc256 rng;
extern CRITICAL_SECTION thread_startup_lock;
extern PractRand::RNGs::Polymorphic::sha2_based_pool entropy_pool;
```

```cpp
//in the .cpp file:
__declspec(thread) PractRand::RNGs::Polymorphic::hc256 rng(PractRand::SEED_AUTO);
CRITICAL_SECTION thread_startup_lock;
PractRand::RNGs::Polymorphic::sha2_based_pool entropy_pool;
```

--------------------------------

### Complex Seeding Setup (Linux/GCC)

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_multithreading.txt

Declares thread-local RNG, a POSIX mutex for synchronization, and a global entropy pool. This is the Linux/GCC equivalent for controlled seeding in multithreaded applications.

```cpp
//in the .h file:
extern __thread PractRand::RNGs::Polymorphic::hc256 rng;
extern pthread_mutex_t thread_startup_lock;
extern PractRand::RNGs::Polymorphic::sha2_based_pool entropy_pool;
```

```cpp
//in the .cpp file:
__thread PractRand::RNGs::Polymorphic::hc256 rng(PractRand::SEED_AUTO);
pthread_mutex_t thread_startup_lock;
PractRand::RNGs::Polymorphic::sha2_based_pool entropy_pool;
```

--------------------------------

### Get Uniform 64-bit Integers

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Generate uniform random 64-bit (long) integers within specified ranges.

```C++
Uint64 randli(Uint64 max); //uniform random number in [0..max)
Uint64 randli(Uint64 min, Uint64 max); //uniform random number in [min..max)
```

--------------------------------

### Get Fast but Biased 32-bit Integers

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Use these faster methods for generating uniform 32-bit integers, but be aware they may introduce bias. Avoid on low-end embedded CPUs due to internal multiplication.

```C++
Uint32 randi_fast(Uint32 max); //uniform random number in [0..max), with bias
Uint32 randi_fast(Uint32 min, Uint32 max); //uniform random number in [min..max), with bias
```

--------------------------------

### Build PractRand Static Library on Linux

Source: https://github.com/martymacgyver/practrand/blob/master/doc/installation.txt

Compile PractRand source files into a static library using g++. This command includes optimization flags and specifies include paths and threading support.

```bash
g++ -c src/*.cpp src/RNGs/*.cpp src/RNGs/other/*.cpp -O3 -Iinclude -pthread
ar rcs libPractRand.a *.o
```

--------------------------------

### Build PractRand Command Line Tools on Linux

Source: https://github.com/martymacgyver/practrand/blob/master/doc/installation.txt

Compile PractRand command-line tools using g++, linking against the PractRand static library. Includes optimization and threading flags.

```bash
g++ -o RNG_test tools/RNG_test.cpp libPractRand.a -O3 -Iinclude -pthread
```

```bash
g++ -o RNG_benchmark tools/RNG_benchmark.cpp libPractRand.a -O3 -Iinclude -pthread
```

```bash
g++ -o RNG_output tools/RNG_output.cpp libPractRand.a -O3 -Iinclude -pthread
```

--------------------------------

### Get Uniform Floats

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Generate uniform random floating-point numbers in the range [0..1) or within custom ranges.

```C++
float randf(); //uniform random number in [0..1)
float randf(float max); //uniform random number in [0..max)
float randf(float min, float max); //uniform random number in [min..max)
```

--------------------------------

### Get Uniform Doubles

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Generate uniform random double-precision floating-point numbers in the range [0..1) or within custom ranges.

```C++
double randlf(); //uniform random number in [0..1)
double randlf(double max); //uniform random number in [0..max)
double randlf(double min, double max); //uniform random number in [min..max)
```

--------------------------------

### Get Uniform 32-bit Integers

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Generate uniform random 32-bit integers within specified ranges. The `randi` function provides unbiased results.

```C++
Uint32 randi(Uint32 max); //uniform random number in [0..max)
Uint32 randi(Uint32 min, Uint32 max); //uniform random number in [min..max)
```

--------------------------------

### Basic Entropy Pool Usage for Seeding an RNG

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_entropy_pools.txt

Demonstrates how to use an entropy pool to adapt a block of data for seeding a PractRand RNG. Ensure the chosen entropy pool type is polymorphic.

```C++
//things to operate on:
  Some_RNG_Type rng_to_be_seeded;
  char data_to_use_as_seed[713];

  //an entropy pooling algorithm is chosen (must be polymorphic for this purpose)
  typedef PractRand::RNGs::Polymorphic::sha2_based_pool EntropyPoolType;

  //that algorithm is used to pool the entropy:
  EntropyPoolType entropy_pool;
  for (int i = 0; i < 713; i++) entropy_pool.add_entropy8(data_to_use_as_seed[i]);
  entropy_pool.flush_buffers();

  //the pooled entropy is used to seed your RNG:
  rng_to_be_seeded->seed(&entropy_pool);
```

--------------------------------

### Get Packed Random Bits

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Use these methods to obtain raw random bits packed into integer types. These provide the highest entropy directly from the RNG.

```C++
Uint8 raw8();
Uint16 raw16();
Uint32 raw32();
Uint64 raw64();
```

--------------------------------

### Benchmark RNG Speeds with RNG_benchmark

Source: https://github.com/martymacgyver/practrand/blob/master/doc/tools.txt

Measure the speeds of recommended and candidate RNGs. Note that candidate RNGs may receive an unfair advantage due to linking. Non-recommended RNGs are not benchmarked.

```bash
RNG_benchmark
```

--------------------------------

### Include PractRand Headers

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Include the main PractRand header and the specific header for the chosen RNG algorithm. This is necessary for using any RNG from PractRand.

```cpp
#include "PractRand.h"
#include "PractRand/RNGs/hc256.h"
```

--------------------------------

### Thread-Local RNG Initialization (MSVC)

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_multithreading.txt

Initialize a thread-local RNG instance with `PractRand::SEED_AUTO` on MSVC. This allows PractRand's auto-seeding mechanism to function thread-safely after `PractRand::initialize_PractRand()` has been called.

```cpp
__declspec(thread) PractRand::RNGs::Polymorphic::hc256 rng(PractRand::SEED_AUTO);
```

--------------------------------

### Per-Thread RNG Seeding with Mutex Protection

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_multithreading.txt

Seed the RNG within each thread's initialization function using a mutex to prevent race conditions. This ensures each thread gets a unique seed derived from the global entropy pool.

```cpp
//inside per-thread initialization function:
  pthread_mutex_lock( &thread_startup_lock);
  rng.seed(entropy_pool);
  pthread_mutex_unlock( &thread_startup_lock);
```

--------------------------------

### Delayed Seeding with PractRand RNG

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Construct an RNG without an initial seed using PractRand::SEED_NONE and seed it later using autoseed() or seed(). This is an exception to the general rule that RNGs must be seeded at construction.

```cpp
PractRand::RNGs::Polymorphic::hc256 my_rng( my_seed );
```

--------------------------------

### Automatic Seeding with PractRand RNG

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Use automatic seeding for ease of use and to ensure a different random sequence on each program run. This method is generally effective and suitable for most multithreaded programs, but not recommended for cryptographic usage.

```cpp
PractRand::RNGs::Polymorphic::hc256 rng(PractRand::SEED_AUTO);
```

```cpp
rng.autoseed();
```

--------------------------------

### Test RNG with specific input size (Linux)

Source: https://github.com/martymacgyver/practrand/blob/master/doc/Tests_overview.txt

When an RNG stops sending data prematurely, use the '-tlmin 1KB' option to ensure RNG_test attempts to process at least 1024 bytes of input, even if the input stream ends early. This is useful for getting partial results.

```bash
My_RNG | ./RNG_test -tlmin 1KB stdin
```

--------------------------------

### Complex Seeding Initialization (MSVC)

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_multithreading.txt

Initializes the critical section, adds entropy to the pool, and seeds the main thread's RNG. This must be called before any multithreading or RNG usage.

```cpp
//inside main(): (or elsewhere, as long as it runs prior to multithreading or RNG use)
InitializeCriticalSection(&thread_startup_lock);
entropy_pool.add_entropy_automatically();
//additional entropy_pool.add_entropy* calls go here if needed
entropy_pool.flush_buffers();
rng.seed(entropy_pool);
```

--------------------------------

### PractRand RNG Methods

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

This section outlines the various methods provided by PractRand RNGs for generating random numbers. These methods cover different data types (integers, floats, doubles) and ranges, including uniform distributions.

```APIDOC
## PractRand RNG Methods

### Description
This section details the methods available for generating random numbers from PractRand RNGs. These include methods for raw bits, uniform integers, and uniform floating-point numbers.

### Methods

#### Raw Random Bits
These methods provide integers packed with random bits.

- `Uint8 raw8()`: Returns a random 8-bit unsigned integer.
- `Uint16 raw16()`: Returns a random 16-bit unsigned integer.
- `Uint32 raw32()`: Returns a random 32-bit unsigned integer.
- `Uint64 raw64()`: Returns a random 64-bit unsigned integer.

#### Uniform 32-bit Integers
These methods generate uniform random 32-bit integers within specified ranges.

- `Uint32 randi(Uint32 max)`: Generates a uniform random number in the range `[0..max)`.
- `Uint32 randi(Uint32 min, Uint32 max)`: Generates a uniform random number in the range `[min..max)`.

#### Uniform 32-bit Integers (Fast, Biased)
These methods are faster but may introduce bias. Avoid on low-end embedded CPUs.

- `Uint32 randi_fast(Uint32 max)`: Generates a uniform random number in `[0..max)` with potential bias.
- `Uint32 randi_fast(Uint32 min, Uint32 max)`: Generates a uniform random number in `[min..max)` with potential bias.

#### Uniform 64-bit Integers (Long Integers)
These methods generate uniform random 64-bit integers within specified ranges.

- `Uint64 randli(Uint64 max)`: Generates a uniform random number in the range `[0..max)`.
- `Uint64 randli(Uint64 min, Uint64 max)`: Generates a uniform random number in the range `[min..max)`.

#### Uniform Floats
These methods generate uniform random floating-point numbers.

- `float randf()`: Generates a uniform random number in the range `[0..1)`.
- `float randf(float max)`: Generates a uniform random number in the range `[0..max)`.
- `float randf(float min, float max)`: Generates a uniform random number in the range `[min..max)`.

#### Uniform Doubles (Long Floating Point)
These methods generate uniform random double-precision floating-point numbers.

- `double randlf()`: Generates a uniform random number in the range `[0..1)`.
- `double randlf(double max)`: Generates a uniform random number in the range `[0..max)`.
- `double randlf(double min, double max)`: Generates a uniform random number in the range `[min..max)`.

### Notes
- For non-uniform distributions (e.g., Gaussian), consider using external libraries like Boost / C++0x TR1 with `PRACTRAND_BOOST_COMPATIBILITY` defined.
```

--------------------------------

### Integer Seeding with PractRand RNG

Source: https://github.com/martymacgyver/practrand/blob/master/doc/RNG_usage.txt

Seed the RNG with a 64-bit unsigned integer to produce a consistent sequence across program runs, useful for debugging. Note that seeding from a single integer is never cryptographically secure.

```cpp
PractRand::RNGs::Polymorphic::hc256 rng(13);
```

```cpp
rng.seed(13);
```