Skip to content

Commit 998d597

Browse files
rreusserkgryte
rreusser
authored and
kgryte
committed
Add the complex cis function (stdlib-js#143)
* Add complex cis function * Add note on memory management * Group arithmetic in python benchmark * Clean up test description * Clean up review issues * Fix real/imag organization issue in c benchmark * Fix README example and python benchmark
1 parent 1c7365d commit 998d597

19 files changed

Lines changed: 1052 additions & 0 deletions

File tree

‎docs/links/database.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1566,6 +1566,19 @@
15661566
"chi"
15671567
]
15681568
},
1569+
"https://en.wikipedia.org/wiki/Cis_%28mathematics%29": {
1570+
"id": "cis",
1571+
"description": "Wikipedia entry for cis function.",
1572+
"short_url": "",
1573+
"keywords": [
1574+
"cis",
1575+
"complex",
1576+
"exponential",
1577+
"math",
1578+
"phasor",
1579+
"special"
1580+
]
1581+
},
15691582
"https://en.wikipedia.org/wiki/Code_point": {
15701583
"id": "code-point",
15711584
"description": "Wikipedia entry for a code point, a term from character encoding to refer to a numerical value in code space.",

‎lib/node_modules/@stdlib/math/base/complex/cis/README.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# cis
2+
3+
> Compute the [cis][cis] function of a complex number.
4+
5+
<section class="intro">
6+
7+
The [cis][cis] function is defined as
8+
9+
<!-- <equation class="equation" label="eq:cis_function" align="center" raw="\operatorname{cis}(z) = e^{iz} = \cos(z) + i \sin(z)." alt="cis function"> -->
10+
11+
<!-- </equation> -->
12+
13+
</section>
14+
15+
<!-- /.intro -->
16+
17+
<section class="usage">
18+
19+
## Usage
20+
21+
``` javascript
22+
var cis = require( '@stdlib/math/base/complex/cis' );
23+
```
24+
25+
#### cis( \[out,\] re, im )
26+
27+
Evaluates the [cis][cis] function with a `complex` argument comprised of a _real_ component `re` and an _imaginary_ component `im`.
28+
29+
``` javascript
30+
var v = cis( 0.0, 0.0 );
31+
// returns [ 1.0, 0.0 ]
32+
33+
v = cis( 1.0, 0.0 );
34+
// returns [ ~0.540, ~0.841 ]
35+
```
36+
37+
By default, the function returns real and imaginary components as a two-element `array`. To avoid unnecessary memory allocation, the function supports providing an output (destination) object.
38+
39+
```javascript
40+
var out = new Float64Array( 2 );
41+
42+
var v = cis( out, 1.0, 0.0 );
43+
// returns <Float64Array>[ ~0.540, ~0.841 ]
44+
45+
var bool = ( v === out );
46+
// returns true
47+
```
48+
49+
</section>
50+
51+
<!-- /.usage -->
52+
53+
54+
<section class="examples">
55+
56+
## Examples
57+
58+
``` javascript
59+
var Complex128 = require( '@stdlib/types/complex/float64' );
60+
var randu = require( '@stdlib/math/base/random/randu' );
61+
var round = require( '@stdlib/math/base/special/round' );
62+
var real = require( '@stdlib/types/complex/real' );
63+
var imag = require( '@stdlib/types/complex/imag' );
64+
var cis = require( '@stdlib/math/base/complex/cis' );
65+
66+
var re;
67+
var im;
68+
var z1;
69+
var z2;
70+
var o;
71+
var i;
72+
73+
for ( i = 0; i < 100; i++ ) {
74+
re = round( randu()*100.0 ) - 50.0;
75+
im = round( randu()*100.0 ) - 50.0;
76+
z1 = new Complex128( re, im );
77+
78+
o = cis( [ 0.0, 0.0 ], real(z1), imag(z1) );
79+
z2 = new Complex128( o[ 0 ], o[ 1 ] );
80+
81+
console.log( 'cis(%s) = %s', z1.toString(), z2.toString() );
82+
}
83+
```
84+
85+
</section>
86+
87+
<!-- /.examples -->
88+
89+
<section class="links">
90+
91+
[cis]: https://en.wikipedia.org/wiki/Cis_%28mathematics%29
92+
93+
</section>
94+
95+
<!-- /.links -->

‎lib/node_modules/@stdlib/math/base/complex/cis/benchmark/benchmark.js‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
'use strict';
2+
3+
// MODULES //
4+
5+
var bench = require( '@stdlib/bench' );
6+
var randu = require( '@stdlib/math/base/random/randu' );
7+
var isArray = require( '@stdlib/assert/is-array' );
8+
var pkg = require( './../package.json' ).name;
9+
var cis = require( './../lib' );
10+
11+
12+
// MAIN //
13+
14+
bench( pkg, function benchmark( b ) {
15+
var re;
16+
var im;
17+
var y;
18+
var i;
19+
20+
b.tic();
21+
for ( i = 0; i < b.iterations; i++ ) {
22+
re = ( randu()*100.0 ) - 50.0;
23+
im = ( randu()*100.0 ) - 50.0;
24+
y = cis( re, im );
25+
if ( y.length === 0 ) {
26+
b.fail( 'should not be empty' );
27+
}
28+
}
29+
b.toc();
30+
if ( !isArray( y ) ) {
31+
b.fail( 'should return an array' );
32+
}
33+
b.pass( 'benchmark finished' );
34+
b.end();
35+
});
36+
37+
bench( pkg+'::memory_reuse', function benchmark( b ) {
38+
var out;
39+
var re;
40+
var im;
41+
var y;
42+
var i;
43+
44+
out = new Array( 2 );
45+
46+
b.tic();
47+
for ( i = 0; i < b.iterations; i++ ) {
48+
re = ( randu()*100.0 ) - 50.0;
49+
im = ( randu()*100.0 ) - 50.0;
50+
y = cis( out, re, im );
51+
if ( y.length === 0 ) {
52+
b.fail( 'should not be empty' );
53+
}
54+
}
55+
b.toc();
56+
if ( !isArray( y ) ) {
57+
b.fail( 'should return an array' );
58+
}
59+
b.pass( 'benchmark finished' );
60+
b.end();
61+
});

‎lib/node_modules/@stdlib/math/base/complex/cis/benchmark/c/Makefile‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
2+
# VARIABLES #
3+
4+
ifndef VERBOSE
5+
QUIET := @
6+
endif
7+
8+
# Determine the OS:
9+
#
10+
# [1]: https://en.wikipedia.org/wiki/Uname#Examples
11+
# [2]: http://stackoverflow.com/a/27776822/2225624
12+
OS ?= $(shell uname)
13+
ifneq (, $(findstring MINGW,$(OS)))
14+
OS := WINNT
15+
else
16+
ifneq (, $(findstring MSYS,$(OS)))
17+
OS := WINNT
18+
else
19+
ifneq (, $(findstring CYGWIN,$(OS)))
20+
OS := WINNT
21+
endif
22+
endif
23+
endif
24+
25+
# Define the program used for compiling C source files:
26+
ifdef C_COMPILER
27+
CC := $(C_COMPILER)
28+
else
29+
CC := gcc
30+
endif
31+
32+
# Define the command-line options when compiling C files:
33+
CFLAGS ?= \
34+
-std=c99 \
35+
-O3 \
36+
-Wall \
37+
-pedantic
38+
39+
# Determine whether to generate [position independent code][1]:
40+
#
41+
# [1]: https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options
42+
# [2]: http://stackoverflow.com/questions/5311515/gcc-fpic-option
43+
ifeq ($(OS), WINNT)
44+
fPIC ?=
45+
else
46+
fPIC ?= -fPIC
47+
endif
48+
49+
# List of C targets:
50+
c_targets := benchmark.out
51+
52+
53+
# TARGETS #
54+
55+
# Default target.
56+
#
57+
# This target is the default target.
58+
59+
all: $(c_targets)
60+
61+
.PHONY: all
62+
63+
64+
# Compile C source.
65+
#
66+
# This target compiles C source files.
67+
68+
$(c_targets): %.out: %.c
69+
$(QUIET) $(CC) $(CFLAGS) $(fPIC) -o $@ $< -lm
70+
71+
72+
# Run a benchmark.
73+
#
74+
# This target runs a benchmark.
75+
76+
run: $(c_targets)
77+
$(QUIET) ./$<
78+
79+
.PHONY: run
80+
81+
82+
# Perform clean-up.
83+
#
84+
# This target removes generated files.
85+
86+
clean:
87+
$(QUIET) -rm -f *.o *.out
88+
89+
.PHONY: clean

‎lib/node_modules/@stdlib/math/base/complex/cis/benchmark/c/benchmark.c‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
/**
2+
* Benchmark `cis`.
3+
*/
4+
#include <stdlib.h>
5+
#include <stdio.h>
6+
#include <math.h>
7+
#include <complex.h>
8+
#include <sys/time.h>
9+
10+
#define NAME "cis"
11+
#define ITERATIONS 1000000
12+
#define REPEATS 3
13+
14+
/**
15+
* Prints the TAP version.
16+
*/
17+
void print_version() {
18+
printf( "TAP version 13\n" );
19+
}
20+
21+
/**
22+
* Prints the TAP summary.
23+
*
24+
* @param total total number of tests
25+
* @param passing total number of passing tests
26+
*/
27+
void print_summary( int total, int passing ) {
28+
printf( "#\n" );
29+
printf( "1..%d\n", total ); // TAP plan
30+
printf( "# total %d\n", total );
31+
printf( "# pass %d\n", passing );
32+
printf( "#\n" );
33+
printf( "# ok\n" );
34+
}
35+
36+
/**
37+
* Prints benchmarks results.
38+
*
39+
* @param elapsed elapsed time in seconds
40+
*/
41+
void print_results( double elapsed ) {
42+
double rate = (double)ITERATIONS / elapsed;
43+
printf( " ---\n" );
44+
printf( " iterations: %d\n", ITERATIONS );
45+
printf( " elapsed: %0.9f\n", elapsed );
46+
printf( " rate: %0.9f\n", rate );
47+
printf( " ...\n" );
48+
}
49+
50+
/**
51+
* Returns a clock time.
52+
*
53+
* @return clock time
54+
*/
55+
double tic() {
56+
struct timeval now;
57+
gettimeofday( &now, NULL );
58+
return (double)now.tv_sec + (double)now.tv_usec/1.0e6;
59+
}
60+
61+
/**
62+
* Generates a random double on the interval [0,1].
63+
*
64+
* @return random double
65+
*/
66+
double rand_double() {
67+
int r = rand();
68+
return (double)r / ( (double)RAND_MAX + 1.0 );
69+
}
70+
71+
/**
72+
* Runs a benchmark.
73+
*
74+
* @return elapsed time in seconds
75+
*/
76+
double benchmark() {
77+
double elapsed;
78+
double re;
79+
double im;
80+
double t;
81+
int i;
82+
83+
double complex z1;
84+
double complex z2;
85+
86+
t = tic();
87+
for ( i = 0; i < ITERATIONS; i++ ) {
88+
re = ( 100.0*rand_double() ) - 50.0;
89+
im = ( 100.0*rand_double() ) - 50.0;
90+
91+
z2 = ( cos( re ) + I * sin( re ) ) / exp( im );
92+
if ( z2 != z2 ) {
93+
printf( "should not return NaN\n" );
94+
break;
95+
}
96+
}
97+
elapsed = tic() - t;
98+
if ( z2 != z2 ) {
99+
printf( "should not return NaN\n" );
100+
}
101+
return elapsed;
102+
}
103+
104+
/**
105+
* Main execution sequence.
106+
*/
107+
int main( void ) {
108+
double elapsed;
109+
int i;
110+
111+
// Use the current time to seed the random number generator:
112+
srand( time( NULL ) );
113+
114+
print_version();
115+
for ( i = 0; i < REPEATS; i++ ) {
116+
printf( "# c::%s\n", NAME );
117+
elapsed = benchmark();
118+
print_results( elapsed );
119+
printf( "ok %d benchmark finished\n", i+1 );
120+
}
121+
print_summary( REPEATS, REPEATS );
122+
}

‎lib/node_modules/@stdlib/math/base/complex/cis/benchmark/julia/REQUIRE‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
julia 0.5
2+
BenchmarkTools 0.0.8

0 commit comments

Comments
 (0)