use Random.PCGRandom;


import Random.PCGRandom;


the ‘PCGRandom’ module is unstable and may be removed in the future

Permuted Linear Congruential Random Number Generator.

This module provides PCG random number generation routines. See http://www.pcg-random.org/ and the paper, PCG: A Family of Simple Fast Space-Efficient Statistically Good Algorithms for Random Number Generation by M.E. O’Neill.

It also includes some Chapel-specific features, such as generating real, imag, and complex numbers; and generating numbers in a range in parallel. These features are not available in the reference implementations of PCG.

The related module PCGRandomLib provides a lower-level interface to many PCG functions.


The interface provided by this module is expected to change.

type PCGRandomStream = PCGRandomStreamInternal(?)


‘PCGRandomStream’ is deprecated; please use randomStream instead

Models a stream of pseudorandom numbers generated by the PCG random number generator. See http://www.pcg-random.org/ and the paper, PCG: A Family of Simple Fast Space-Efficient Statistically Good Algorithms for Random Number Generation by M.E. O’Neill.

This class builds upon the pcg_setseq_64_xsh_rr_32_rng PCG RNG which has 64 bits of state and 32 bits of output.

While the PCG RNG used here is believed to have good statistical properties, it is not suitable for generating key material for encryption since the output of this RNG may be predictable. Additionally, if statistical properties of the random numbers are very important, another strategy may be required.

We have good confidence that the random numbers generated by this class match the C PCG reference implementation and have specifically verified equal output given the same seed. However, this implementation differs from the C PCG reference implementation in how it produces random integers within particular bounds (with PCGRandomStream.getNext using min and max arguments). In addition, this implementation directly supports the generation of random real values, unlike the C PCG implementation.

Smaller numbers, such as uint(8) or uint(16), are generated from the high-order bits of the 32-bit output.

To generate larger numbers, several 32-bit-output RNGs are ganged together. This strategy is recommended by the author of PCG (and demonstrated in the file pcg32x2-demo.c. Each of these 32-bit RNGs has a different sequence constant and so will be independent and uncorrelated. For example, to generate 128-bit complex numbers, this RNG will use 4 ganged 32-bit PCG RNGs with different sequence constants. One impact of this approach is that this implementation will only generate 2**64 different complex numbers with a given seed (for example).

This class also supports generating integers within particular bounds. When that is required, this class uses a strategy different from the PCG reference implementation in order to work better in a parallel setting. In particular, when more than 1 random value is required as part of generating a value in a range, conceptually it uses more ganged-together RNGs (as with the 32x2 strategy). Each new value beyond the first that is computed will be computed with a different ganged-together RNG. This strategy is meant to avoid statistical bias. While we have tested this strategy to our satisfaction, it has not been subject to rigorous analysis and may have undesirable statistical properties.

When generating a real, imaginary, or complex number, this implementation uses the strategy of generating a 64-bit unsigned integer and then multiplying it by 2.0**-64 in order to convert it to a floating point number. While this does construct a uniform distribution on rounded floating point values, it leaves out many possible real values (for example, 2**-128). We believe that this strategy has reasonable statistical properties. One side effect of this strategy is that the real number 1.0 can be generated because of rounding. The real number 0.0 can be generated because PCG can produce the value 0 as a random integer.

We have tested this implementation with TestU01 (available at http://simul.iro.umontreal.ca/testu01/tu01.html ). We measured our implementation with TestU01 1.2.3 and the Crush suite, which consists of 144 statistical tests. The results were:

  • no failures for generating uniform reals

  • 1 failure for generating 32-bit values (which is also true for the reference version of PCG with the same configuration)

  • 0 failures for generating 64-bit values (which we provided to TestU01 as 2 different 32-bit values since it only accepts 32 bits at a time)

  • 0 failures for generating bounded integers (which we provided to TestU01 by requesting values in [0..,2**31+2**30+1) until we had two values < 2**31, removing the top 0 bit, and then combining the top 16 bits into the value provided to TestU01).

proc randlc(type resultType, ref states)