• Home
• it.unimi.dsi
• dsiutils
• 2.3.3
• source code
• package-info.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

src.it.unimi.dsi.util.package-info Maven / Gradle / Ivy

/**
 * 
Miscellaneaous utility classes.
 * 
 * 
Pseudorandom number generators
 * 
 * 
We provide a number of fast, high-quality PRNGs with different features.
 * 

 * 
{@link it.unimi.dsi.util.XoRoShiRo128PlusRandom xoroshiro128+} is a fast, top-quality generator. 
 * It has strong statistical properties and it is the fastest generator we provide. Its period (2128 − 1) is sufficient 
 * for any application with a reasonable amount of parallelism. It is our suggestion for an all-purpose generator.
 * 
{@link it.unimi.dsi.util.XorShift128PlusRandom xorshift128+} is a fast, high-quality generator, but it has been superseded
 * by xoroshiro128+, which is better under every respect. It is presently used in the JavaScript engines of
 * Chrome,
 * Firefox and
 * Safari, and it is the
 * default generator in Erlang.
 * 
{@link it.unimi.dsi.util.SplitMix64Random SplitMix64} is a fast, top-quality generator, but it has a relatively short period (264) so it should
 * not be used to generate very long sequences (the rule of thumb to have a period greater than the square of the length of the sequence you want to generate).
 * It is a non-splittable version of Java 8's SplittableRandom,
 * and thus conceptually identical to Java 8's
 * ThreadLocalRandom (note that Java 7's version
 * was identical to {@link java.util.Random}, instead). We use it to initialize the state of all other generators starting from a 64-bit seed.
 * 
{@link it.unimi.dsi.util.XorShift1024StarRandom xorshift1024*} is fast, has good quality 
 * and provides a long period (21024 − 1) for massive parallel computations.
 * 
 * 
 * 
{@link it.unimi.dsi.util.XoRoShiRo128PlusRandom xoroshiro128+}, {@link it.unimi.dsi.util.XorShift128PlusRandom xorshift128+} and
 * {@link it.unimi.dsi.util.XorShift1024StarRandom xorshift1024*} provide
 * {@linkplain it.unimi.dsi.util.XoRoShiRo128PlusRandom#jump() jump functions} which make it possible to generate long non-overlapping sequences,
 * and {@linkplain it.unimi.dsi.util.XoRoShiRo128PlusRandom#split() split functions} in the spirit of {@link java.util.SplittableRandom SplittableRandom}.
 * 
 * 
A table summarizing timings is provided below. Note that we test several different method parameters to highlight
 * the different strategies used to generate numbers in a range, as the rejection-based algorithm used by all generators
 * can be based on integer or long inputs, and the results are quite different. For example, on modern, 64-bit CPUs Java's
 * strategy of applying rejection to 32-bit integers does not pay off (see the timings for nextInt(230 + 1)).
 * 
 * 
The timings are very different from previous versions, but they
 * should be more reliable, as they are now obtained by means of 
 * JMH microbenchmarks. The JMH timings were decreased by 1ns, as
 * using the low-level {@code perfasm} profiler the JMH overhead was estimated at ≈1ns per call.
 *  
 * 

 * 

 * 
{@link java.util.Random Random}
 * 
ThreadLocalRandom
 * 
SplittableRandom
 * 
{@link it.unimi.dsi.util.SplitMix64RandomGenerator SplitMix64}
 * 
{@link it.unimi.dsi.util.XoRoShiRo128PlusRandom xoroshiro128+}
 * 
{@link it.unimi.dsi.util.XorShift128PlusRandom xorshift128+}
 * 
{@link it.unimi.dsi.util.XorShift1024StarRandom xorshift1024*}
 * 
 * 
nextInt()	
8.272
1.860
1.999
1.896
1.936
2.007
3.127
 * 
nextLong()	
17.549
1.886
2.123
2.054
1.994
2.012
3.106
 * 
nextDouble()	
17.542
2.686
3.068
3.004
2.597
2.740
3.835
 * 
nextInt(100000)	
8.285
3.163
3.769
3.713
3.070
3.264
4.753
 * 
nextInt(229+228)	
12.634
7.939
8.574
4.130
3.347
3.586
5.152
 * 
nextInt(230)	
8.269
1.886
2.148
2.226
1.978
2.580
3.229
 * 
nextInt(230 + 1)	
22.152
15.645
16.483
3.837
3.244
3.528
5.004
 * 
nextInt(230 + 229)	
12.581
7.923
8.578
4.092
3.344
3.572
5.138
 * 
nextLong(1000000000000)	
3.482
4.060
3.923
3.304
3.604
5.064
 * 
nextLong(262 + 1)	
16.090
16.864
16.811
13.805
14.878
18.197   
 *
 * 
 * 
 * 
The quality of all generators we provide is very high: for instance, they perform better than WELL1024a 
 * or MT19937 (AKA the Mersenne Twister) in the TestU01 BigCrush test suite.
 * More details can be found on the xoroshiro+/xorshift*/xorshift+ generators and the PRNG shootout page.
 * 
 * 
For each generator, we provide a version that extends {@link java.util.Random}, overriding (as usual) the {@link java.util.Random#next(int) next(int)} method. Nonetheless,
 * since the generators are all inherently 64-bit also {@link java.util.Random#nextInt() nextInt()}, {@link java.util.Random#nextFloat() nextFloat()},
 * {@link java.util.Random#nextLong() nextLong()}, {@link java.util.Random#nextDouble() nextDouble()}, {@link java.util.Random#nextBoolean() nextBoolean()}
 * and {@link java.util.Random#nextBytes(byte[]) nextBytes(byte[])} have been overridden for speed (preserving, of course, {@link java.util.Random}'s semantics).
 * In particular, {@link java.util.Random#nextDouble() nextDouble()} and {@link java.util.Random#nextFloat() nextFloat()} 
 * use a multiplication-free conversion.
 * 
 * 
If you do not need an instance of {@link java.util.Random}, or if you need a {@link org.apache.commons.math3.random.RandomGenerator} to use
 * with Commons Math, there is for each generator a corresponding {@link org.apache.commons.math3.random.RandomGenerator RandomGenerator}
 * implementation, which indeed we suggest to use in general if you do not need a generator implementing {@link java.util.Random}. 
 */

package it.unimi.dsi.util;