@ohos-ports/stdlib-simulate 0.4.1-beta.0

package/iter/awln/lib/main.js

@@ -0,0 +1,299 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2019 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 setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
+var setReadOnlyAccessor = require( '@stdlib/utils/define-nonenumerable-read-only-accessor' );
+var setReadWriteAccessor = require( '@stdlib/utils/define-nonenumerable-read-write-accessor' );
+var isIteratorLike = require( '@stdlib/assert/is-iterator-like' );
+var isPositiveNumber = require( '@stdlib/assert/is-positive-number' ).isPrimitive;
+var isPlainObject = require( '@stdlib/assert/is-plain-object' );
+var isFunction = require( '@stdlib/assert/is-function' );
+var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive;
+var isUint32Array = require( '@stdlib/assert/is-uint32array' );
+var hasOwnProp = require( '@stdlib/assert/has-own-property' );
+var noop = require( '@stdlib/utils/noop' );
+var constantFunction = require( '@stdlib/utils/constant-function' );
+var iteratorSymbol = require( '@stdlib/symbol/iterator' );
+var laplace = require( '@stdlib/random/base/laplace' ).factory;
+var format = require( '@stdlib/string/format' );
+var SQRT_TWO = require( '@stdlib/constants/float64/sqrt-two' );
+var defaults = require( './defaults.js' );
+
+
+// MAIN //
+
+/**
+* Returns an iterator which introduces additive white Laplacian noise with standard deviation `sigma`.
+*
+* ## Method
+*
+* -   The variance of a Laplace (biexponential or double-exponential) distribution is given by
+*
+*     ```tex
+*     \operatorname{Var} = 2b^2
+*     ```
+*
+*     where \\( b \\) is the distribution scale parameter.
+*
+* -   Accordingly, the standard deviation is then
+*
+*     ```tex
+*     \sigma = b\sqrt{2}
+*     ```
+*
+* -   Solving for \\( b \\), we derive the parameter transform necessary for generating a Laplacian random variable with standard deviation \\( \sigma \\)
+*
+*     ```tex
+*     b = \frac{\sigma}{\sqrt{2}}
+*     ```
+*
+* @param {Iterator} iterator - input iterator
+* @param {PositiveNumber} sigma - standard deviation of the noise
+* @param {Options} [options] - function options
+* @param {PRNG} [options.prng] - pseudorandom number generator which generates uniformly distributed pseudorandom numbers on the interval `[0,1)`
+* @param {PRNGSeedMT19937} [options.seed] - pseudorandom number generator seed
+* @param {PRNGStateMT19937} [options.state] - pseudorandom number generator state
+* @param {boolean} [options.copy=true] - boolean indicating whether to copy a provided pseudorandom number generator state
+* @throws {TypeError} first argument must be an iterator
+* @throws {TypeError} second argument must be a positive number
+* @throws {TypeError} third argument must be an object
+* @throws {TypeError} must provide valid options
+* @throws {Error} must provide a valid state
+* @returns {Iterator} iterator
+*
+* @example
+* var iterSineWave = require( '@stdlib/simulate/iter/sine-wave' );
+*
+* var sine = iterSineWave({
+*     'iter': 100
+* });
+*
+* var it = iterawln( sine, 0.5 );
+*
+* var v = it.next().value;
+* // returns <number>
+*
+* v = it.next().value;
+* // returns <number>
+*
+* v = it.next().value;
+* // returns <number>
+*
+* // ...
+*/
+function iterawln( iterator, sigma, options ) {
+	var rlaplace;
+	var opts;
+	var iter;
+	var FLG;
+	if ( !isIteratorLike( iterator ) ) {
+		throw new TypeError( format( 'invalid argument. First argument must be an iterator. Value: `%s`.', iterator ) );
+	}
+	if ( !isPositiveNumber( sigma ) ) {
+		throw new TypeError( format( 'invalid argument. Second argument must be a positive number. Value: `%s`.', sigma ) );
+	}
+	opts = defaults();
+	if ( arguments.length > 2 ) {
+		if ( !isPlainObject( options ) ) {
+			throw new TypeError( format( 'invalid argument. Third argument must be an object. Value: `%s`.', options ) );
+		}
+		if ( hasOwnProp( options, 'copy' ) ) {
+			opts.copy = options.copy;
+			if ( !isBoolean( options.copy ) ) {
+				throw new TypeError( format( 'invalid option. `%s` option must be a boolean. Option: `%s`.', 'copy', options.copy ) );
+			}
+		}
+		if ( hasOwnProp( options, 'prng' ) ) {
+			if ( !isFunction( options.prng ) ) {
+				throw new TypeError( format( 'invalid option. `%s` option must be a pseudorandom number generator function. Option: `%s`.', 'prng', options.prng ) );
+			}
+			opts.prng = options.prng;
+		}
+		// If provided a PRNG, ignore the `state` option, as we don't support getting or setting PRNG state.
+		else if ( hasOwnProp( options, 'state' ) ) {
+			opts.state = options.state;
+			if ( !isUint32Array( options.state ) ) {
+				throw new TypeError( format( 'invalid option. `%s` option must be a Uint32Array. Option: `%s`.', 'state', options.state ) );
+			}
+		}
+		// If provided a PRNG, ignore the `seed` option, as a `seed`, by itself, is insufficient to guarantee reproducibility. If provided a state, ignore the `seed` option, as a PRNG state should contain seed information.
+		else if ( hasOwnProp( options, 'seed' ) ) {
+			opts.seed = options.seed;
+			if ( options.seed === void 0 ) {
+				throw new TypeError( format( 'invalid option. `%s` option must be either a positive integer less than or equal to the maximum unsigned 32-bit integer or an array-like object containing integer values less than or equal to the maximum unsigned 32-bit integer. Option: `%s`.', 'seed', options.seed ) );
+			}
+		}
+	}
+	rlaplace = laplace( 0.0, sigma/SQRT_TWO, opts );
+
+	// Create an iterator protocol-compliant object:
+	iter = {};
+	setReadOnly( iter, 'next', next );
+	setReadOnly( iter, 'return', end );
+
+	// If an environment supports `Symbol.iterator` and the provided iterator is iterable, make the iterator iterable:
+	if ( iteratorSymbol && isFunction( iterator[ iteratorSymbol ] ) ) {
+		setReadOnly( iter, iteratorSymbol, factory );
+	}
+	// If we are provided an "external" PRNG, we don't support getting or setting PRNG state, as we'd need to check for compatible state value types, etc, entailing considerable complexity.
+	if ( options && options.prng ) {
+		setReadOnly( iter, 'seed', null );
+		setReadOnly( iter, 'seedLength', null );
+		setReadWriteAccessor( iter, 'state', constantFunction( null ), noop );
+		setReadOnly( iter, 'stateLength', null );
+		setReadOnly( iter, 'byteLength', null );
+		setReadOnly( iter, 'PRNG', options.prng );
+	} else {
+		setReadOnlyAccessor( iter, 'seed', getSeed );
+		setReadOnlyAccessor( iter, 'seedLength', getSeedLength );
+		setReadWriteAccessor( iter, 'state', getState, setState );
+		setReadOnlyAccessor( iter, 'stateLength', getStateLength );
+		setReadOnlyAccessor( iter, 'byteLength', getStateSize );
+		setReadOnly( iter, 'PRNG', rlaplace.PRNG );
+	}
+	return iter;
+
+	/**
+	* Returns the PRNG seed.
+	*
+	* @private
+	* @returns {PRNGSeedMT19937} seed
+	*/
+	function getSeed() {
+		return rlaplace.seed;
+	}
+
+	/**
+	* Returns the PRNG seed length.
+	*
+	* @private
+	* @returns {PositiveInteger} seed length
+	*/
+	function getSeedLength() {
+		return rlaplace.seedLength;
+	}
+
+	/**
+	* Returns the PRNG state length.
+	*
+	* @private
+	* @returns {PositiveInteger} state length
+	*/
+	function getStateLength() {
+		return rlaplace.stateLength;
+	}
+
+	/**
+	* Returns the PRNG state size (in bytes).
+	*
+	* @private
+	* @returns {PositiveInteger} state size (in bytes)
+	*/
+	function getStateSize() {
+		return rlaplace.byteLength;
+	}
+
+	/**
+	* Returns the current PRNG state.
+	*
+	* @private
+	* @returns {PRNGStateMT19937} current state
+	*/
+	function getState() {
+		return rlaplace.state;
+	}
+
+	/**
+	* Sets the PRNG state.
+	*
+	* @private
+	* @param {PRNGStateMT19937} s - generator state
+	* @throws {Error} must provide a valid state
+	*/
+	function setState( s ) {
+		rlaplace.state = s;
+	}
+
+	/**
+	* Returns an iterator protocol-compliant object containing the next iterated value.
+	*
+	* @private
+	* @returns {Object} iterator protocol-compliant object
+	*/
+	function next() {
+		var v;
+		if ( FLG ) {
+			return {
+				'done': true
+			};
+		}
+		v = iterator.next();
+		if ( v.done ) {
+			FLG = true;
+			return v;
+		}
+		if ( typeof v.value === 'number' ) {
+			v = v.value + rlaplace();
+		} else {
+			v = NaN;
+		}
+		return {
+			'value': v,
+			'done': false
+		};
+	}
+
+	/**
+	* Finishes an iterator.
+	*
+	* @private
+	* @param {*} [value] - value to return
+	* @returns {Object} iterator protocol-compliant object
+	*/
+	function end( value ) {
+		FLG = true;
+		if ( arguments.length ) {
+			return {
+				'value': value,
+				'done': true
+			};
+		}
+		return {
+			'done': true
+		};
+	}
+
+	/**
+	* Returns a new iterator.
+	*
+	* @private
+	* @returns {Iterator} iterator
+	*/
+	function factory() {
+		return iterawln( iterator[ iteratorSymbol ](), sigma, opts );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = iterawln;

package/iter/awln/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@stdlib/simulate/iter/awln",
+  "version": "0.0.0",
+  "description": "Create an iterator which introduces additive white Laplacian noise.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "The Stdlib Authors",
+    "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+  },
+  "contributors": [
+    {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    }
+  ],
+  "main": "./lib",
+  "directories": {
+    "benchmark": "./benchmark",
+    "doc": "./docs",
+    "example": "./examples",
+    "lib": "./lib",
+    "test": "./test"
+  },
+  "types": "./docs/types",
+  "scripts": {},
+  "homepage": "https://github.com/stdlib-js/stdlib",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/stdlib.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=0.10.0",
+    "npm": ">2.7.0"
+  },
+  "os": [
+    "aix",
+    "darwin",
+    "freebsd",
+    "linux",
+    "macos",
+    "openbsd",
+    "sunos",
+    "win32",
+    "windows"
+  ],
+  "keywords": [
+    "stdlib",
+    "simulate",
+    "simulation",
+    "noise",
+    "additive",
+    "white",
+    "laplacian",
+    "laplace",
+    "biexponential",
+    "bi-exponential",
+    "double-exponential",
+    "exponential",
+    "information theory",
+    "random",
+    "iterator",
+    "iterable",
+    "iterate",
+    "iteration",
+    "iter"
+  ]
+}

