Skip to content

PRNGine - Pseudo Random Number Engines for Monte Carlo simulations

License

Notifications You must be signed in to change notification settings

jenetics/prngine

Repository files navigation

PRNGine

Build Status Maven Central Javadoc

PRNGine is a pseudo-random number generator library for sequential and parallel Monte Carlo simulations. All PRNG implementations of this library extends the Java RandomGenerator class, which makes it easily usable in other projects. The PRNGs are not cryptographically strong RNGs.

The following PRNGs are implemented:

  • KISS32Random: Implementation of an simple PRNG as proposed in Good Practice in (Pseudo) Random Number Generation for Bioinformatics Applications (JKISS32, page 3) David Jones, UCL Bioinformatics Group.
  • KISS64Random: Implementation of an simple PRNG as proposed in Good Practice in (Pseudo) Random Number Generation for Bioinformatics Applications (JKISS64, page 10) David Jones, UCL Bioinformatics Group.
  • LCG64ShiftRandom: This class implements a linear congruential PRNG with additional bit-shift transition. It is a port of the trng::lcg64_shift PRNG class of the TRNG library created by Heiko Bauke.
  • MT19937_32Random: This is a 32-bit version of Mersenne Twister pseudorandom number generator.
  • MT19937_64Random: This is a 64-bit version of Mersenne Twister pseudorandom number generator.
  • XOR32ShiftRandom: This generator was discovered and characterized by George Marsaglia [Xorshift RNGs]. In just three XORs and three shifts (generally fast operations) it produces a full period of 232 - 1 on 32 bits. (The missing value is zero, which perpetuates itself and must be avoided.) High and low bits pass Diehard.
  • XOR64ShiftRandom: This generator was discovered and characterized by George Marsaglia [Xorshift RNGs]. In just three XORs and three shifts (generally fast operations) it produces a full period of 264 - 1 on 64 bits. (The missing value is zero, which perpetuates itself and must be avoided.) High and low bits pass Diehard.

NOTE

All implemented random generators are not thread-safe. If they are used in a multi-threaded environment, they must be synchronized externally.

Requirements

  • JDK 17: You need Java 17 for building the library.

Building PRNGine

For building the PRNGine library you have to check out the master branch from Github.

$ git clone https://github.com/jenetics/prngine.git

Executing the tests:

$ cd prngine
$ ./gradle test

Building the library:

$ ./gradle jar

Examples

PRNG creation

All random generators can be created with new or via the RandomGenerator.of("<name>") or RandomGeneratorFactory.of("<name>") factory method.

final LCG64ShiftRandom random1 = new LCG64ShiftRandom();
final RandomGenerator random2 = RandomGenerator.of("LCG64ShiftRandom");
final RandomGenerator random3 = RandomGeneratorFactory.of("LCG64ShiftRandom").create();

PRNG seeding

The library also contains methods for creating random seed values, which can be used for initializing the available PRNGs.

// Creating a new 64 bit seed value.
final long seed = Seeds.seed();
final Random ranomd = new LCG64ShiftRandom(seed);

Every random engine has a seedBytes() method, which return the seed byte[] array with the length required by the PRNG.

// This random creation is equivalent to...
final RandomGenerator random1 = new LCG64ShiftRandom();

// ...creating it with the seed bytes of the PRNG. 
final byte[] seed = LCG64ShiftRandom.seedBytes();
final RandomGenerator random2 = new LCG53ShiftRandom(seed);

Test results

Statistical tests (dieharder)

All implemented PRNGs has been tested with the dieharder test suite.

PRNG Passed Weak Failed
KISS32Random 113 1 0
KISS64Random 109 5 0
LCG64ShiftRandom 111 3 0
MT19937_32Random 111 3 0
MT19937_64Random 108 6 0
XOR32ShiftRandom 103 6 5
XOR64ShiftRandom 113 1 0
L64X256MixRandom 111 3 0

Runtime performance tests

The runtime performance of the PRNGs was tested with the JMH testing framework on an Intel Core i7-6700HQ CPU @ 2.60GHz with Java SE Runtime Environment (build 1.8.0_112-b15)—Java HotSpot.

PRNG 10e6 ints/s 10e6 floats/s F range 10e6 longs/s 10e6 doubles/s
KISS32Random 169 143 126 124 108
KISS64Random 128 124 100 131 120
LCG64ShiftRandom 234 168 19 244 185
MT19937_32Random 164 127 113 92 82
MT19937_64Random 148 120 107 148 120
XOR32ShiftRandom 206 160 144 135 120
XOR64ShiftRandom 189 156 143 207 166
L64X256MixRandom 162 136 121 166 142

License

The library is licensed under the Apache License, Version 2.0.

Copyright 2017-2021 Franz Wilhelmstötter

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Release notes

  • Make the random generators work seamlessly with the new Java 17 RandomGenerator API.

Improvements

  • #26: Convert Gradle build scripts from Groovy to Kotlin and prepare for Java 11.

Improvements

  • #21: Update Gradle version and add CI build for Java 11.

Bugs

Improvements

  • #3: Define stable module name. Set the Automatic-Module-Name to io.jenetics.prngine.