From 44ebf88b152ee5e046b5ba89d9015379ffa2e33c Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 14 Jul 2023 19:23:54 +0000 Subject: [PATCH] Auto-generated commit --- base/special/cphase/README.md | 128 ++++++++-- base/special/cphase/benchmark/benchmark.js | 15 +- .../cphase/benchmark/benchmark.native.js | 65 +++++ .../cphase/benchmark/c/native/Makefile | 146 +++++++++++ .../cphase/benchmark/c/native/benchmark.c | 143 +++++++++++ base/special/cphase/binding.gyp | 170 +++++++++++++ base/special/cphase/docs/repl.txt | 14 +- base/special/cphase/docs/types/index.d.ts | 15 +- base/special/cphase/docs/types/test.ts | 33 +-- base/special/cphase/examples/c/Makefile | 146 +++++++++++ base/special/cphase/examples/c/example.c | 43 ++++ base/special/cphase/examples/index.js | 13 +- base/special/cphase/include.gypi | 53 ++++ .../include/stdlib/math/base/special/cphase.h | 40 +++ base/special/cphase/lib/index.js | 5 +- base/special/cphase/lib/main.js | 15 +- base/special/cphase/lib/native.js | 47 ++++ base/special/cphase/manifest.json | 76 ++++++ base/special/cphase/package.json | 3 +- base/special/cphase/src/Makefile | 70 ++++++ base/special/cphase/src/addon.c | 23 ++ base/special/cphase/src/main.c | 45 ++++ base/special/cphase/test/test.js | 101 ++++---- base/special/cphase/test/test.native.js | 231 ++++++++++++++++++ base/special/cpolar/lib/cpolar.js | 7 +- base/special/cpolar/test/test.js | 8 +- 26 files changed, 1525 insertions(+), 130 deletions(-) create mode 100644 base/special/cphase/benchmark/benchmark.native.js create mode 100644 base/special/cphase/benchmark/c/native/Makefile create mode 100644 base/special/cphase/benchmark/c/native/benchmark.c create mode 100644 base/special/cphase/binding.gyp create mode 100644 base/special/cphase/examples/c/Makefile create mode 100644 base/special/cphase/examples/c/example.c create mode 100644 base/special/cphase/include.gypi create mode 100644 base/special/cphase/include/stdlib/math/base/special/cphase.h create mode 100644 base/special/cphase/lib/native.js create mode 100644 base/special/cphase/manifest.json create mode 100644 base/special/cphase/src/Makefile create mode 100644 base/special/cphase/src/addon.c create mode 100644 base/special/cphase/src/main.c create mode 100644 base/special/cphase/test/test.native.js diff --git a/base/special/cphase/README.md b/base/special/cphase/README.md index 0b93f1b30..a64269cb5 100644 --- a/base/special/cphase/README.md +++ b/base/special/cphase/README.md @@ -20,7 +20,7 @@ limitations under the License. # cphase -> Compute the [argument][complex-number-argument] of a complex number in radians. +> Compute the [argument][complex-number-argument] of a double-precision complex floating-point number in radians.
@@ -38,12 +38,14 @@ The [argument][complex-number-argument] of a complex number, also known as the * var cphase = require( '@stdlib/math/base/special/cphase' ); ``` -#### cphase( re, im ) +#### cphase( z ) -Computes the [argument][complex-number-argument] of a `complex` number comprised of a **real** component `re` and an **imaginary** component `im`. +Computes the [argument][complex-number-argument] of a double-precision complex floating-point number. ```javascript -var phi = cphase( 5.0, 3.0 ); +var Complex128 = require( '@stdlib/complex/float64' ); + +var phi = cphase( new Complex128( 5.0, 3.0 ) ); // returns ~0.5404 ``` @@ -59,22 +61,116 @@ var phi = cphase( 5.0, 3.0 ); ```javascript var Complex128 = require( '@stdlib/complex/float64' ); -var randu = require( '@stdlib/random/base/randu' ); -var round = require( '@stdlib/math/base/special/round' ); -var real = require( '@stdlib/complex/real' ); -var imag = require( '@stdlib/complex/imag' ); +var uniform = require( '@stdlib/random/base/uniform' ); var cphase = require( '@stdlib/math/base/special/cphase' ); -var re; -var im; var z; var i; for ( i = 0; i < 100; i++ ) { - re = round( randu()*100.0 ) - 50.0; - im = round( randu()*100.0 ) - 50.0; - z = new Complex128( re, im ); - console.log( 'arg(%s) = %d', z.toString(), cphase( real(z), imag(z) ) ); + z = new Complex128( uniform( -500.0, 500.0 ), uniform( -500.0, 500.0 ) ); + console.log( 'arg(%s) = %d', z.toString(), cphase( z ) ); +} +``` + +
+ + + + + +* * * + +
+ +## C APIs + + + +
+ +
+ + + + + +
+ +### Usage + +```c +#include "stdlib/math/base/special/cphase.h" +``` + +#### stdlib_base_cphase( z ) + +Computes the [argument][complex-number-argument] of a double-precision complex floating-point number. + +```c +#include "stdlib/complex/float64.h" +#include "stdlib/complex/real.h" +#include "stdlib/complex/imag.h" + +stdlib_complex128_t z = stdlib_complex128( 5.0, 3.0 ); +double out = stdlib_base_cphase( z ); +// returns ~0.5404 +``` + +The function accepts the following arguments: + +- **z**: `[in] stdlib_complex128_t` input value. + +```c +double stdlib_base_cphase( const stdlib_complex128_t z ); +``` + +
+ + + + + +
+ +
+ + + + + +
+ +### Examples + +```c +#include "stdlib/math/base/special/cphase.h" +#include "stdlib/complex/float64.h" +#include "stdlib/complex/reim.h" +#include + +int main( void ) { + const stdlib_complex128_t x[] = { + stdlib_complex128( 3.14, 1.5 ), + stdlib_complex128( -3.14, -1.5 ), + stdlib_complex128( 0.0, 0.0 ), + stdlib_complex128( 0.0/0.0, 0.0/0.0 ) + }; + + stdlib_complex128_t v; + stdlib_complex128_t y; + double re1; + double im1; + double re2; + double im2; + int i; + for ( i = 0; i < 4; i++ ) { + v = x[ i ]; + y = stdlib_base_cphase( v ); + stdlib_reim( v, &re1, &im1 ); + stdlib_reim( y, &re2, &im2 ); + printf( "cphase(%lf + %lfi) = %lf\n", re, im, y ); + } } ``` @@ -82,6 +178,10 @@ for ( i = 0; i < 100; i++ ) { +
+ + +
diff --git a/base/special/cphase/benchmark/benchmark.js b/base/special/cphase/benchmark/benchmark.js index c51c61eaf..859c7f1dd 100644 --- a/base/special/cphase/benchmark/benchmark.js +++ b/base/special/cphase/benchmark/benchmark.js @@ -21,7 +21,8 @@ // MODULES // var bench = require( '@stdlib/bench' ); -var randu = require( '@stdlib/random/base/randu' ); +var uniform = require( '@stdlib/random/base/uniform' ); +var Complex128 = require( '@stdlib/complex/float64' ); var isnan = require( './../../../../base/assert/is-nan' ); var pkg = require( './../package.json' ).name; var cphase = require( './../lib' ); @@ -30,16 +31,18 @@ var cphase = require( './../lib' ); // MAIN // bench( pkg, function benchmark( b ) { - var re; - var im; + var values; var y; var i; + values = [ + new Complex128( uniform( -500.0, 500.0 ), uniform( -500.0, 500.0 ) ), + new Complex128( uniform( -500.0, 500.0 ), uniform( -500.0, 500.0 ) ) + ]; + b.tic(); for ( i = 0; i < b.iterations; i++ ) { - re = ( randu()*1000.0 ) - 500.0; - im = ( randu()*1000.0 ) - 500.0; - y = cphase( re, im ); + y = cphase( values[ i%values.length ] ); if ( isnan( y ) ) { b.fail( 'should not return NaN' ); } diff --git a/base/special/cphase/benchmark/benchmark.native.js b/base/special/cphase/benchmark/benchmark.native.js new file mode 100644 index 000000000..2c31b690a --- /dev/null +++ b/base/special/cphase/benchmark/benchmark.native.js @@ -0,0 +1,65 @@ +/** +* @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'; + +// MODULES // + +var resolve = require( 'path' ).resolve; +var bench = require( '@stdlib/bench' ); +var uniform = require( '@stdlib/random/base/uniform' ); +var isnan = require( './../../../../base/assert/is-nan' ); +var Complex128 = require( '@stdlib/complex/float64' ); +var tryRequire = require( '@stdlib/utils/try-require' ); +var pkg = require( './../package.json' ).name; + + +// VARIABLES // + +var cphase = tryRequire( resolve( __dirname, './../lib/native.js' ) ); +var opts = { + 'skip': ( cphase instanceof Error ) +}; + + +// MAIN // + +bench( pkg+'::native', opts, function benchmark( b ) { + var values; + var y; + var i; + + values = [ + new Complex128( uniform( -500.0, 500.0 ), uniform( -500.0, 500.0 ) ), + new Complex128( uniform( -500.0, 500.0 ), uniform( -500.0, 500.0 ) ) + ]; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + y = cphase( values[ i%values.length ] ); + if ( isnan( y ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( isnan( y ) ) { + b.fail( 'should not return NaN' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/base/special/cphase/benchmark/c/native/Makefile b/base/special/cphase/benchmark/c/native/Makefile new file mode 100644 index 000000000..3cbfe3fef --- /dev/null +++ b/base/special/cphase/benchmark/c/native/Makefile @@ -0,0 +1,146 @@ +#/ +# @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. +#/ + +# VARIABLES # + +ifndef VERBOSE + QUIET := @ +else + QUIET := +endif + +# Determine the OS ([1][1], [2][2]). +# +# [1]: https://en.wikipedia.org/wiki/Uname#Examples +# [2]: http://stackoverflow.com/a/27776822/2225624 +OS ?= $(shell uname) +ifneq (, $(findstring MINGW,$(OS))) + OS := WINNT +else +ifneq (, $(findstring MSYS,$(OS))) + OS := WINNT +else +ifneq (, $(findstring CYGWIN,$(OS))) + OS := WINNT +else +ifneq (, $(findstring Windows_NT,$(OS))) + OS := WINNT +endif +endif +endif +endif + +# Define the program used for compiling C source files: +ifdef C_COMPILER + CC := $(C_COMPILER) +else + CC := gcc +endif + +# Define the command-line options when compiling C files: +CFLAGS ?= \ + -std=c99 \ + -O3 \ + -Wall \ + -pedantic + +# Determine whether to generate position independent code ([1][1], [2][2]). +# +# [1]: https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options +# [2]: http://stackoverflow.com/questions/5311515/gcc-fpic-option +ifeq ($(OS), WINNT) + fPIC ?= +else + fPIC ?= -fPIC +endif + +# List of includes (e.g., `-I /foo/bar -I /beep/boop/include`): +INCLUDE ?= + +# List of source files: +SOURCE_FILES ?= + +# List of libraries (e.g., `-lopenblas -lpthread`): +LIBRARIES ?= + +# List of library paths (e.g., `-L /foo/bar -L /beep/boop`): +LIBPATH ?= + +# List of C targets: +c_targets := benchmark.out + + +# RULES # + +#/ +# Compiles source files. +# +# @param {string} [C_COMPILER] - C compiler (e.g., `gcc`) +# @param {string} [CFLAGS] - C compiler options +# @param {(string|void)} [fPIC] - compiler flag determining whether to generate position independent code (e.g., `-fPIC`) +# @param {string} [INCLUDE] - list of includes (e.g., `-I /foo/bar -I /beep/boop/include`) +# @param {string} [SOURCE_FILES] - list of source files +# @param {string} [LIBPATH] - list of library paths (e.g., `-L /foo/bar -L /beep/boop`) +# @param {string} [LIBRARIES] - list of libraries (e.g., `-lopenblas -lpthread`) +# +# @example +# make +# +# @example +# make all +#/ +all: $(c_targets) + +.PHONY: all + +#/ +# Compiles C source files. +# +# @private +# @param {string} CC - C compiler (e.g., `gcc`) +# @param {string} CFLAGS - C compiler options +# @param {(string|void)} fPIC - compiler flag determining whether to generate position independent code (e.g., `-fPIC`) +# @param {string} INCLUDE - list of includes (e.g., `-I /foo/bar`) +# @param {string} SOURCE_FILES - list of source files +# @param {string} LIBPATH - list of library paths (e.g., `-L /foo/bar`) +# @param {string} LIBRARIES - list of libraries (e.g., `-lopenblas`) +#/ +$(c_targets): %.out: %.c + $(QUIET) $(CC) $(CFLAGS) $(fPIC) $(INCLUDE) -o $@ $(SOURCE_FILES) $< $(LIBPATH) -lm $(LIBRARIES) + +#/ +# Runs compiled benchmarks. +# +# @example +# make run +#/ +run: $(c_targets) + $(QUIET) ./$< + +.PHONY: run + +#/ +# Removes generated files. +# +# @example +# make clean +#/ +clean: + $(QUIET) -rm -f *.o *.out + +.PHONY: clean diff --git a/base/special/cphase/benchmark/c/native/benchmark.c b/base/special/cphase/benchmark/c/native/benchmark.c new file mode 100644 index 000000000..e053f36a7 --- /dev/null +++ b/base/special/cphase/benchmark/c/native/benchmark.c @@ -0,0 +1,143 @@ +/** +* @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. +*/ + +/** +* Benchmark `cphase`. +*/ +#include "stdlib/math/base/special/cphase.h" +#include "stdlib/complex/float64.h" +#include "stdlib/complex/reim.h" +#include +#include +#include +#include +#include + +#define NAME "cphase" +#define ITERATIONS 1000000 +#define REPEATS 3 + +/** +* Prints the TAP version. +*/ +void print_version() { + printf( "TAP version 13\n" ); +} + +/** +* Prints the TAP summary. +* +* @param total total number of tests +* @param passing total number of passing tests +*/ +void print_summary( int total, int passing ) { + printf( "#\n" ); + printf( "1..%d\n", total ); // TAP plan + printf( "# total %d\n", total ); + printf( "# pass %d\n", passing ); + printf( "#\n" ); + printf( "# ok\n" ); +} + +/** +* Prints benchmarks results. +* +* @param elapsed elapsed time in seconds +*/ +void print_results( double elapsed ) { + double rate = (double)ITERATIONS / elapsed; + printf( " ---\n" ); + printf( " iterations: %d\n", ITERATIONS ); + printf( " elapsed: %0.9f\n", elapsed ); + printf( " rate: %0.9f\n", rate ); + printf( " ...\n" ); +} + +/** +* Returns a clock time. +* +* @return clock time +*/ +double tic() { + struct timeval now; + gettimeofday( &now, NULL ); + return (double)now.tv_sec + (double)now.tv_usec/1.0e6; +} + +/** +* Generates a random number on the interval [0,1]. +* +* @return random number +*/ +double rand_double() { + int r = rand(); + return (double)r / ( (double)RAND_MAX + 1.0 ); +} + +/** +* Runs a benchmark. +* +* @return elapsed time in seconds +*/ +double benchmark() { + double elapsed; + double re; + double im; + double y; + double t; + int i; + + stdlib_complex128_t z; + + t = tic(); + for ( i = 0; i < ITERATIONS; i++ ) { + re = ( 1000.0*rand_double() ) - 500.0; + im = ( 1000.0*rand_double() ) - 500.0; + z = stdlib_complex128( re, im ); + y = stdlib_base_cphase( z ); + if ( y != y ) { + printf( "should not return NaN\n" ); + break; + } + } + elapsed = tic() - t; + if ( y != y ) { + printf( "should not return NaN\n" ); + } + return elapsed; +} + +/** +* Main execution sequence. +*/ +int main( void ) { + double elapsed; + int i; + + // Use the current time to seed the random number generator: + srand( time( NULL ) ); + + print_version(); + for ( i = 0; i < REPEATS; i++ ) { + printf( "# c::native::%s\n", NAME ); + elapsed = benchmark(); + print_results( elapsed ); + printf( "ok %d benchmark finished\n", i+1 ); + } + print_summary( REPEATS, REPEATS ); +} diff --git a/base/special/cphase/binding.gyp b/base/special/cphase/binding.gyp new file mode 100644 index 000000000..f2b466aef --- /dev/null +++ b/base/special/cphase/binding.gyp @@ -0,0 +1,170 @@ +# @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. + +# A `.gyp` file for building a Node.js native add-on. +# +# [1]: https://gyp.gsrc.io/docs/InputFormatReference.md +# [2]: https://gyp.gsrc.io/docs/UserDocumentation.md +{ + # List of files to include in this file: + 'includes': [ + './include.gypi', + ], + + # Define variables to be used throughout the configuration for all targets: + 'variables': { + # Target name should match the add-on export name: + 'addon_target_name%': 'addon', + + # Set variables based on the host OS: + 'conditions': [ + [ + 'OS=="win"', + { + # Define the object file suffix: + 'obj': 'obj', + }, + { + # Define the object file suffix: + 'obj': 'o', + } + ], # end condition (OS=="win") + ], # end conditions + }, # end variables + + # Define compile targets: + 'targets': [ + + # Target to generate an add-on: + { + # The target name should match the add-on export name: + 'target_name': '<(addon_target_name)', + + # Define dependencies: + 'dependencies': [], + + # Define directories which contain relevant include headers: + 'include_dirs': [ + # Local include directory: + '<@(include_dirs)', + ], + + # List of source files: + 'sources': [ + '<@(src_files)', + ], + + # Settings which should be applied when a target's object files are used as linker input: + 'link_settings': { + # Define libraries: + 'libraries': [ + '<@(libraries)', + ], + + # Define library directories: + 'library_dirs': [ + '<@(library_dirs)', + ], + }, + + # C/C++ compiler flags: + 'cflags': [ + # Enable commonly used warning options: + '-Wall', + + # Aggressive optimization: + '-O3', + ], + + # C specific compiler flags: + 'cflags_c': [ + # Specify the C standard to which a program is expected to conform: + '-std=c99', + ], + + # C++ specific compiler flags: + 'cflags_cpp': [ + # Specify the C++ standard to which a program is expected to conform: + '-std=c++11', + ], + + # Linker flags: + 'ldflags': [], + + # Apply conditions based on the host OS: + 'conditions': [ + [ + 'OS=="mac"', + { + # Linker flags: + 'ldflags': [ + '-undefined dynamic_lookup', + '-Wl,-no-pie', + '-Wl,-search_paths_first', + ], + }, + ], # end condition (OS=="mac") + [ + 'OS!="win"', + { + # C/C++ flags: + 'cflags': [ + # Generate platform-independent code: + '-fPIC', + ], + }, + ], # end condition (OS!="win") + ], # end conditions + }, # end target <(addon_target_name) + + # Target to copy a generated add-on to a standard location: + { + 'target_name': 'copy_addon', + + # Declare that the output of this target is not linked: + 'type': 'none', + + # Define dependencies: + 'dependencies': [ + # Require that the add-on be generated before building this target: + '<(addon_target_name)', + ], + + # Define a list of actions: + 'actions': [ + { + 'action_name': 'copy_addon', + 'message': 'Copying addon...', + + # Explicitly list the inputs in the command-line invocation below: + 'inputs': [], + + # Declare the expected outputs: + 'outputs': [ + '<(addon_output_dir)/<(addon_target_name).node', + ], + + # Define the command-line invocation: + 'action': [ + 'cp', + '<(PRODUCT_DIR)/<(addon_target_name).node', + '<(addon_output_dir)/<(addon_target_name).node', + ], + }, + ], # end actions + }, # end target copy_addon + ], # end targets +} diff --git a/base/special/cphase/docs/repl.txt b/base/special/cphase/docs/repl.txt index 6349990ee..dc62445be 100644 --- a/base/special/cphase/docs/repl.txt +++ b/base/special/cphase/docs/repl.txt @@ -1,6 +1,7 @@ -{{alias}}( re, im ) - Computes the argument of a complex number in radians. +{{alias}}( z ) + Computes the argument of a double-precision complex floating-point number + in radians. The argument of a complex number, also known as the phase, is the angle of the radius extending from the origin to the complex number plotted in the @@ -8,11 +9,8 @@ Parameters ---------- - re: number - Real component. - - im: number - Imaginary component. + z: Complex128 + Complex number. Returns ------- @@ -21,7 +19,7 @@ Examples -------- - > var phi = {{alias}}( 5.0, 3.0 ) + > var phi = {{alias}}( new {{alias:@stdlib/complex/float64}}( 5.0, 3.0 ) ) ~0.5404 See Also diff --git a/base/special/cphase/docs/types/index.d.ts b/base/special/cphase/docs/types/index.d.ts index 400507fa5..8dfe3ee86 100644 --- a/base/special/cphase/docs/types/index.d.ts +++ b/base/special/cphase/docs/types/index.d.ts @@ -18,22 +18,27 @@ // TypeScript Version: 2.0 +/// + +import { Complex128 } from '@stdlib/types/object'; + /** -* Computes the argument of a complex number in radians. +* Computes the argument of a double-precision complex floating-point number in radians. * * ## Notes * * - The argument of a complex number, also known as the phase, is the angle of the radius extending from the origin to the complex number plotted in the complex plane and the positive real axis. * -* @param re - real component -* @param im - imaginary component +* @param z - complex number * @returns argument * * @example -* var phi = cphase( 5.0, 3.0 ); +* var Complex128 = require( `@stdlib/complex/float64` ); +* +* var phi = cphase( new Complex128( 5.0, 3.0 ) ); * // returns ~0.5404 */ -declare function cphase( re: number, im: number ): number; +declare function cphase( z: Complex128 ): number; // EXPORTS // diff --git a/base/special/cphase/docs/types/test.ts b/base/special/cphase/docs/types/test.ts index c3ff46035..f2d66a698 100644 --- a/base/special/cphase/docs/types/test.ts +++ b/base/special/cphase/docs/types/test.ts @@ -16,6 +16,7 @@ * limitations under the License. */ +import Complex128 = require( '@stdlib/complex/float64' ); import cphase = require( './index' ); @@ -23,31 +24,19 @@ import cphase = require( './index' ); // The function returns a number... { - cphase( 5, 3 ); // $ExpectType number + cphase( new Complex128( 5.0, 3.0 ) ); // $ExpectType number } -// The compiler throws an error if the function is provided a first argument which is not a number... +// The compiler throws an error if the function is not provided a complex number... { - cphase( true, 3 ); // $ExpectError - cphase( false, 3 ); // $ExpectError - cphase( null, 3 ); // $ExpectError - cphase( undefined, 3 ); // $ExpectError - cphase( '5', 3 ); // $ExpectError - cphase( [], 3 ); // $ExpectError - cphase( {}, 3 ); // $ExpectError - cphase( ( x: number ): number => x, 3 ); // $ExpectError -} - -// The compiler throws an error if the function is provided a second argument which is not a number... -{ - cphase( 5, true ); // $ExpectError - cphase( 5, false ); // $ExpectError - cphase( 5, null ); // $ExpectError - cphase( 5, undefined ); // $ExpectError - cphase( 5, '5' ); // $ExpectError - cphase( 5, [] ); // $ExpectError - cphase( 5, {} ); // $ExpectError - cphase( 5, ( x: number ): number => x ); // $ExpectError + cphase( true ); // $ExpectError + cphase( false ); // $ExpectError + cphase( null ); // $ExpectError + cphase( undefined ); // $ExpectError + cphase( '5' ); // $ExpectError + cphase( [] ); // $ExpectError + cphase( {} ); // $ExpectError + cphase( ( x: number ): number => x ); // $ExpectError } // The compiler throws an error if the function is provided insufficient arguments... diff --git a/base/special/cphase/examples/c/Makefile b/base/special/cphase/examples/c/Makefile new file mode 100644 index 000000000..f0ae66fec --- /dev/null +++ b/base/special/cphase/examples/c/Makefile @@ -0,0 +1,146 @@ +#/ +# @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. +#/ + +# VARIABLES # + +ifndef VERBOSE + QUIET := @ +else + QUIET := +endif + +# Determine the OS ([1][1], [2][2]). +# +# [1]: https://en.wikipedia.org/wiki/Uname#Examples +# [2]: http://stackoverflow.com/a/27776822/2225624 +OS ?= $(shell uname) +ifneq (, $(findstring MINGW,$(OS))) + OS := WINNT +else +ifneq (, $(findstring MSYS,$(OS))) + OS := WINNT +else +ifneq (, $(findstring CYGWIN,$(OS))) + OS := WINNT +else +ifneq (, $(findstring Windows_NT,$(OS))) + OS := WINNT +endif +endif +endif +endif + +# Define the program used for compiling C source files: +ifdef C_COMPILER + CC := $(C_COMPILER) +else + CC := gcc +endif + +# Define the command-line options when compiling C files: +CFLAGS ?= \ + -std=c99 \ + -O3 \ + -Wall \ + -pedantic + +# Determine whether to generate position independent code ([1][1], [2][2]). +# +# [1]: https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options +# [2]: http://stackoverflow.com/questions/5311515/gcc-fpic-option +ifeq ($(OS), WINNT) + fPIC ?= +else + fPIC ?= -fPIC +endif + +# List of includes (e.g., `-I /foo/bar -I /beep/boop/include`): +INCLUDE ?= + +# List of source files: +SOURCE_FILES ?= + +# List of libraries (e.g., `-lopenblas -lpthread`): +LIBRARIES ?= + +# List of library paths (e.g., `-L /foo/bar -L /beep/boop`): +LIBPATH ?= + +# List of C targets: +c_targets := example.out + + +# RULES # + +#/ +# Compiles source files. +# +# @param {string} [C_COMPILER] - C compiler (e.g., `gcc`) +# @param {string} [CFLAGS] - C compiler options +# @param {(string|void)} [fPIC] - compiler flag determining whether to generate position independent code (e.g., `-fPIC`) +# @param {string} [INCLUDE] - list of includes (e.g., `-I /foo/bar -I /beep/boop/include`) +# @param {string} [SOURCE_FILES] - list of source files +# @param {string} [LIBPATH] - list of library paths (e.g., `-L /foo/bar -L /beep/boop`) +# @param {string} [LIBRARIES] - list of libraries (e.g., `-lopenblas -lpthread`) +# +# @example +# make +# +# @example +# make all +#/ +all: $(c_targets) + +.PHONY: all + +#/ +# Compiles C source files. +# +# @private +# @param {string} CC - C compiler (e.g., `gcc`) +# @param {string} CFLAGS - C compiler options +# @param {(string|void)} fPIC - compiler flag determining whether to generate position independent code (e.g., `-fPIC`) +# @param {string} INCLUDE - list of includes (e.g., `-I /foo/bar`) +# @param {string} SOURCE_FILES - list of source files +# @param {string} LIBPATH - list of library paths (e.g., `-L /foo/bar`) +# @param {string} LIBRARIES - list of libraries (e.g., `-lopenblas`) +#/ +$(c_targets): %.out: %.c + $(QUIET) $(CC) $(CFLAGS) $(fPIC) $(INCLUDE) -o $@ $(SOURCE_FILES) $< $(LIBPATH) -lm $(LIBRARIES) + +#/ +# Runs compiled examples. +# +# @example +# make run +#/ +run: $(c_targets) + $(QUIET) ./$< + +.PHONY: run + +#/ +# Removes generated files. +# +# @example +# make clean +#/ +clean: + $(QUIET) -rm -f *.o *.out + +.PHONY: clean diff --git a/base/special/cphase/examples/c/example.c b/base/special/cphase/examples/c/example.c new file mode 100644 index 000000000..e1f1c325a --- /dev/null +++ b/base/special/cphase/examples/c/example.c @@ -0,0 +1,43 @@ +/** +* @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. +*/ + +#include "stdlib/math/base/special/cphase.h" +#include "stdlib/complex/float64.h" +#include "stdlib/complex/reim.h" +#include + +int main( void ) { + const stdlib_complex128_t x[] = { + stdlib_complex128( 3.14, 1.0 ), + stdlib_complex128( -3.14, -1.0 ), + stdlib_complex128( 0.0, 0.0 ), + stdlib_complex128( 0.0/0.0, 0.0/0.0 ) + }; + + stdlib_complex128_t v; + double re; + double im; + double y; + int i; + for ( i = 0; i < 4; i++ ) { + v = x[ i ]; + y = stdlib_base_cphase( v ); + stdlib_reim( v, &re, &im ); + printf( "fcphase(%lf + %lfi) = %lf\n", re, im, y ); + } +} diff --git a/base/special/cphase/examples/index.js b/base/special/cphase/examples/index.js index 905066c32..5a80ed8d4 100644 --- a/base/special/cphase/examples/index.js +++ b/base/special/cphase/examples/index.js @@ -19,20 +19,13 @@ 'use strict'; var Complex128 = require( '@stdlib/complex/float64' ); -var randu = require( '@stdlib/random/base/randu' ); -var round = require( './../../../../base/special/round' ); -var real = require( '@stdlib/complex/real' ); -var imag = require( '@stdlib/complex/imag' ); +var uniform = require( '@stdlib/random/base/uniform' ); var cphase = require( './../lib' ); -var re; -var im; var z; var i; for ( i = 0; i < 100; i++ ) { - re = round( randu()*100.0 ) - 50.0; - im = round( randu()*100.0 ) - 50.0; - z = new Complex128( re, im ); - console.log( 'arg(%s) = %d', z.toString(), cphase( real(z), imag(z) ) ); + z = new Complex128( uniform( -500.0, 500.0 ), uniform( -500.0, 500.0 ) ); + console.log( 'arg(%s) = %d', z.toString(), cphase( z ) ); } diff --git a/base/special/cphase/include.gypi b/base/special/cphase/include.gypi new file mode 100644 index 000000000..78db9faf8 --- /dev/null +++ b/base/special/cphase/include.gypi @@ -0,0 +1,53 @@ +# @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. + +# A GYP include file for building a Node.js native add-on. +# +# Main documentation: +# +# [1]: https://gyp.gsrc.io/docs/InputFormatReference.md +# [2]: https://gyp.gsrc.io/docs/UserDocumentation.md +{ + # Define variables to be used throughout the configuration for all targets: + 'variables': { + # Source directory: + 'src_dir': './src', + + # Include directories: + 'include_dirs': [ + ' + +/** +* Computes the argument of a complex double-precision complex floating-point number in radians. +* +* @param z input value +* @return argument +* +* @example +* #include "stdlib/complex/float64.h" +* #include "stdlib/complex/real.h" +* #include "stdlib/complex/imag.h" +* +* stdlib_complex128_t z = stdlib_complex128( 5.0, 3.0 ); +* double out = stdlib_base_cphase( z ); +* // returns ~0.5404 +*/ +double stdlib_base_cphase( const stdlib_complex128_t z ) { + double re; + double im; + + stdlib_reim( z, &re, &im ); + return atan2( im, re ); // TODO: replace with stdlib function once available +} diff --git a/base/special/cphase/test/test.js b/base/special/cphase/test/test.js index 0781c77c2..9dcdec184 100644 --- a/base/special/cphase/test/test.js +++ b/base/special/cphase/test/test.js @@ -28,6 +28,7 @@ var EPS = require( '@stdlib/constants/float64/eps' ); var PINF = require( '@stdlib/constants/float64/pinf' ); var NINF = require( '@stdlib/constants/float64/ninf' ); var PI = require( '@stdlib/constants/float64/pi' ); +var Complex128 = require( '@stdlib/complex/float64' ); var cphase = require( './../lib' ); @@ -47,113 +48,113 @@ tape( 'main export is a function', function test( t ) { }); tape( 'the function returns `NaN` if provided `NaN` as either of the arguments', function test( t ) { - t.strictEqual( isnan( cphase( 2.0, NaN ) ), true, 'returns NaN' ); - t.strictEqual( isnan( cphase( NaN, 3.0 ) ), true, 'returns NaN' ); + t.strictEqual( isnan( cphase( new Complex128( 2.0, NaN ) ) ), true, 'returns NaN' ); + t.strictEqual( isnan( cphase( new Complex128( NaN, 3.0 ) ) ), true, 'returns NaN' ); t.end(); }); tape( 'the function returns `+0` if provided `im = +0.0` and `re >= 0`', function test( t ) { - t.strictEqual( cphase( 0.0, +0.0 ), +0.0, 'returns +0' ); - t.strictEqual( cphase( 2.0, +0.0 ), +0.0, 'returns +0' ); - t.strictEqual( cphase( 4.0, +0.0 ), +0.0, 'returns +0' ); - t.strictEqual( cphase( 5.0, +0.0 ), +0.0, 'returns +0' ); - t.strictEqual( cphase( 10.0, +0.0 ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 0.0, +0.0) ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 2.0, +0.0) ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 4.0, +0.0) ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 5.0, +0.0) ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 10.0, +0.0) ), +0.0, 'returns +0' ); t.end(); }); tape( 'the function returns `-0` if provided `im = -0.0` and `re >= 0`', function test( t ) { - t.strictEqual( isNegativeZero( cphase( 0.0, -0.0 ) ), true, 'returns -0' ); - t.strictEqual( isNegativeZero( cphase( 2.0, -0.0 ) ), true, 'returns -0' ); - t.strictEqual( isNegativeZero( cphase( 4.0, -0.0 ) ), true, 'returns -0' ); - t.strictEqual( isNegativeZero( cphase( 5.0, -0.0 ) ), true, 'returns -0' ); - t.strictEqual( isNegativeZero( cphase( 10.0, -0.0 ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 0.0, -0.0 ) ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 2.0, -0.0 ) ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 4.0, -0.0 ) ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 5.0, -0.0 ) ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 10.0, -0.0 ) ) ), true, 'returns -0' ); t.end(); }); tape( 'the function returns `PI` if provided `im = +0.0` and `re <= -0.0`', function test( t ) { - t.strictEqual( cphase( -0.0, +0.0 ), +PI, 'returns +PI' ); - t.strictEqual( cphase( -2.0, +0.0 ), +PI, 'returns +PI' ); - t.strictEqual( cphase( -4.0, +0.0 ), +PI, 'returns +PI' ); - t.strictEqual( cphase( -5.0, +0.0 ), +PI, 'returns +PI' ); - t.strictEqual( cphase( -10.0, +0.0 ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -0.0, +0.0 ) ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -2.0, +0.0 ) ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -4.0, +0.0 ) ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -5.0, +0.0 ) ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -10.0, +0.0 ) ), +PI, 'returns +PI' ); t.end(); }); tape( 'the function returns `-PI` if provided `im = -0.0` and `re <= -0.0`', function test( t ) { - t.strictEqual( cphase( -0.0, -0.0 ), -PI, 'returns -PI' ); - t.strictEqual( cphase( -2.0, -0.0 ), -PI, 'returns -PI' ); - t.strictEqual( cphase( -4.0, -0.0 ), -PI, 'returns -PI' ); - t.strictEqual( cphase( -5.0, -0.0 ), -PI, 'returns -PI' ); - t.strictEqual( cphase( -10.0, -0.0 ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -0.0, -0.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -2.0, -0.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -4.0, -0.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -5.0, -0.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -10.0, -0.0 ) ), -PI, 'returns -PI' ); t.end(); }); tape( 'the function returns `+PI/4` if provided `re = im = +infinity`', function test( t ) { - t.strictEqual( cphase( PINF, PINF ), +PI/4.0, 'returns +PI/4' ); + t.strictEqual( cphase( new Complex128( PINF, PINF ) ), +PI/4.0, 'returns +PI/4' ); t.end(); }); tape( 'the function returns `-PI/4` if provided `re = -im = +infinity`', function test( t ) { - t.strictEqual( cphase( PINF, NINF ), -PI/4.0, 'returns -PI/4' ); + t.strictEqual( cphase( new Complex128( PINF, NINF ) ), -PI/4.0, 'returns -PI/4' ); t.end(); }); tape( 'the function returns `*3*PI/4` if provided `-re = im = +infinity`', function test( t ) { - t.strictEqual( cphase( NINF, PINF ), +3.0*PI/4.0, 'returns +3*PI/4' ); + t.strictEqual( cphase( new Complex128( NINF, PINF ) ), +3.0*PI/4.0, 'returns +3*PI/4' ); t.end(); }); tape( 'the function returns `-3*PI/4` if provided `re = im = -infinity`', function test( t ) { - t.strictEqual( cphase( NINF, NINF ), -3.0*PI/4.0, 'returns -3*PI/4' ); + t.strictEqual( cphase( new Complex128( NINF, NINF ) ), -3.0*PI/4.0, 'returns -3*PI/4' ); t.end(); }); tape( 'the function returns `0.0` when `re = +infinity`', function test( t ) { - t.strictEqual( cphase( PINF, -2.0 ), 0.0, 'returns 0.0' ); - t.strictEqual( cphase( PINF, 0.0 ), 0.0, 'returns 0.0' ); - t.strictEqual( cphase( PINF, 2.0 ), 0.0, 'returns 0.0' ); + t.strictEqual( cphase( new Complex128( PINF, -2.0 ) ), 0.0, 'returns 0.0' ); + t.strictEqual( cphase( new Complex128( PINF, 0.0 ) ), 0.0, 'returns 0.0' ); + t.strictEqual( cphase( new Complex128( PINF, 2.0 ) ), 0.0, 'returns 0.0' ); t.end(); }); tape( 'the function returns `+PI` when `im > 0` and `re = -infinity`', function test( t ) { - t.strictEqual( cphase( NINF, 1.0 ), PI, 'returns PI' ); - t.strictEqual( cphase( NINF, 2.0 ), PI, 'returns PI' ); - t.strictEqual( cphase( NINF, 3.0 ), PI, 'returns PI' ); + t.strictEqual( cphase( new Complex128( NINF, 1.0 ) ), PI, 'returns PI' ); + t.strictEqual( cphase( new Complex128( NINF, 2.0 ) ), PI, 'returns PI' ); + t.strictEqual( cphase( new Complex128( NINF, 3.0 ) ), PI, 'returns PI' ); t.end(); }); tape( 'the function returns `-PI` when `im < 0` and `re = -infinity`', function test( t ) { - t.strictEqual( cphase( NINF, -1.0 ), -PI, 'returns -PI' ); - t.strictEqual( cphase( NINF, -2.0 ), -PI, 'returns -PI' ); - t.strictEqual( cphase( NINF, -3.0 ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( NINF, -1.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( NINF, -2.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( NINF, -3.0 ) ), -PI, 'returns -PI' ); t.end(); }); tape( 'the function returns `+PI/2` when `im = +infinity`', function test( t ) { - t.strictEqual( cphase( -1.0, PINF ), PI/2.0, 'returns PI/2' ); - t.strictEqual( cphase( 0.0, PINF ), PI/2.0, 'returns PI/2' ); - t.strictEqual( cphase( 2.0, PINF ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( -1.0, PINF ) ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, PINF ) ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 2.0, PINF ) ), PI/2.0, 'returns PI/2' ); t.end(); }); tape( 'the function returns `-PI/2` when `im = -infinity`', function test( t ) { - t.strictEqual( cphase( -1.0, NINF ), -PI/2.0, 'returns -PI/2' ); - t.strictEqual( cphase( 0.0, NINF ), -PI/2.0, 'returns -PI/2' ); - t.strictEqual( cphase( 2.0, NINF ), -PI/2.0, 'returns -PI/2' ); + t.strictEqual( cphase( new Complex128( -1.0, NINF ) ), -PI/2.0, 'returns -PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, NINF ) ), -PI/2.0, 'returns -PI/2' ); + t.strictEqual( cphase( new Complex128( 2.0, NINF ) ), -PI/2.0, 'returns -PI/2' ); t.end(); }); tape( 'the function returns `PI/2` if provided a positive `im` and `re=0`', function test( t ) { - t.strictEqual( cphase( 0.0, 2.0 ), PI/2.0, 'returns PI/2' ); - t.strictEqual( cphase( 0.0, 1.0 ), PI/2.0, 'returns PI/2' ); - t.strictEqual( cphase( 0.0, 0.5 ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, 2.0 ) ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, 1.0 ) ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, 0.5 ) ), PI/2.0, 'returns PI/2' ); t.end(); }); tape( 'the function returns `-PI/2` if provided a negative `im` and `re=0`', function test( t ) { - t.strictEqual( cphase( 0.0, -2.0 ), -PI/2.0, 'returns PI/2' ); - t.strictEqual( cphase( 0.0, -1.0 ), -PI/2.0, 'returns PI/2' ); - t.strictEqual( cphase( 0.0, -0.5 ), -PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, -2.0 ) ), -PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, -1.0 ) ), -PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, -0.5 ) ), -PI/2.0, 'returns PI/2' ); t.end(); }); @@ -170,7 +171,7 @@ tape( 'the function computes the argument of a complex number (when `re` and `im im = positivePositive.im; expected = positivePositive.expected; for ( i = 0; i < re.length; i++ ) { - actual = cphase( re[i], im[i] ); + actual = cphase( new Complex128( re[i], im[i] ) ); delta = abs( actual - expected[i] ); tol = EPS * abs( expected[i] ); t.strictEqual( delta <= tol, true, 'within tolerance. re: '+re[i]+'. im: '+im[i]+'. Actual: '+actual+'. Expected: '+expected[i]+'. tol: '+tol+'. delta: '+delta+'.' ); @@ -191,7 +192,7 @@ tape( 'the function computes the argument of a complex number (when `re` is nega im = negativePositive.im; expected = negativePositive.expected; for ( i = 0; i < re.length; i++ ) { - actual = cphase( re[i], im[i] ); + actual = cphase( new Complex128( re[i], im[i] ) ); delta = abs( actual - expected[i] ); tol = 2.0 * EPS * abs( expected[i] ); t.strictEqual( delta <= tol, true, 'within tolerance. re: '+re[i]+'. im: '+im[i]+'. Actual: '+actual+'. Expected: '+expected[i]+'. tol: '+tol+'. delta: '+delta+'.' ); @@ -212,7 +213,7 @@ tape( 'the function computes the argument of a complex number (when `re` and `im im = negativeNegative.im; expected = negativeNegative.expected; for ( i = 0; i < re.length; i++ ) { - actual = cphase( re[i], im[i] ); + actual = cphase( new Complex128( re[i], im[i] ) ); delta = abs( actual - expected[i] ); tol = 2.0 * EPS * abs( expected[i] ); t.strictEqual( delta <= tol, true, 'within tolerance. re: '+re[i]+'. im: '+im[i]+'. Actual: '+actual+'. Expected: '+expected[i]+'. tol: '+tol+'. delta: '+delta+'.' ); diff --git a/base/special/cphase/test/test.native.js b/base/special/cphase/test/test.native.js new file mode 100644 index 000000000..422e1a240 --- /dev/null +++ b/base/special/cphase/test/test.native.js @@ -0,0 +1,231 @@ +/** +* @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'; + +// MODULES // + +var resolve = require( 'path' ).resolve; +var tape = require( 'tape' ); +var isnan = require( './../../../../base/assert/is-nan' ); +var isNegativeZero = require( './../../../../base/assert/is-negative-zero' ); +var abs = require( './../../../../base/special/abs' ); +var EPS = require( '@stdlib/constants/float64/eps' ); +var PINF = require( '@stdlib/constants/float64/pinf' ); +var NINF = require( '@stdlib/constants/float64/ninf' ); +var PI = require( '@stdlib/constants/float64/pi' ); +var Complex128 = require( '@stdlib/complex/float64' ); +var tryRequire = require( '@stdlib/utils/try-require' ); + + +// VARIABLES // + +var cphase = tryRequire( resolve( __dirname, './../lib/native.js' ) ); +var opts = { + 'skip': ( cphase instanceof Error ) +}; + + +// FIXTURES // + +var positivePositive = require( './fixtures/julia/positive_positive.json' ); +var negativePositive = require( './fixtures/julia/negative_positive.json' ); +var negativeNegative = require( './fixtures/julia/negative_negative.json' ); + + +// TESTS // + +tape( 'main export is a function', opts, function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof cphase, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function returns `NaN` if provided `NaN` as either of the arguments', opts, function test( t ) { + t.strictEqual( isnan( cphase( new Complex128( 2.0, NaN ) ) ), true, 'returns NaN' ); + t.strictEqual( isnan( cphase( new Complex128( NaN, 3.0 ) ) ), true, 'returns NaN' ); + t.end(); +}); + +tape( 'the function returns `+0` if provided `im = +0.0` and `re >= 0`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( 0.0, +0.0) ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 2.0, +0.0) ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 4.0, +0.0) ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 5.0, +0.0) ), +0.0, 'returns +0' ); + t.strictEqual( cphase( new Complex128( 10.0, +0.0) ), +0.0, 'returns +0' ); + t.end(); +}); + +tape( 'the function returns `-0` if provided `im = -0.0` and `re >= 0`', opts, function test( t ) { + t.strictEqual( isNegativeZero( cphase( new Complex128( 0.0, -0.0 ) ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 2.0, -0.0 ) ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 4.0, -0.0 ) ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 5.0, -0.0 ) ) ), true, 'returns -0' ); + t.strictEqual( isNegativeZero( cphase( new Complex128( 10.0, -0.0 ) ) ), true, 'returns -0' ); + t.end(); +}); + +tape( 'the function returns `PI` if provided `im = +0.0` and `re <= -0.0`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( -0.0, +0.0 ) ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -2.0, +0.0 ) ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -4.0, +0.0 ) ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -5.0, +0.0 ) ), +PI, 'returns +PI' ); + t.strictEqual( cphase( new Complex128( -10.0, +0.0 ) ), +PI, 'returns +PI' ); + t.end(); +}); + +tape( 'the function returns `-PI` if provided `im = -0.0` and `re <= -0.0`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( -0.0, -0.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -2.0, -0.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -4.0, -0.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -5.0, -0.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( -10.0, -0.0 ) ), -PI, 'returns -PI' ); + t.end(); +}); + +tape( 'the function returns `+PI/4` if provided `re = im = +infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( PINF, PINF ) ), +PI/4.0, 'returns +PI/4' ); + t.end(); +}); + +tape( 'the function returns `-PI/4` if provided `re = -im = +infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( PINF, NINF ) ), -PI/4.0, 'returns -PI/4' ); + t.end(); +}); + +tape( 'the function returns `*3*PI/4` if provided `-re = im = +infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( NINF, PINF ) ), +3.0*PI/4.0, 'returns +3*PI/4' ); + t.end(); +}); + +tape( 'the function returns `-3*PI/4` if provided `re = im = -infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( NINF, NINF ) ), -3.0*PI/4.0, 'returns -3*PI/4' ); + t.end(); +}); + +tape( 'the function returns `0.0` when `re = +infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( PINF, -2.0 ) ), 0.0, 'returns 0.0' ); + t.strictEqual( cphase( new Complex128( PINF, 0.0 ) ), 0.0, 'returns 0.0' ); + t.strictEqual( cphase( new Complex128( PINF, 2.0 ) ), 0.0, 'returns 0.0' ); + t.end(); +}); + +tape( 'the function returns `+PI` when `im > 0` and `re = -infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( NINF, 1.0 ) ), PI, 'returns PI' ); + t.strictEqual( cphase( new Complex128( NINF, 2.0 ) ), PI, 'returns PI' ); + t.strictEqual( cphase( new Complex128( NINF, 3.0 ) ), PI, 'returns PI' ); + t.end(); +}); + +tape( 'the function returns `-PI` when `im < 0` and `re = -infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( NINF, -1.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( NINF, -2.0 ) ), -PI, 'returns -PI' ); + t.strictEqual( cphase( new Complex128( NINF, -3.0 ) ), -PI, 'returns -PI' ); + t.end(); +}); + +tape( 'the function returns `+PI/2` when `im = +infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( -1.0, PINF ) ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, PINF ) ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 2.0, PINF ) ), PI/2.0, 'returns PI/2' ); + t.end(); +}); + +tape( 'the function returns `-PI/2` when `im = -infinity`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( -1.0, NINF ) ), -PI/2.0, 'returns -PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, NINF ) ), -PI/2.0, 'returns -PI/2' ); + t.strictEqual( cphase( new Complex128( 2.0, NINF ) ), -PI/2.0, 'returns -PI/2' ); + t.end(); +}); + +tape( 'the function returns `PI/2` if provided a positive `im` and `re=0`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( 0.0, 2.0 ) ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, 1.0 ) ), PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, 0.5 ) ), PI/2.0, 'returns PI/2' ); + t.end(); +}); + +tape( 'the function returns `-PI/2` if provided a negative `im` and `re=0`', opts, function test( t ) { + t.strictEqual( cphase( new Complex128( 0.0, -2.0 ) ), -PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, -1.0 ) ), -PI/2.0, 'returns PI/2' ); + t.strictEqual( cphase( new Complex128( 0.0, -0.5 ) ), -PI/2.0, 'returns PI/2' ); + t.end(); +}); + +tape( 'the function computes the argument of a complex number (when `re` and `im` are positive)', opts, function test( t ) { + var expected; + var actual; + var delta; + var tol; + var re; + var im; + var i; + + re = positivePositive.re; + im = positivePositive.im; + expected = positivePositive.expected; + for ( i = 0; i < re.length; i++ ) { + actual = cphase( new Complex128( re[i], im[i] ) ); + delta = abs( actual - expected[i] ); + tol = EPS * abs( expected[i] ); + t.strictEqual( delta <= tol, true, 'within tolerance. re: '+re[i]+'. im: '+im[i]+'. Actual: '+actual+'. Expected: '+expected[i]+'. tol: '+tol+'. delta: '+delta+'.' ); + } + t.end(); +}); + +tape( 'the function computes the argument of a complex number (when `re` is negative and `im` is positive)', opts, function test( t ) { + var expected; + var actual; + var delta; + var tol; + var re; + var im; + var i; + + re = negativePositive.re; + im = negativePositive.im; + expected = negativePositive.expected; + for ( i = 0; i < re.length; i++ ) { + actual = cphase( new Complex128( re[i], im[i] ) ); + delta = abs( actual - expected[i] ); + tol = 2.0 * EPS * abs( expected[i] ); + t.strictEqual( delta <= tol, true, 'within tolerance. re: '+re[i]+'. im: '+im[i]+'. Actual: '+actual+'. Expected: '+expected[i]+'. tol: '+tol+'. delta: '+delta+'.' ); + } + t.end(); +}); + +tape( 'the function computes the argument of a complex number (when `re` and `im` are negative)', opts, function test( t ) { + var expected; + var actual; + var delta; + var tol; + var re; + var im; + var i; + + re = negativeNegative.re; + im = negativeNegative.im; + expected = negativeNegative.expected; + for ( i = 0; i < re.length; i++ ) { + actual = cphase( new Complex128( re[i], im[i] ) ); + delta = abs( actual - expected[i] ); + tol = 2.0 * EPS * abs( expected[i] ); + t.strictEqual( delta <= tol, true, 'within tolerance. re: '+re[i]+'. im: '+im[i]+'. Actual: '+actual+'. Expected: '+expected[i]+'. tol: '+tol+'. delta: '+delta+'.' ); + } + t.end(); +}); diff --git a/base/special/cpolar/lib/cpolar.js b/base/special/cpolar/lib/cpolar.js index dc68df64d..34e0bff8a 100644 --- a/base/special/cpolar/lib/cpolar.js +++ b/base/special/cpolar/lib/cpolar.js @@ -46,8 +46,11 @@ var Complex128 = require( '@stdlib/complex/float64' ); * // returns true */ function cpolar( out, re, im ) { - out[ 0 ] = cabs( new Complex128( re, im ) ); - out[ 1 ] = cphase( re, im ); + var z; + + z = new Complex128( re, im ); + out[ 0 ] = cabs( z ); + out[ 1 ] = cphase( z ); return out; } diff --git a/base/special/cpolar/test/test.js b/base/special/cpolar/test/test.js index e586aab0c..8085c11de 100644 --- a/base/special/cpolar/test/test.js +++ b/base/special/cpolar/test/test.js @@ -42,7 +42,7 @@ tape( 'the function computes the absolute value and phase of a complex number', var v; v = cpolar( 5.0, 3.0 ); - expected = [ cabs( new Complex128( 5.0, 3.0 ) ), cphase( 5.0, 3.0 ) ]; + expected = [ cabs( new Complex128( 5.0, 3.0 ) ), cphase( new Complex128( 5.0, 3.0 ) ) ]; t.deepEqual( v, expected, 'returns expected value' ); @@ -57,7 +57,7 @@ tape( 'the function computes the absolute value and phase of a complex number (o out = new Array( 2 ); v = cpolar( out, 5.0, 3.0 ); - expected = [ cabs( new Complex128( 5.0, 3.0 ) ), cphase( 5.0, 3.0 ) ]; + expected = [ cabs( new Complex128( 5.0, 3.0 ) ), cphase( new Complex128( 5.0, 3.0 ) ) ]; t.deepEqual( v, expected, 'returns expected value' ); t.strictEqual( v, out, 'returns output value' ); @@ -75,7 +75,7 @@ tape( 'the function computes the absolute value and phase of a complex number (o v = cpolar( out, 5.0, 3.0 ); abs = cabs( new Complex128( 5.0, 3.0 ) ); - expected = new Float64Array( [ abs, cphase( 5.0, 3.0 ) ] ); + expected = new Float64Array( [ abs, cphase( new Complex128( 5.0, 3.0 ) ) ] ); t.deepEqual( v, expected, 'returns expected value' ); t.strictEqual( v, out, 'returns output value' ); @@ -93,7 +93,7 @@ tape( 'the function computes the absolute value and phase of a complex number (o expected = { '0': cabs( new Complex128( 5.0, 3.0 ) ), - '1': cphase( 5.0, 3.0 ) + '1': cphase( new Complex128( 5.0, 3.0 ) ) }; t.deepEqual( v, expected, 'returns expected value' );