# CorrNoise User's Manual

CorrNoise provides a number of pseudo-random number generators.

To install CorrNoise, start Julia and type the following command:

`Pkg.clone("https://github.com/lspestrip/CorrNoise")`

To run the test suite, type the following command:

`Pkg.test("CorrNoise")`

## Documentation

The documentation was built using Documenter.jl.

`Documentation built 2020-04-20T15:16:58.014 with Julia 1.4.0.`

## Random number generators

Although Julia already implements a number of pseudo-random number generators, CorrNoise implements its own generators. We employ the same algorithms used in the pipeline of the ESA Planck/LFI instrument, which provided several types of distributions:

- Uniform distribution (
`Flat128RNG`

), with period 2^128; - Gaussian distribution (
`GaussRNG`

); - \[1/f^2\]distribution (
`Oof2RNG`

); - \[1/f^α\]distribution, with $α < 2$ (
`OofRNG`

).

Each generator but `Flat128RNG`

uses a simpler generator internally. This generator must sample from a given distribution, but it does not need to be a generator provided by CorrNoise. For instance, the Gaussian generator `GaussRNG`

employs an uniform generator, which can either be `Flat128RNG`

or one of the generators provided by Julia like `MersenneTwister`

. For instance, here is an example which shows how to use `Flat128RNG`

:

```
julia> gauss1 = GaussRNG(initflatrng128(1234))
GaussRNG(Flat128RNG(UInt32[0x5bf4963e, 0x7f2bb362, 0x8dfeefd3, 0xef95f09a]), true, 0)
julia> print([randn(gauss1) for i in 1:4])
[-0.6359311782923003, -0.8817164374135789, -0.08693562418260461, -0.4032569270742411]
```

We use `initflatrng128`

, as it creates a Flat128RNG object with some sensible defaults (specifically, it is configured to produce the same sequence of random numbers as the ones produced by the Planck/HFI pipeline, if the seeds are the same). And here is the same example, using a `MersenneTwister`

generator:

```
julia> gauss2 = GaussRNG(MersenneTwister(1234))
ERROR: UndefVarError: MersenneTwister not defined
julia> print([randn(gauss2) for i in 1:4])
ERROR: UndefVarError: gauss2 not defined
```

Of course, the numbers are different. They are however drawn from the same distribution (Gaussian curve with mean 0 and σ=1).

### Uniform generator

`CorrNoise.Flat128RNG`

— Type.`Flat128RNG`

State of the base-128 uniform random generator. Initialize this using the function `initflatrng128`

.

`CorrNoise.initflatrng128`

— Function.`initflatrng128(xstart = 123456789, ystart = 362436069, zstart = 521288629, wstart = 88675123)`

Initialize a flat random number generator with period 2^128. To draw random numbers, use the `Base.rand`

function as usual.

Example:

```
rng = initflatrng128()
print([rand(rng) for i in 1:4])
```

### Gaussian generator

`CorrNoise.GaussRNG`

— Type.```
GaussRNG(flatrng::AbstractRNG)
GaussRNG(seed=0)
```

Initialize a Gaussian RNG. The parameter `flatrng`

must be a uniform RNG. If a `seed`

is used, then a `MersenneTwister`

RNG is used.

### $1/f^2$ generator

`CorrNoise.Oof2RNG`

— Type.`Oof2RNG(normrng, fmin, fknee, fsample)`

Create a `Oof2RNG`

RNG object. It requires a gaussian RNG generator in `normrng`

(use `GaussRNG`

), the minimum frequency (longest period) in `fmin`

, the knee frequency and the sampling frequency. The measure unit of the three frequencies must be the same (e.g., Hz).

Use `randoof2`

to draw samples from a `Oof2RNG`

object, as in the following example:

```
rng = Oof2RNG(GaussRNG(), 1e-3, 1.0, 1e2)
print([randoof2(rng) for i in 1:4])
```

### $1/f^α$ generator (with $α < 2$)

`CorrNoise.OofRNG`

— Type.`OofRNG(normrng, slope, fmin, fknee, fsample)`

Create a `OofRNG`

RNG object. It requires a gaussian RNG generator in `normrng`

(use `GaussRNG`

), the slope α of the noise in `slope`

, the minimum frequency (longest period) in `fmin`

, the knee frequency and the sampling frequency. The measure unit of the three frequencies must be the same (e.g., Hz).

Use `randoof`

to draw samples from a `OofRNG`

object, as in the following example:

```
rng = OofRNG(GaussRNG(), -1.5, 1e-3, 1.0, 1e2)
print([randoof(rng) for i in 1:4])
```