package/iter/awun/README.md

@@ -0,0 +1,238 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2019 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.
+
+-->
+
+# iterawun
+
+> Create an [iterator][mdn-iterator-protocol] which introduces additive white uniform noise (AWUN).
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var iterawun = require( '@stdlib/simulate/iter/awun' );
+```
+
+#### iterawun( iterator, sigma\[, options] )
+
+Returns an [iterator][mdn-iterator-protocol] which introduces additive white uniform noise (AWUN) with standard deviation `sigma`.
+
+```javascript
+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`][@stdlib/array/uint32] 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][@stdlib/random/base/mt19937] algorithm to generate uniformly distributed pseudorandom numbers on the interval `[0,1)`. To use a different PRNG, set the `prng` option.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## Notes
+
+-   If PRNG state is "shared" (meaning a state array was provided during iterator creation and **not** copied) and one sets the iterator state to a state array having a different length, the iterator does **not** update the existing shared state and, instead, points to the newly provided state array. In order to synchronize generated output according to the new shared state array, the state array for **each** relevant PRNG/iterator must be **explicitly** set.
+-   If PRNG state is "shared" and one sets the iterator state to a state array of the same length, the PRNG state is updated (along with the state of all other PRNGs/iterators sharing the state array).
+-   If an iterated value is non-numeric (including `NaN`), the returned [`iterator`][mdn-iterator-protocol] returns `NaN`. If non-numeric iterated values are possible, you are advised to provide an [`iterator`][mdn-iterator-protocol] which type checks and handles non-numeric values accordingly.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var iterSineWave = require( '@stdlib/simulate/iter/sine-wave' );
+var iterawun = require( '@stdlib/simulate/iter/awun' );
+
+// Create an iterator for generating a sine wave:
+var sine = iterSineWave({
+    'iter': 100,
+    'amplitude': 10.0
+});
+
+// Create an iterator for introducing additive white uniform noise:
+var it = iterawun( sine, 3.0 );
+
+// Perform manual iteration...
+var v;
+while ( true ) {
+    v = it.next();
+    if ( v.done ) {
+        break;
+    }
+    console.log( v.value );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+* * *
+
+## See Also
+
+-   <span class="package-name">[`@stdlib/simulate/iter/awgn`][@stdlib/simulate/iter/awgn]</span><span class="delimiter">: </span><span class="description">create an iterator which introduces additive white Gaussian noise.</span>
+-   <span class="package-name">[`@stdlib/simulate/iter/awln`][@stdlib/simulate/iter/awln]</span><span class="delimiter">: </span><span class="description">create an iterator which introduces additive white Laplacian noise.</span>
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol
+
+[@stdlib/array/uint32]: https://www.npmjs.com/package/@stdlib/array-uint32
+
+[@stdlib/random/base/mt19937]: https://www.npmjs.com/package/@stdlib/random-base-mt19937
+
+<!-- <related-links> -->
+
+[@stdlib/simulate/iter/awgn]: https://github.com/stdlib-js/simulate/tree/main/iter/awgn
+
+[@stdlib/simulate/iter/awln]: https://github.com/stdlib-js/simulate/tree/main/iter/awln
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->

package/iter/awun/docs/repl.txt

@@ -0,0 +1,85 @@
+
+{{alias}}( iterator, sigma[, options] )
+    Returns an iterator which introduces additive white uniform noise (AWUN)
+    with standard deviation `sigma`.
+
+    If an environment supports Symbol.iterator and the provided iterator is
+    iterable, the returned iterator is iterable.
+
+    Parameters
+    ----------
+    iterator: Object
+        Input iterator.
+
+    sigma: number
+        Standard deviation of the noise.
+
+    options: Object (optional)
+        Options.
+
+    options.prng: Function (optional)
+        Pseudorandom number generator (PRNG) for generating uniformly
+        distributed pseudorandom numbers on the interval [0,1). If provided, the
+        `state` and `seed` options are ignored. In order to seed the returned
+        iterator, one must seed the provided `prng` (assuming the provided
+        `prng` is seedable).
+
+    options.seed: integer|ArrayLikeObject<integer> (optional)
+        Pseudorandom number generator seed. The seed may be either a positive
+        unsigned 32-bit integer or, for arbitrary length seeds, an array-like
+        object containing unsigned 32-bit integers.
+
+    options.state: Uint32Array (optional)
+        Pseudorandom number generator state. If provided, the `seed` option is
+        ignored.
+
+    options.copy: boolean (optional)
+        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.
+
+    Returns
+    -------
+    iterator: Object
+        Iterator.
+
+    iterator.next(): Function
+        Returns an iterator protocol-compliant object containing the next
+        iterated value (if one exists) and a boolean flag indicating whether the
+        iterator is finished.
+
+    iterator.return( [value] ): Function
+        Finishes an iterator and returns a provided value.
+
+    iterator.PRNG: Function
+        Underlying pseudorandom number generator.
+
+    iterator.seed: Uint32Array|null
+        Pseudorandom number generator seed.
+
+    iterator.seedLength: integer|null
+        Length of generator seed.
+
+    iterator.state: Uint32Array|null
+        Pseudorandom random number generator state.
+
+    iterator.stateLength: integer|null
+        Length of generator state.
+
+    iterator.byteLength: integer|null
+        Size (in bytes) of generator state.
+
+    Examples
+    --------
+    > var src = {{alias:@stdlib/simulate/iter/sine-wave}}();
+    > var it = {{alias}}( src, 0.5 );
+    > var v = it.next().value
+    <number>
+    > v = it.next().value
+    <number>
+
+    See Also
+    --------
+