Philox: Expose another counter through constructor (#17)

* Lower min CMake version

* document testu01 building options

* Corrected Squares' seed type; then fixed a whole bunch of compiler warnings related to type conversions

* Moved examples/readme to tests/

* Philox: Expose another counter through constructor

include/openrand/phillox.h

@@ -50,12 +50,25 @@ namespace openrand {
  */
 class Phillox : public BaseRNG<Phillox> {
  public:
+  /**
+   * @brief Construct a new Phillox object
+   *
+   * @note Internally, global_seed is treated in the same way as other counters,
+   * and can be treated as such depending on the application needs.
+   *
+   * @param seed 64-bit seed
+   * @param ctr 32-bit counter
+   * @param global_seed (Optional) 32-bit global seed.
+   * @param ctr1 (Optional) Another 32-bit counter exposed for advanced use.
+   */
   DEVICE Phillox(uint64_t seed, uint32_t ctr,
-                 uint32_t global_seed = openrand::DEFAULT_GLOBAL_SEED)
+                 uint32_t global_seed = openrand::DEFAULT_GLOBAL_SEED,
+                 uint32_t ctr1 = 0x12345)
       : seed_hi((uint32_t)(seed >> 32)),
         seed_lo((uint32_t)(seed & 0xFFFFFFFF)),
-        initctr_hi(global_seed),
-        initctr_lo(ctr) {
+        ctr0(ctr),
+        ctr1(ctr1),
+        ctr2(global_seed) {
   }
 
   template <typename T = uint32_t>
@@ -89,17 +102,19 @@ class Phillox : public BaseRNG<Phillox> {
  private:
   DEVICE void generate() {
     uint32_t key[2] = {seed_hi, seed_lo};
-    // The counter takes one of the 4 values from internal counter, one from
-    // global seed, and one is what the user provided during instantiation.
-    // Another is left constant.
-
-    // The internal counter helps to avoid forcing user to increment counter
-    // each time a number is generated.
-
-    _out[0] = 0x12345;
-    _out[1] = _ctr;
-    _out[2] = initctr_hi;
-    _out[3] = initctr_lo;
+    /**
+     * Philox 4x32 can take upto 4 counters. Here, one counter is part of the
+     * general API, mandatory during instantiation. One is (optional) global seed.
+     * Third one can be optionally set by user. 4th one is interanally managed.
+     *
+     * The internal counter helps to avoid forcing user to increment counter
+     * each time a number is generated.
+     */
+
+    _out[0] = ctr0;
+    _out[1] = ctr1;
+    _out[2] = ctr2;
+    _out[3] = ctr3;
 
     for (int r = 0; r < 10; r++) {
       if (r > 0) {
@@ -108,7 +123,7 @@ class Phillox : public BaseRNG<Phillox> {
       }
       round(key, _out);
     }
-    _ctr++;
+    ctr3++;
   }
 
   inline DEVICE uint32_t mulhilo(uint32_t L, uint32_t R, uint32_t *hip) {
@@ -128,12 +143,12 @@ class Phillox : public BaseRNG<Phillox> {
     ctr[3] = lo0;
   }
 
-  // User provided seed and counter broken up, constant throughout
-  // the lifetime of the object
+  // User provided seed and counter, constant throughout
+  // the lifetime of the rng object
   const uint32_t seed_hi, seed_lo;
-  const uint32_t initctr_hi, initctr_lo;
+  const uint32_t ctr0, ctr1, ctr2;
   // private counter to keep track of numbers generated by this instance of rng
-  uint32_t _ctr = 0;
+  uint32_t ctr3 = 0;
   uint32_t _out[4];
 };  // class Phillox