6.2.3.4 Generating random numbers ¶

As discussed above, to generate noise we need to make random samples of a particular distribution. So it is important to understand some general concepts regarding the generation of random numbers. For a very complete and nice introduction we strongly advise reading Donald Knuth’s “The art of computer programming”, volume 2, chapter 3¹⁵⁵. Quoting from the GNU Scientific Library manual, “If you do not own it, you should stop reading right now, run to the nearest bookstore, and buy it”¹⁵⁶!

Using only software, we can only produce what is called a psuedo-random sequence of numbers. A true random number generator is a hardware (let’s assume we have made sure it has no systematic biases), for example, throwing dice or flipping coins (which have remained from the ancient times). More modern hardware methods use atmospheric noise, thermal noise or other types of external electromagnetic or quantum phenomena. All pseudo-random number generators (software) require a seed to be the basis of the generation. The advantage of having a seed is that if you specify the same seed for multiple runs, you will get an identical sequence of random numbers which allows you to reproduce the same final noised image.

The programs in GNU Astronomy Utilities (for example, MakeNoise or MakeProfiles) use the GNU Scientific Library (GSL) to generate random numbers. GSL allows the user to set the random number generator through environment variables, see Installation directory for an introduction to environment variables. In the chapter titled “Random Number Generation” they have fully explained the various random number generators that are available (there are a lot of them!). Through the two environment variables GSL_RNG_TYPE and GSL_RNG_SEED you can specify the generator and its seed respectively.

If you do not specify a value for GSL_RNG_TYPE, GSL will use its default random number generator type. The default type is sufficient for most general applications. If no value is given for the GSL_RNG_SEED environment variable and you have asked Gnuastro to read the seed from the environment (through the --envseed option), then GSL will use the default value of each generator to give identical outputs. If you do not explicitly tell Gnuastro programs to read the seed value from the environment variable, then they will use the system time (accurate to within a microsecond) to generate (apparently random) seeds. In this manner, every time you run the program, you will get a different random number distribution.

There are two ways you can specify values for these environment variables. You can call them on the same command-line for example:

$ GSL_RNG_TYPE="taus" GSL_RNG_SEED=345 astarithmetic input.fits \
                                                     mknoise-sigma \
                                                     --envseed

In this manner the values will only be used for this particular execution of Arithmetic. However, it makes your code hard to read! Alternatively, you can define them for the full period of your terminal session or script, using the shell’s export command with the two separate commands below (for a script remove the $ signs):

$ export GSL_RNG_TYPE="taus"
$ export GSL_RNG_SEED=345

The subsequent programs which use GSL’s random number generators will hence forth use these values in this session of the terminal you are running or while executing this script. In case you want to set fixed values for these parameters every time you use the GSL random number generator, you can add these two lines to your .bashrc startup script¹⁵⁷, see Installation directory.

IMPORTANT NOTE: If the two environment variables GSL_RNG_TYPE and GSL_RNG_SEED are defined, GSL will report them by default, even if you do not use the --envseed option. For example, see this call to MakeProfiles:

$ export GSL_RNG_TYPE=taus
$ export GSL_RNG_SEED=345
$ astmkprof -s1 --kernel=gaussian,2,5
GSL_RNG_TYPE=taus
GSL_RNG_SEED=345
MakeProfiles V.VV started on DDD MMM DDD HH:MM:SS YYYY
  - Building one gaussian kernel
  - Random number generator (RNG) type: taus
  - Basic RNG seed: 1618960836
  ---- ./kernel.fits created.
  -- Output: ./kernel.fits
MakeProfiles finished in 0.068945 seconds

The first two output lines (showing the names and values of the GSL environment variables) are printed by GSL before MakeProfiles actually starts generating random numbers. Gnuastro’s programs will report the actual values they use independently (after the name of the program), you should check them for the final values used, not GSL’s printed values. In the example above, did you notice how the random number generator seed above is different between GSL and MakeProfiles? However, if --envseed was given, both printed seeds would be the same.