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

package/iter/square-wave/lib/index.js

@@ -0,0 +1,54 @@
+/**
+* @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';
+
+/**
+* Create an iterator which generates a square wave.
+*
+* @module @stdlib/simulate/iter/square-wave
+*
+* @example
+* var iterSquareWave = require( '@stdlib/simulate/iter/square-wave' );
+*
+* var opts = {
+*     'period': 4
+* };
+*
+* var iter = iterSquareWave( opts );
+*
+* var v = iter.next().value;
+* // returns 1.0
+*
+* v = iter.next().value;
+* // returns 1.0
+*
+* v = iter.next().value;
+* // returns -1.0
+*
+* // ...
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;

package/iter/square-wave/lib/main.js

@@ -0,0 +1,156 @@
+/**
+* @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 iteratorSymbol = require( '@stdlib/symbol/iterator' );
+var validate = require( './validate.js' );
+
+
+// MAIN //
+
+/**
+* Returns an iterator which generates a square wave.
+*
+* @param {Options} [options] - function options
+* @param {PositiveInteger} [options.period=10] - number of iterations before a square wave repeats (this must be a positive even integer)
+* @param {number} [options.min=-1.0] - minimum amplitude
+* @param {number} [options.max=1.0] - maximum amplitude
+* @param {integer} [options.offset=0] - phase offset (in units of iterations; zero-based)
+* @param {NonNegativeInteger} [options.iter=1e308] - number of iterations
+* @throws {TypeError} options argument must be an object
+* @throws {TypeError} must provide valid options
+* @returns {Iterator} iterator
+*
+* @example
+* var opts = {
+*     'period': 4
+* };
+*
+* var iter = iterSquareWave( opts );
+*
+* var v = iter.next().value;
+* // returns 1.0
+*
+* v = iter.next().value;
+* // returns 1.0
+*
+* v = iter.next().value;
+* // returns -1.0
+*
+* // ...
+*/
+function iterSquareWave( options ) {
+	var opts;
+	var iter;
+	var FLG;
+	var err;
+	var t;
+	var h;
+	var i;
+
+	opts = {
+		'period': 10,
+		'min': -1.0,
+		'max': 1.0,
+		'offset': 0,
+		'iter': 1e308
+	};
+	if ( arguments.length ) {
+		err = validate( opts, options );
+		if ( err ) {
+			throw err;
+		}
+	}
+	t = ( opts.period-opts.offset ) % opts.period;
+	if ( t < 0 ) {
+		t += opts.period;
+	}
+	t -= 1;
+	h = opts.period / 2;
+	i = 0;
+
+	// Create an iterator protocol-compliant object:
+	iter = {};
+	setReadOnly( iter, 'next', next );
+	setReadOnly( iter, 'return', end );
+
+	// If an environment supports `Symbol.iterator`, make the iterator iterable:
+	if ( iteratorSymbol ) {
+		setReadOnly( iter, iteratorSymbol, factory );
+	}
+	return iter;
+
+	/**
+	* Returns an iterator protocol-compliant object containing the next iterated value.
+	*
+	* @private
+	* @returns {Object} iterator protocol-compliant object
+	*/
+	function next() {
+		i += 1;
+		if ( FLG || i > opts.iter ) {
+			return {
+				'done': true
+			};
+		}
+		t += 1;
+		return {
+			'value': ( (t%opts.period) < h ) ? opts.max : opts.min,
+			'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 iterSquareWave( opts );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = iterSquareWave;

package/iter/square-wave/lib/validate.js

@@ -0,0 +1,99 @@
+/**
+* @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 isPlainObject = require( '@stdlib/assert/is-plain-object' );
+var hasOwnProp = require( '@stdlib/assert/has-own-property' );
+var isNumber = require( '@stdlib/assert/is-number' ).isPrimitive;
+var isInteger = require( '@stdlib/assert/is-integer' ).isPrimitive;
+var isPositiveInteger = require( '@stdlib/assert/is-positive-integer' ).isPrimitive;
+var isNonNegativeInteger = require( '@stdlib/assert/is-nonnegative-integer' ).isPrimitive;
+var isEven = require( '@stdlib/math/base/assert/is-even' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var format = require( '@stdlib/string/format' );
+
+
+// MAIN //
+
+/**
+* Validates function options.
+*
+* @private
+* @param {Object} opts - destination object
+* @param {Options} options - function options
+* @param {PositiveInteger} [options.period] - number of iterations before a square wave repeats
+* @param {number} [options.min] - minimum amplitude
+* @param {number} [options.max] - maximum amplitude
+* @param {integer} [options.offset] - phase offset (in units of iterations)
+* @param {NonNegativeInteger} [options.iter] - number of iterations
+* @returns {(Error|null)} null or an error object
+*
+* @example
+* var opts = {};
+* var options = {
+*     'iter': 100
+* };
+* var err = validate( opts, options );
+* if ( err ) {
+*     throw err;
+* }
+*/
+function validate( opts, options ) {
+	if ( !isPlainObject( options ) ) {
+		return new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
+	}
+	if ( hasOwnProp( options, 'period' ) ) {
+		opts.period = options.period;
+		if ( !isPositiveInteger( options.period ) || !isEven( options.period ) ) { // eslint-disable-line max-len
+			return new TypeError( format( 'invalid option. `%s` option must be an positive even integer. Option: `%s`.', 'period', options.period ) );
+		}
+	}
+	if ( hasOwnProp( options, 'min' ) ) {
+		opts.min = options.min;
+		if ( !isNumber( options.min ) || isnan( options.min ) ) {
+			return new TypeError( format( 'invalid option. `%s` option must be a number. Option: `%s`.', 'min', options.min ) );
+		}
+	}
+	if ( hasOwnProp( options, 'max' ) ) {
+		opts.max = options.max;
+		if ( !isNumber( options.max ) || isnan( options.max ) ) {
+			return new TypeError( format( 'invalid option. `%s` option must be a number. Option: `%s`.', 'max', options.max ) );
+		}
+	}
+	if ( hasOwnProp( options, 'offset' ) ) {
+		opts.offset = options.offset;
+		if ( !isInteger( options.offset ) ) {
+			return new TypeError( format( 'invalid option. `%s` option must be an integer. Option: `%s`.', 'offset', options.offset ) );
+		}
+	}
+	if ( hasOwnProp( options, 'iter' ) ) {
+		opts.iter = options.iter;
+		if ( !isNonNegativeInteger( options.iter ) ) {
+			return new TypeError( format( 'invalid option. `%s` option must be a nonnegative integer. Option: `%s`.', 'iter', options.iter ) );
+		}
+	}
+	return null;
+}
+
+
+// EXPORTS //
+
+module.exports = validate;

package/iter/square-wave/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@stdlib/simulate/iter/square-wave",
+  "version": "0.0.0",
+  "description": "Create an iterator which generates a square wave.",
+  "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",
+    "square",
+    "pulse",
+    "wave",
+    "signal",
+    "processing",
+    "waveform",
+    "periodic",
+    "iterator",
+    "iterate",
+    "iteration",
+    "iter"
+  ]
+}

package/iter/triangle-wave/README.md

@@ -0,0 +1,289 @@
+<!--
+
+@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.
+
+-->
+
+# iterTriangleWave
+
+> Create an iterator which generates a triangle wave.
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+A triangle waveform is represented by the following equation
+
+<!-- <equation class="equation" label="eq:triangle_waveform" align="center" raw="f(t; \tau, a, \varphi) = \frac{2a}{\pi} \operatorname{arcsin} \sin \frac{2\pi(t-\varphi)}{\tau}" alt="Equation for a triangle waveform."> -->
+
+<div class="equation" align="center" data-raw-text="f(t; \tau, a, \varphi) = \frac{2a}{\pi} \operatorname{arcsin} \sin \frac{2\pi(t-\varphi)}{\tau}" data-equation="eq:triangle_waveform">
+    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@5827c258000edcb03496265cdfd372d686b4c656/lib/node_modules/@stdlib/simulate/iter/triangle-wave/docs/img/equation_triangle_waveform.svg" alt="Equation for a triangle waveform.">
+    <br>
+</div>
+
+<!-- </equation> -->
+
+where `τ` is the period, `a` is the peak amplitude, and `φ` is the phase offset.
+
+<!-- TODO: add a figure showing a triangle wave -->
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var iterTriangleWave = require( '@stdlib/simulate/iter/triangle-wave' );
+```
+
+#### iterTriangleWave( \[options] )
+
+Returns an iterator which generates a triangle wave.
+
+```javascript
+var it = iterTriangleWave();
+// returns <Object>
+
+var v = it.next().value;
+// returns <number>
+
+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.
+
+The function supports the following `options`:
+
+-   **period**: period (i.e., the number of iterations before a waveform repeats). Default: `10`.
+-   **amplitude**: peak amplitude. Default: `1.0`.
+-   **offset**: phase offset (in units of iterations; zero-based). A negative offset translates a waveform to the left. A positive offset translates a waveform to the right. Default: `0`.
+-   **iter**: number of iterations. Default: `1e308`.
+
+By default, the function returns an iterator which generates a triangle wave that repeats every `10` iterations. To specify an alternative period, set the `period` option.
+
+```javascript
+var opts = {
+    'period': 4
+};
+
+var it = iterTriangleWave( opts );
+// returns <Object>
+
+var v = it.next().value;
+// returns 0.0
+
+v = it.next().value;
+// returns 1.0
+
+v = it.next().value;
+// returns 0.0
+
+v = it.next().value;
+// returns -1.0
+
+v = it.next().value;
+// returns 0.0
+
+// ...
+```
+
+To adjust at what point the iterator begins in the waveform cycle, set the phase `offset` option. For example, to translate the waveform to the left,
+
+```javascript
+var opts = {
+    'period': 4,
+    'offset': -1
+};
+
+var it = iterTriangleWave( opts );
+// returns <Object>
+
+var v = it.next().value;
+// returns 1.0
+
+v = it.next().value;
+// returns 0.0
+
+v = it.next().value;
+// returns -1.0
+
+v = it.next().value;
+// returns 0.0
+
+v = it.next().value;
+// returns 1.0
+
+// ...
+```
+
+To translate the waveform to the right,
+
+```javascript
+var opts = {
+    'period': 4,
+    'offset': 1
+};
+
+var it = iterTriangleWave( opts );
+// returns <Object>
+
+var v = it.next().value;
+// returns -1.0
+
+v = it.next().value;
+// returns 0.0
+
+v = it.next().value;
+// returns 1.0
+
+v = it.next().value;
+// returns 0.0
+
+v = it.next().value;
+// returns -1.0
+
+// ...
+```
+
+By default, the function returns an infinite iterator (i.e., an iterator which never ends). To limit the number of iterations, set the `iter` option.
+
+```javascript
+var opts = {
+    'iter': 2
+};
+var it = iterTriangleWave( opts );
+// returns <Object>
+
+var v = it.next().value;
+// returns <number>
+
+v = it.next().value;
+// returns <number>
+
+var bool = it.next().done;
+// 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 an environment supports `Symbol.iterator`, the returned iterator is iterable.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var iterTriangleWave = require( '@stdlib/simulate/iter/triangle-wave' );
+
+// Create an iterator:
+var opts = {
+    'period': 10,
+    'amplitude': 10.0,
+    'offset': -5,
+    'iter': 100
+};
+var it = iterTriangleWave( opts );
+
+// 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/pulse`][@stdlib/simulate/iter/pulse]</span><span class="delimiter">: </span><span class="description">create an iterator which generates a pulse waveform.</span>
+-   <span class="package-name">[`@stdlib/simulate/iter/sawtooth-wave`][@stdlib/simulate/iter/sawtooth-wave]</span><span class="delimiter">: </span><span class="description">create an iterator which generates a sawtooth wave.</span>
+-   <span class="package-name">[`@stdlib/simulate/iter/sine-wave`][@stdlib/simulate/iter/sine-wave]</span><span class="delimiter">: </span><span class="description">create an iterator which generates a sine wave.</span>
+-   <span class="package-name">[`@stdlib/simulate/iter/square-wave`][@stdlib/simulate/iter/square-wave]</span><span class="delimiter">: </span><span class="description">create an iterator which generates a square wave.</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">
+
+<!-- <related-links> -->
+
+[@stdlib/simulate/iter/pulse]: https://github.com/stdlib-js/simulate/tree/main/iter/pulse
+
+[@stdlib/simulate/iter/sawtooth-wave]: https://github.com/stdlib-js/simulate/tree/main/iter/sawtooth-wave
+
+[@stdlib/simulate/iter/sine-wave]: https://github.com/stdlib-js/simulate/tree/main/iter/sine-wave
+
+[@stdlib/simulate/iter/square-wave]: https://github.com/stdlib-js/simulate/tree/main/iter/square-wave
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->