Prefer high bits (#36)

* Add preferHighBits property

* replace $(D) with ``

they are the same

* preferHighBits only if isSaturatedRandomEngine

* Make preferHighBits!T public and move to mir.random.engine

* Update package.d

source/mir/random/engine/linear_congruential.d

@@ -18,7 +18,7 @@ struct LinearCongruentialEngine(Uint, Uint a, Uint c, Uint m)
     ///
     enum isRandomEngine = true;
 
-    /// Highest generated value ($(D modulus - 1 - bool(c == 0))).
+    /// Highest generated value (`modulus - 1 - bool(c == 0)`).
     enum Uint max = m - 1 - bool(c == 0);
 /**
 The parameters of this distribution. The random number is $(D_PARAM x
@@ -34,6 +34,14 @@ The parameters of this distribution. The random number is $(D_PARAM x
     static assert(m == 0 || c < m);
     static assert(m == 0 || (cast(ulong)a * (m-1) + c) % m == (c < a ? c - a + m : c - a));
 
+    /++
+    The low bits of a linear congruential generator whose modulus is a
+    power of 2 have a much shorter period than the high bits.
+    Note that for LinearCongruentialEngine, `modulus == 0` signifies
+    a modulus of `2 ^^ Uint.sizeof` which is not representable as `Uint`.
+    +/
+    enum bool preferHighBits = 0 == (modulus & (modulus - 1));
+
     @disable this();
     @disable this(this);
 
@@ -107,7 +115,7 @@ The parameters of this distribution. The random number is $(D_PARAM x
 
 /**
 Constructs a $(D_PARAM LinearCongruentialEngine) generator seeded with
-$(D x0).
+`x0`.
 Params:
     x0 = seed, must be positive if c equals to 0.
  */
@@ -171,10 +179,10 @@ Params:
 
 /**
 Define $(D_PARAM LinearCongruentialEngine) generators with well-chosen
-parameters. $(D MinstdRand0) implements Park and Miller's "minimal
+parameters. `MinstdRand0` implements Park and Miller's "minimal
 standard" $(HTTP
 wikipedia.org/wiki/Park%E2%80%93Miller_random_number_generator,
-generator) that uses 16807 for the multiplier. $(D MinstdRand)
+generator) that uses 16807 for the multiplier. `MinstdRand`
 implements a variant that has slightly better spectral behavior by
 using the multiplier 48271. Both generators are rather simplistic.
  */

source/mir/random/engine/package.d

@@ -72,6 +72,32 @@ template isSaturatedRandomEngine(T)
         enum isSaturatedRandomEngine = false;
 }
 
+/++
+Are the high bits of the engine's output known to have
+better statistical properties than the low bits of the
+output? This property is set by checking the value of
+an optional enum named `preferHighBits`. If the property
+is missing it is treated as false.
+
+This should be specified as true for:
+<ul>
+<li>linear congruential generators with power-of-2 modulus</li>
+<li>xorshift+ family</li>
+<li>xorshift* family</li>
+<li>in principle any generator whose final operation is something like
+multiplication or addition in which the high bits depend on the low bits
+but the low bits are unaffected by the high bits.</li>
+</ul>
++/
+template preferHighBits(G)
+    if (isSaturatedRandomEngine!G)
+{
+    static if (__traits(compiles, { enum bool e = G.preferHighBits; }))
+        private enum bool preferHighBits = G.preferHighBits;
+    else
+        private enum bool preferHighBits = false;
+}
+
 /**
 A "good" seed for initializing random number engines. Initializing
 with $(D_PARAM unpredictableSeed) makes engines generate different

source/mir/random/engine/xorshift.d

@@ -193,6 +193,15 @@ if (isIntegral!StateUInt && isIntegral!OutputUInt
     static assert(multiplier != 1 && multiplier % 2 != 0,
         typeof(this).stringof~": multiplier must be an odd number other than 1!");
 
+    /++
+    Note that when StateUInt is the same size as OutputUInt the two lowest bits
+    of this generator are
+    $(LINK2 https://en.wikipedia.org/wiki/Linear-feedback_shift_register,
+    LSFRs), and thus will fail binary rank tests. We suggest to use a sign test
+    to extract a random Boolean value, and right shifts to extract subsets of bits.
+    +/
+    enum bool preferHighBits = true;
+
   private:
     enum uint N = nbits / (StateUInt.sizeof * 8);
     enum bool usePointer = N > 3;
@@ -432,6 +441,17 @@ struct Xoroshiro128Plus
     +/
     ulong[2] s = void;
 
+    /++
+    The lowest bit of this generator is an
+    $(LINK2 https://en.wikipedia.org/wiki/Linear-feedback_shift_register,
+    LSFR). The next bit is not an LFSR, but in the long run it will fail
+    binary rank tests, too. The other bits have no LFSR artifacts.
+
+    We suggest to use a sign test to extract a random Boolean value, and
+    right shifts to extract subsets of bits.
+    +/
+    enum bool preferHighBits = true;
+
     @disable this();
     @disable this(this);
 

source/mir/random/package.d

@@ -64,6 +64,11 @@ T rand(T, G)(ref G gen)
             (cast(R*)(&ret))[p] = gen();
         return ret;
     }
+    else static if (preferHighBits!G && P == 0)
+    {
+        version(LDC) pragma(inline, true);
+        return cast(T) (gen() >>> ((R.sizeof - T.sizeof) * 8));
+    }
     else
     {
         version(LDC) pragma(inline, true);
@@ -89,7 +94,8 @@ Returns:
 bool rand(T : bool, G)(ref G gen)
     if (isSaturatedRandomEngine!G)
 {
-    return gen() & 1;
+    import std.traits : Signed;
+    return 0 > cast(Signed!(EngineReturnType!G)) gen();
 }
 
 ///