improve new random generators and add tests for them

Author: TilmanNeumann

src/main/java/de/tilman_neumann/jml/random/LehmerRng64.java

@@ -27,6 +27,9 @@ public class LehmerRng64 {
 
 	private Uint128 state = mult;
 
+	/**
+	 * @return a random long number N with Long.MIN_VALUE <= N <= Long.MAX_VALUE.
+	 */
 	public long nextLong() {
 		long result = state.getHigh();
 		state = Uint128.mul128_getLow(state, mult);

src/main/java/de/tilman_neumann/jml/random/LehmerRng64MH.java

@@ -27,6 +27,9 @@ public class LehmerRng64MH {
 
 	private Uint128 state = mult;
 
+	/**
+	 * @return a random long number N with Long.MIN_VALUE <= N <= Long.MAX_VALUE.
+	 */
 	public long nextLong() {
 		long result = state.getHigh();
 		state = Uint128.mul128MH_getLow(state, mult);

src/main/java/de/tilman_neumann/jml/random/SpRand32.java

@@ -19,73 +19,70 @@
 /**
  * My Java port of the pseudo-random number generator from tinyEcm.c by Ben Buhrow.
  * 
+ * This generator is special in that nextInt() creates strictly non-negative random numbers.
+ * 
  * @author Tilman Neumann
  */
 public class SpRand32 {
 	private static final Logger LOG = LogManager.getLogger(SpRand32.class);
 
 	private static final boolean DEBUG = false;
 
+	private static final long MAX_INT_AS_LONG = Integer.MAX_VALUE;
+	
 	// seed
-	//private long LCGSTATE = 65537 * new Random().nextInt();
 	private long LCGSTATE = 4295098403L; // rng comparable with C version of TinyEcm
 
-	public int nextInt(int lower, int upper) {
+	/**
+	 * @return a random int number N with 0 <= N <= Integer.MAX_VALUE.
+	 */
+	public int nextInt() {
 		if (DEBUG) LOG.debug("LCGSTATE=" + LCGSTATE);
 
-		// fix rng for negative upper values
-		long upperl = (long) upper;
-		if (upperl<0) upperl += (1L<<32);
-		long diff = upperl - lower;
-		if (DEBUG) LOG.debug("lower=" + lower + ", upper=" + upperl + ", diff=" + diff);
-		
 		// advance the state of the LCG and return the appropriate result
 		LCGSTATE = 6364136223846793005L * LCGSTATE + 1442695040888963407L;
 		long LCGSTATE_shifted = LCGSTATE >>> 32;
 		if (DEBUG) LOG.debug("LCGSTATE=" + LCGSTATE + ", LCGSTATE_shifted=" + LCGSTATE_shifted);
 
 		double quot = (double)LCGSTATE_shifted / 4294967296.0; // dividend is 2^32
-		double prod = diff * quot;
+		double prod = MAX_INT_AS_LONG * quot;
 		int rand = (int)(0xFFFFFFFF & (long)prod); // (int)prod does not work for prod >= 2^31
-		int result = lower + rand;
+		int result = rand;
 		if (DEBUG) LOG.debug("quot=" + quot + ", prod=" + prod + ", rand=" + rand + ", result=" + result);
 		return result;
 	}
 
-	public int nextInt(int upper) {
+	/**
+	 * @param max
+	 * @return a random int number N with 0 <= N <= max.
+	 */
+	public int nextInt(int max) {
 		if (DEBUG) LOG.debug("LCGSTATE=" + LCGSTATE);
 
 		// fix rng for negative upper values
-		long upperl = (long) upper;
-		if (upperl<0) upperl += (1L<<32);
-		if (DEBUG) LOG.debug("upper=" + upperl);
+		long maxLong = (long) max;
+		if (maxLong<0) maxLong += (1L<<32);
+		if (DEBUG) LOG.debug("max=" + maxLong);
 
 		// advance the state of the LCG and return the appropriate result
 		LCGSTATE = 6364136223846793005L * LCGSTATE + 1442695040888963407L;
 		long LCGSTATE_shifted = LCGSTATE >>> 32;
 		if (DEBUG) LOG.debug("LCGSTATE=" + LCGSTATE + ", LCGSTATE_shifted=" + LCGSTATE_shifted);
 
 		double quot = (double)LCGSTATE_shifted / 4294967296.0; // dividend is 2^32
-		double prod = upperl * quot;
+		double prod = maxLong * quot;
 		int rand = (int)(0xFFFFFFFF & (long)prod); // (int)prod does not work for prod >= 2^31
 		int result = rand;
 		if (DEBUG) LOG.debug("quot=" + quot + ", prod=" + prod + ", rand=" + rand + ", result=" + result);
 		return result;
 	}
 
-	public int nextInt() {
-		if (DEBUG) LOG.debug("LCGSTATE=" + LCGSTATE);
-		
-		// advance the state of the LCG and return the appropriate result
-		LCGSTATE = 6364136223846793005L * LCGSTATE + 1442695040888963407L;
-		long LCGSTATE_shifted = LCGSTATE >>> 32;
-		if (DEBUG) LOG.debug("LCGSTATE=" + LCGSTATE + ", LCGSTATE_shifted=" + LCGSTATE_shifted);
-		
-		double quot = (double)LCGSTATE_shifted / 4294967296.0; // dividend is 2^32
-		double prod = Integer.MAX_VALUE * quot;
-		int rand = (int)(0xFFFFFFFF & (long)prod); // (int)prod does not work for prod >= 2^31
-		int result = rand;
-		if (DEBUG) LOG.debug("quot=" + quot + ", prod=" + prod + ", rand=" + rand + ", result=" + result);
-		return result;
+	/**
+	 * @param min
+	 * @param max
+	 * @return a random int number N with lower <= N <= max.
+	 */
+	public int nextInt(int min, int max) {
+		return min + nextInt(max - min);
 	}
 }

src/main/java/de/tilman_neumann/jml/random/Xorshf32.java

@@ -17,17 +17,16 @@
  * Java port of Marsaglia's xorshf generator.
  * @see https://stackoverflow.com/questions/1640258/need-a-fast-random-generator-for-c<br/><br/>
  * 
- * <strong>WARNING: This class is experimental!</strong> SpRand32 looks faster for numbers close to 31 bit.
- * Maybe I need to improve the conversion from C "unsigned long" to Java int (shifts, masks etc.).
+ * This generator is special in that nextInt() creates strictly non-negative random numbers.
  * 
  * @author Tilman Neumann
  */
 public class Xorshf32 {
 
 	private int x=123456789, y=362436069, z=521288629;
 
-	public int nextInt(int min, int max) {
-	    return min + nextInt(max - min);
+	public int nextInt() {
+	    return nextInt(Integer.MAX_VALUE);
 	}
 
 	public int nextInt(int max) {
@@ -43,8 +42,8 @@ public int nextInt(int max) {
 
 	    return Math.abs(z % max);
 	}
-	
-	public int nextInt() {
-	    return nextInt(Integer.MAX_VALUE);
+
+	public int nextInt(int min, int max) {
+	    return min + nextInt(max - min);
 	}
 }

src/main/java/de/tilman_neumann/jml/random/Xorshf32b.java

@@ -14,14 +14,17 @@
 package de.tilman_neumann.jml.random;
 
 /**
- * An <strong>experimental</strong> variant of Marsaglia's xorshf generator.
+ * A variant of Marsaglia's xorshf generator.
  * 
  * @author Tilman Neumann
  */
 public class Xorshf32b {
 
 	private int x=123456789, y=362436069, z=521288629;
 
+	/**
+	 * @return a random long number N with Integer.MIN_VALUE <= N <= Integer.MAX_VALUE.
+	 */
 	public int nextInt() {
 		int t;
 	    x ^= x << 16;
@@ -36,8 +39,13 @@ public int nextInt() {
 	    return z;
 	}
 
+	/**
+	 * @param max
+	 * @return a random int number N with 0 <= N <= max.
+	 */
 	public int nextInt(int max) {
-		final long l = nextInt();  // up to unsigned 2^32 - 1
+		final long i = nextInt();
+		final long l = i<0 ? -i : i;  // up to unsigned 2^32 - 1
 		final long prod = l * max; // up to max * (2^32 - 1)
 	    return (int) (prod >>> 32);
 	}

src/main/java/de/tilman_neumann/jml/random/Xorshf64.java

@@ -14,20 +14,26 @@
 package de.tilman_neumann.jml.random;
 
 /**
- * <strong>Experimental</strong> 64 bit random number generator computing longs from two consecutive 32 bit random numbers.
+ * <strong>Experimental</strong> 64 bit random number generator computing longs from three consecutive 32 bit random numbers.
  * 
  * @author Tilman Neumann
  */
 public class Xorshf64 {
 
-	private Xorshf32 intGenerator = new Xorshf32();
+	private Xorshf32b intGenerator = new Xorshf32b();
 
-	public long nextLong() {
-	    return ((long) intGenerator.nextInt()) * intGenerator.nextInt();
-	}
-	
-	// TODO nextLong(upper)
+	private long i1, i2;
 
-	// TODO nextLong(lower, upper)
+	public Xorshf64() {
+		i1 = intGenerator.nextInt();
+		i2 = intGenerator.nextInt();
+	}
 
+	public long nextLong() {
+		final long i3 = intGenerator.nextInt();
+	    long result = ((i1*i2)<<1) + i3; // make upper bound 63 bit
+	    i1 = i2;
+	    i2 = i3;
+	    return result;
+	}
 }

src/main/java/de/tilman_neumann/jml/random/Xorshf64b.java

@@ -0,0 +1,53 @@
+/*
+ * java-math-library is a Java library focused on number theory, but not necessarily limited to it. It is based on the PSIQS 4.0 factoring project.
+ * Copyright (C) 2018-2025 Tilman Neumann - [email protected]
+ *
+ * This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program;
+ * if not, see <http://www.gnu.org/licenses/>.
+ */
+package de.tilman_neumann.jml.random;
+
+import static org.junit.Assert.assertTrue;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import de.tilman_neumann.util.ConfigUtil;
+
+/**
+ * Tests of the LehmerRng64MH random number generator.
+ * 
+ * @author Tilman Neumann
+ */
+public class LehmerRng64MHTest {
+	private static final Logger LOG = LogManager.getLogger(LehmerRng64MHTest.class);
+
+	private static final int NCOUNT = 1000000;
+	
+	private static final LehmerRng64MH rng = new LehmerRng64MH();
+	
+	@BeforeClass
+	public static void setup() {
+		ConfigUtil.initProject();
+	}
+	
+	@Test
+	public void testNextLongNoArgs() {
+		long min = Long.MAX_VALUE, max = Long.MIN_VALUE;
+		for (int i=0; i<NCOUNT; i++) {
+			long n = rng.nextLong();
+			if (n<min) min = n;
+			if (n>max) max = n;
+		}
+		LOG.debug(NCOUNT + " numbers from " + rng.getClass().getSimpleName() + ".nextLong() gave min = " + min + ", max = " + max);
+		assertTrue(min < 0);
+	}
+}

src/test/java/de/tilman_neumann/jml/random/LehmerRng64MHTest.java

@@ -1,26 +1,53 @@
+/*
+ * java-math-library is a Java library focused on number theory, but not necessarily limited to it. It is based on the PSIQS 4.0 factoring project.
+ * Copyright (C) 2018-2025 Tilman Neumann - [email protected]
+ *
+ * This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program;
+ * if not, see <http://www.gnu.org/licenses/>.
+ */
 package de.tilman_neumann.jml.random;
 
+import static org.junit.Assert.assertTrue;
+
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.junit.BeforeClass;
+import org.junit.Test;
 
 import de.tilman_neumann.util.ConfigUtil;
 
 /**
  * Tests of Lehmer's random number generator for 64 bit numbers.
  * 
- * Currently only prints some generated numbers.
- * 
  * @author Tilman Neumann
  */
 public class LehmerRng64Test {
 	private static final Logger LOG = LogManager.getLogger(LehmerRng64Test.class);
+
+	private static final int NCOUNT = 1000000;
 
-	public static void main(String[] args) {
+	private static final LehmerRng64 rng = new LehmerRng64();
+	
+	@BeforeClass
+	public static void setup() {
 		ConfigUtil.initProject();
-		
-		LehmerRng64 rng = new LehmerRng64();
-		for (int i=0;i<100; i++) {
-			LOG.debug("" + rng.nextLong());
+	}
+	
+	@Test
+	public void testNextLongNoArgs() {
+		long min = Long.MAX_VALUE, max = Long.MIN_VALUE;
+		for (int i=0; i<NCOUNT; i++) {
+			long n = rng.nextLong();
+			if (n<min) min = n;
+			if (n>max) max = n;
 		}
+		LOG.debug(NCOUNT + " numbers from " + rng.getClass().getSimpleName() + ".nextLong() gave min = " + min + ", max = " + max);
+		assertTrue(min < 0);
 	}
 }

src/test/java/de/tilman_neumann/jml/random/LehmerRng64Test.java

@@ -47,7 +47,6 @@ public class RngPerformanceTest {
 	private static final LehmerRng64 lehmer64 = new LehmerRng64();
 	private static final LehmerRng64MH lehmer64MH = new LehmerRng64MH();
 	private static final Xorshf64 xorshf64 = new Xorshf64();
-	private static final Xorshf64b xorshf64b = new Xorshf64b();
 
 	/**
 	 * Test.
@@ -172,9 +171,5 @@ public static void main(String[] args) {
 			xorshf64.nextLong();
 		}
 		LOG.debug("Xorshf64.nextLong() took " + timer.capture() + " ms");
-		for (int i=0; i<NCOUNT; i++) {
-			xorshf64b.nextLong();
-		}
-		LOG.debug("Xorshf64b.nextLong() took " + timer.capture() + " ms");
 	}
 }