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

package/iter/awgn/README.md

@@ -0,0 +1,240 @@
+<!--
+
+@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.
+
+-->
+
+# iterawgn
+
+> Create an [iterator][mdn-iterator-protocol] which introduces [additive white Gaussian noise][awgn] (AWGN).
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var iterawgn = require( '@stdlib/simulate/iter/awgn' );
+```
+
+#### iterawgn( iterator, sigma\[, options] )
+
+Returns an [iterator][mdn-iterator-protocol] which introduces [additive white Gaussian noise][awgn] (AWGN) 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 = iterawgn( 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). If provided a PRNG, the property value is `null`.
+-   **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 pseudorandom numbers drawn from a standard normal distribution. 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 [improved ziggurat][@stdlib/random/base/improved-ziggurat] algorithm to generate pseudorandom numbers drawn from a standard normal distribution. To use a different PRNG, set the `prng` option.
+
+```javascript
+var array2iterator = require( '@stdlib/array/to-iterator' );
+var boxMuller = require( '@stdlib/random/base/box-muller' );
+
+var arr = array2iterator( [ 1.0, 1.0, 1.0, 1.0, 1.0 ] );
+var it = iterawgn( arr, 0.2, {
+    'prng': boxMuller
+});
+
+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 = iterawgn( arr, 0.2, {
+    'seed': 12345
+});
+
+var v1 = it1.next().value;
+// returns <number>
+
+var it2 = iterawgn( 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 = iterawgn( 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 = iterawgn( 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 iterawgn = require( '@stdlib/simulate/iter/awgn' );
+
+// Create an iterator for generating a sine wave:
+var sine = iterSineWave({
+    'iter': 100,
+    'amplitude': 10.0
+});
+
+// Create an iterator for introducing additive white Gaussian noise:
+var it = iterawgn( 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/awln`][@stdlib/simulate/iter/awln]</span><span class="delimiter">: </span><span class="description">create an iterator which introduces additive white Laplacian noise.</span>
+-   <span class="package-name">[`@stdlib/simulate/iter/awun`][@stdlib/simulate/iter/awun]</span><span class="delimiter">: </span><span class="description">create an iterator which introduces additive white uniform 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
+
+[awgn]: https://en.wikipedia.org/wiki/Additive_white_Gaussian_noise
+
+[@stdlib/array/uint32]: https://www.npmjs.com/package/@stdlib/array-uint32
+
+[@stdlib/random/base/improved-ziggurat]: https://www.npmjs.com/package/@stdlib/random-base-improved-ziggurat
+
+<!-- <related-links> -->
+
+[@stdlib/simulate/iter/awln]: https://github.com/stdlib-js/simulate/tree/main/iter/awln
+
+[@stdlib/simulate/iter/awun]: https://github.com/stdlib-js/simulate/tree/main/iter/awun
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->

package/iter/awgn/docs/repl.txt

@@ -0,0 +1,85 @@
+
+{{alias}}( iterator, sigma[, options] )
+    Returns an iterator which introduces additive white Gaussian noise (AWGN)
+    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 pseudorandom numbers
+        drawn from a standard normal distribution. 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|null
+        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
+    --------
+

package/iter/awgn/docs/types/index.d.ts

@@ -0,0 +1,155 @@
+/*
+* @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.
+*/
+
+// TypeScript Version: 4.1
+
+/// <reference types="@stdlib/types"/>
+
+import { Iterator as Iter, IterableIterator } from '@stdlib/types/iter';
+import * as random from '@stdlib/types/random';
+
+// Define a union type representing both iterable and non-iterable iterators:
+type Iterator = Iter | IterableIterator;
+
+/**
+* Interface defining function options.
+*/
+interface Options {
+	/**
+	* Pseudorandom number generator which generates pseudorandom numbers drawn from a standard normal distribution.
+	*
+	* ## Notes
+	*
+	* -   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).
+	*/
+	prng?: random.PRNG;
+
+	/**
+	* Pseudorandom number generator state.
+	*
+	* ## Notes
+	*
+	* -   If provided, the `seed` option is ignored.
+	*/
+	state?: random.PRNGStateMT19937;
+
+	/**
+	* Pseudorandom number generator seed.
+	*/
+	seed?: random.PRNGSeedMT19937;
+
+	/**
+	* Specifies whether to copy a provided pseudorandom number generator state.
+	*
+	* ## Notes
+	*
+	* -   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.
+	*/
+	copy?: boolean;
+}
+
+/**
+* Interface defining a returned iterator.
+*/
+interface ExtendedIter extends Iter {
+	/**
+	* Underlying PRNG.
+	*/
+	readonly PRNG: random.PRNG | null;
+
+	/**
+	* PRNG seed.
+	*/
+	readonly seed: random.PRNGSeedMT19937 | null;
+
+	/**
+	* PRNG seed length.
+	*/
+	readonly seedLength: number | null;
+
+	/**
+	* PRNG state.
+	*/
+	state: random.PRNGStateMT19937 | null;
+
+	/**
+	* PRNG state length.
+	*/
+	readonly stateLength: number | null;
+
+	/**
+	* PRNG state size (in bytes).
+	*/
+	readonly byteLength: number | null;
+}
+
+/**
+* Interface defining a returned iterable iterator.
+*/
+interface ExtendedIterableIterator extends ExtendedIter {
+	/**
+	* Returns a new iterable iterator.
+	*
+	* @returns iterable iterator
+	*/
+	[Symbol.iterator](): IterableIterator;
+}
+
+// Define a union type representing both iterable and non-iterable returned iterators:
+type ExtendedIterator = ExtendedIter | ExtendedIterableIterator;
+
+/**
+* Returns an iterator which introduces additive white Gaussian noise with standard deviation `sigma`.
+*
+* @param iterator - input iterator
+* @param sigma - standard deviation of the noise
+* @param options - function options
+* @param options.prng - pseudorandom number generator for generating pseudorandom numbers drawn from a standard normal distribution
+* @param options.state - pseudorandom number generator state
+* @param options.seed - pseudorandom number generator seed
+* @param options.copy - boolean indicating whether to copy a provided pseudorandom number generator state (default: true)
+* @throws `sigma` must be a positive number
+* @throws must provide a valid state
+* @returns iterator
+*
+* @example
+* var iterSineWave = require( '@stdlib/simulate/iter/sine-wave' );
+*
+* var sine = iterSineWave({
+*     'iter': 100
+* });
+*
+* var it = iterawgn( sine, 0.5 );
+*
+* var v = it.next().value;
+* // returns <number>
+*
+* v = it.next().value;
+* // returns <number>
+*
+* v = it.next().value;
+* // returns <number>
+*
+* // ...
+*/
+declare function iterawgn( iterator: Iterator, sigma: number, options?: Options ): ExtendedIterator;
+
+
+// EXPORTS //
+
+export = iterawgn;

package/iter/awgn/docs/types/test.ts

@@ -0,0 +1,150 @@
+/*
+* @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.
+*/
+
+import iterawgn = require( './index' );
+
+/**
+* Returns an iterator protocol-compliant object.
+*
+* @returns iterator protocol-compliant object
+*/
+function iterator() {
+	return {
+		'next': next
+	};
+
+	/**
+	* Implements the iterator protocol `next` method.
+	*
+	* @returns iterator protocol-compliant object
+	*/
+	function next() {
+		return {
+			'value': true,
+			'done': false
+		};
+	}
+}
+
+
+// TESTS //
+
+// The function returns an iterator...
+{
+	iterawgn( iterator(), 0.2 ); // $ExpectType ExtendedIterator
+	iterawgn( iterator(), 0.2, {} ); // $ExpectType ExtendedIterator
+	iterawgn( iterator(), 0.2, { 'seed': 12345 } ); // $ExpectType ExtendedIterator
+}
+
+// The compiler throws an error if the function is provided a first argument which is not an iterator protocol-compliant object...
+{
+	iterawgn( '5', 1.0 ); // $ExpectError
+	iterawgn( 5, 1.0 ); // $ExpectError
+	iterawgn( true, 1.0 ); // $ExpectError
+	iterawgn( false, 1.0 ); // $ExpectError
+	iterawgn( null, 1.0 ); // $ExpectError
+	iterawgn( undefined, 1.0 ); // $ExpectError
+	iterawgn( [], 1.0 ); // $ExpectError
+	iterawgn( {}, 1.0 ); // $ExpectError
+	iterawgn( ( x: number ): number => x, 1.0 ); // $ExpectError
+
+	iterawgn( '5', 1.0, {} ); // $ExpectError
+	iterawgn( 5, 1.0, {} ); // $ExpectError
+	iterawgn( true, 1.0, {} ); // $ExpectError
+	iterawgn( false, 1.0, {} ); // $ExpectError
+	iterawgn( null, 1.0, {} ); // $ExpectError
+	iterawgn( undefined, 1.0, {} ); // $ExpectError
+	iterawgn( [], 1.0, {} ); // $ExpectError
+	iterawgn( {}, 1.0, {} ); // $ExpectError
+	iterawgn( ( x: number ): number => x, 1.0, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument which is not a number...
+{
+	iterawgn( iterator(), '5' ); // $ExpectError
+	iterawgn( iterator(), true ); // $ExpectError
+	iterawgn( iterator(), false ); // $ExpectError
+	iterawgn( iterator(), null ); // $ExpectError
+	iterawgn( iterator(), undefined ); // $ExpectError
+	iterawgn( iterator(), [] ); // $ExpectError
+	iterawgn( iterator(), {} ); // $ExpectError
+	iterawgn( iterator(), ( x: number ): number => x ); // $ExpectError
+
+	iterawgn( iterator(), '5', {} ); // $ExpectError
+	iterawgn( iterator(), true, {} ); // $ExpectError
+	iterawgn( iterator(), false, {} ); // $ExpectError
+	iterawgn( iterator(), null, {} ); // $ExpectError
+	iterawgn( iterator(), undefined, {} ); // $ExpectError
+	iterawgn( iterator(), [], {} ); // $ExpectError
+	iterawgn( iterator(), {}, {} ); // $ExpectError
+	iterawgn( iterator(), ( x: number ): number => x, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument which is not an object...
+{
+	iterawgn( iterator(), 1.0, null ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `seed` option...
+{
+	iterawgn( iterator(), 1.0, { 'seed': '5' } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'seed': true } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'seed': false } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'seed': null } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'seed': {} } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'seed': ( x: number ): number => x } ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `prng` option...
+{
+	iterawgn( iterator(), 1.0, { 'prng': '5' } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'prng': 5 } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'prng': true } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'prng': false } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'prng': null } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'prng': [] } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'prng': {} } ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `state` option...
+{
+	iterawgn( iterator(), 1.0, { 'state': '5' } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'state': 5 } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'state': true } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'state': false } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'state': null } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'state': [] } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'state': {} } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'state': ( x: number ): number => x } ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `copy` option...
+{
+	iterawgn( iterator(), 1.0, { 'copy': '5' } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'copy': 5 } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'copy': null } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'copy': [] } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'copy': {} } ); // $ExpectError
+	iterawgn( iterator(), 1.0, { 'copy': ( x: number ): number => x } ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided insufficient arguments...
+{
+	iterawgn(); // $ExpectError
+	iterawgn( iterator() ); // $ExpectError
+}

package/iter/awgn/lib/defaults.js

@@ -0,0 +1,38 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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';
+
+// MAIN //
+
+/**
+* Returns default options.
+*
+* @private
+* @returns {Object} default options
+*/
+function defaults() {
+	return {
+		'copy': true
+	};
+}
+
+
+// EXPORTS //
+
+module.exports = defaults;