107 lines
4.0 KiB
JavaScript
107 lines
4.0 KiB
JavaScript
/**
|
||
* @license Apache-2.0
|
||
*
|
||
* Copyright (c) 2018 The Stdlib Authors.
|
||
*
|
||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||
* you may not use this file except in compliance with the License.
|
||
* You may obtain a copy of the License at
|
||
*
|
||
* http://www.apache.org/licenses/LICENSE-2.0
|
||
*
|
||
* Unless required by applicable law or agreed to in writing, software
|
||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
* See the License for the specific language governing permissions and
|
||
* limitations under the License.
|
||
*/
|
||
|
||
'use strict';
|
||
|
||
// MODULES //
|
||
|
||
var factory = require( './factory.js' );
|
||
var randuint32 = require( './rand_uint32.js' );
|
||
|
||
|
||
// MAIN //
|
||
|
||
/**
|
||
* Generates a pseudorandom integer on the interval \\( [1,2^{32}-1) \\).
|
||
*
|
||
* ## Method
|
||
*
|
||
* - When generating normalized double-precision floating-point numbers, we first generate two pseudorandom integers \\( x \\) and \\( y \\) on the interval \\( [1,2^{32}-1) \\) for a combined \\( 64 \\) random bits.
|
||
*
|
||
* - We would like \\( 53 \\) random bits to generate a 53-bit precision integer and, thus, want to discard \\( 11 \\) of the generated bits.
|
||
*
|
||
* - We do so by discarding \\( 5 \\) bits from \\( x \\) and \\( 6 \\) bits from \\( y \\).
|
||
*
|
||
* - Accordingly, \\( x \\) contains \\( 27 \\) random bits, which are subsequently shifted left \\( 26 \\) bits (multiplied by \\( 2^{26} \\), and \\( y \\) contains \\( 26 \\) random bits to fill in the lower \\( 26 \\) bits. When summed, they combine to comprise \\( 53 \\) random bits of a double-precision floating-point integer.
|
||
*
|
||
* - As an example, suppose, for the sake of argument, the 32-bit PRNG generates the maximum unsigned 32-bit integer \\( 2^{32}-1 \\) twice in a row. Then,
|
||
*
|
||
* ```javascript
|
||
* x = 4294967295 >>> 5; // 00000111111111111111111111111111
|
||
* y = 4294967295 >>> 6; // 00000011111111111111111111111111
|
||
* ```
|
||
*
|
||
* Multiplying \\( x \\) by \\( 2^{26} \\) returns \\( 9007199187632128 \\), which, in binary, is
|
||
*
|
||
* ```binarystring
|
||
* 0 10000110011 11111111111111111111 11111100000000000000000000000000
|
||
* ```
|
||
*
|
||
* Adding \\( y \\) yields \\( 9007199254740991 \\) (the maximum "safe" double-precision floating-point integer value), which, in binary, is
|
||
*
|
||
* ```binarystring
|
||
* 0 10000110011 11111111111111111111 11111111111111111111111111111111
|
||
* ```
|
||
*
|
||
* - Similarly, suppose the 32-bit PRNG generates the following values
|
||
*
|
||
* ```javascript
|
||
* x = 1 >>> 5; // 0 => 00000000000000000000000000000000
|
||
* y = 64 >>> 6; // 1 => 00000000000000000000000000000001
|
||
* ```
|
||
*
|
||
* Multiplying \\( x \\) by \\( 2^{26} \\) returns \\( 0 \\), which, in binary, is
|
||
*
|
||
* ```binarystring
|
||
* 0 00000000000 00000000000000000000 00000000000000000000000000000000
|
||
* ```
|
||
*
|
||
* Adding \\( y \\) yields \\( 1 \\), which, in binary, is
|
||
*
|
||
* ```binarystring
|
||
* 0 01111111111 00000000000000000000 00000000000000000000000000000000
|
||
* ```
|
||
*
|
||
* - As different combinations of \\( x \\) and \\( y \\) are generated, different combinations of double-precision floating-point exponent and significand bits will be toggled, thus generating pseudorandom double-precision floating-point numbers.
|
||
*
|
||
*
|
||
* ## References
|
||
*
|
||
* - Matsumoto, Makoto, and Takuji Nishimura. 1998. "Mersenne Twister: A 623-dimensionally Equidistributed Uniform Pseudo-random Number Generator." _ACM Transactions on Modeling and Computer Simulation_ 8 (1). New York, NY, USA: ACM: 3–30. doi:[10.1145/272991.272995][@matsumoto:1998a].
|
||
* - Harase, Shin. 2017. "Conversion of Mersenne Twister to double-precision floating-point numbers." _ArXiv_ abs/1708.06018 (September). <https://arxiv.org/abs/1708.06018>.
|
||
*
|
||
* [@matsumoto:1998a]: https://doi.org/10.1145/272991.272995
|
||
*
|
||
*
|
||
* @function mt19937
|
||
* @type {PRNG}
|
||
* @returns {PositiveInteger} pseudorandom integer
|
||
*
|
||
* @example
|
||
* var v = mt19937();
|
||
* // returns <number>
|
||
*/
|
||
var mt19937 = factory({
|
||
'seed': randuint32()
|
||
});
|
||
|
||
|
||
// EXPORTS //
|
||
|
||
module.exports = mt19937;
|