Usage

var iterawun = require( '@stdlib/simulate-iter-awun' );

iterawun( iterator, sigma[, options] )

Returns an iterator which introduces additive white uniform noise (AWUN) with standard deviation sigma.

var array2iterator = require( '@stdlib/array-to-iterator' );

var arr = array2iterator( [ 1.0, 1.0, 1.0, 1.0, 1.0 ] );
var it = iterawun( arr, 0.2 );

var v = it.next().value;
// returns <number>

v = it.next().value;
// returns <number>

// ...

The returned iterator protocol-compliant object has the following properties:

• next: function which returns an iterator protocol-compliant object containing the next iterated value (if one exists) assigned to a value property and a done property having a boolean value indicating whether the iterator is finished.
• return: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object.
• PRNG: underlying pseudorandom number generator (PRNG).
• seed: pseudorandom number generator seed. If provided a PRNG, the property value is null.
• seedLength: length of generator seed. If provided a PRNG, the property value is null.
• state: pseudorandom number generator state. If provided a PRNG, the property value is null.
• stateLength: length of generator state. If provided a PRNG, the property value is null.
• byteLength: size (in bytes) of generator state. If provided a PRNG, the property value is null.

The function accepts the following options:

• prng: pseudorandom number generator for generating uniformly distributed pseudorandom numbers on the interval [0,1). If provided, the function ignores both the state and seed options. In order to seed the returned iterator, one must seed the provided prng (assuming the provided prng is seedable).
• seed: pseudorandom number generator seed.
• state: a Uint32Array containing pseudorandom number generator state. If provided, the function ignores the seed option.
• copy: boolean indicating whether to copy a provided pseudorandom number generator state. Setting this option to false allows sharing state between two or more pseudorandom number generators. Setting this option to true ensures that a returned iterator has exclusive control over its internal state. Default: true.

By default, an iterator uses the MT19937 algorithm to generate uniformly distributed pseudorandom numbers on the interval [0,1). To use a different PRNG, set the prng option.

var array2iterator = require( '@stdlib/array-to-iterator' );
var minstd = require( '@stdlib/random-base-minstd-shuffle' );

var arr = array2iterator( [ 1.0, 1.0, 1.0, 1.0, 1.0 ] );
var it = iterawun( arr, 0.2, {
    'prng': minstd.normalized
});

var v = it.next().value;
// returns <number>

To seed an iterator, set the seed option.

var array2iterator = require( '@stdlib/array-to-iterator' );

var arr = array2iterator( [ 1.0, 1.0, 1.0, 1.0, 1.0 ] );
var it1 = iterawun( arr, 0.2, {
    'seed': 12345
});

var v1 = it1.next().value;
// returns <number>

var it2 = iterawun( arr, 0.2, {
    'seed': 12345
});

var v2 = it2.next().value;
// returns <number>

var bool = ( v1 === v2 );
// returns true

To return an iterator having a specific initial state, set the iterator state option.

var array2iterator = require( '@stdlib/array-to-iterator' );
var arr = array2iterator( [ 1.0, 1.0, 1.0, 1.0, 1.0 ] );

var it1 = iterawun( arr, 0.2 );

// Progress the underlying generator state:
var i;
for ( i = 0; i < 3; i++ ) {
    it1.next();
}

// Create a new iterator initialized to the current state of `it1`:
var it2 = iterawun( arr, 0.2, {
    'state': it1.state
});

// Test that the iterator values are the same:
var bool = ( it1.next().value === it2.next().value );
// returns true