Skip to content

Commit 6b7ea3a

Browse files
kgrytekgryte
committed
Add pkg to compute the squared absolute value for a single-precision complex floating-point number
1 parent 1dc63d6 commit 6b7ea3a

File tree

25 files changed

+1783
-0
lines changed

25 files changed

+1783
-0
lines changed

‎lib/node_modules/@stdlib/math/base/special/cabs2f/README.md

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2021 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# abs2
22+
23+
> Compute the squared [absolute value][absolute-value] of a single-precision [complex][@stdlib/complex/float32] floating-point number.
24+
25+
<section class="intro">
26+
27+
The [absolute value][absolute-value] of a [complex][@stdlib/complex/float32] number is defined as
28+
29+
<!-- <equation class="equation" label="eq:absolute_value_complex" align="center" raw="|a + bi| = \sqrt{a^2 + b^2}" alt="Absolute value"> -->
30+
31+
<div class="equation" align="center" data-raw-text="|a + bi| = \sqrt{a^2 + b^2}" data-equation="eq:absolute_value_complex">
32+
<img src="" alt="Absolute value">
33+
<br>
34+
</div>
35+
36+
<!-- </equation> -->
37+
38+
which corresponds to the length of a vector from the origin to a complex value plotted in the complex plane.
39+
40+
</section>
41+
42+
<!-- /.intro -->
43+
44+
<section class="usage">
45+
46+
## Usage
47+
48+
```javascript
49+
var cabs2f = require( '@stdlib/math/base/special/cabs2f' );
50+
```
51+
52+
#### cabs2f( z )
53+
54+
Computes the squared [absolute value][absolute-value] of a single-precision [complex][@stdlib/complex/float32] floating-point number.
55+
56+
```javascript
57+
var Complex64 = require( '@stdlib/complex/float32' );
58+
59+
var y = cabs2f( new Complex64( 5.0, 3.0 ) );
60+
// returns 34.0
61+
```
62+
63+
</section>
64+
65+
<!-- /.usage -->
66+
67+
<section class="notes">
68+
69+
## Notes
70+
71+
- Be careful to avoid overflow and underflow.
72+
- Depending on the environment, this function _may_ have better performance than computing the [absolute value][absolute-value] of a [complex][@stdlib/complex/float32] number and then squaring. Hence, where appropriate, consider using `cabs2f()` over [`cabsf()`][@stdlib/math/base/special/cabsf].
73+
74+
</section>
75+
76+
<!-- /.notes -->
77+
78+
<section class="examples">
79+
80+
## Examples
81+
82+
<!-- eslint-disable max-len -->
83+
84+
<!-- eslint no-undef: "error" -->
85+
86+
```javascript
87+
var Complex64 = require( '@stdlib/complex/float32' );
88+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
89+
var cabs2f = require( '@stdlib/math/base/special/cabs2f' );
90+
91+
// Create a PRNG to generate uniformly distributed pseudorandom integers:
92+
var rand = discreteUniform( -50, 50 );
93+
94+
// Compute the squared absolute value for a set of random numbers...
95+
var z;
96+
var i;
97+
for ( i = 0; i < 100; i++ ) {
98+
z = new Complex64( rand(), rand() );
99+
console.log( 'cabs2f(%s) = %d', z.toString(), cabs2f( z ) );
100+
}
101+
```
102+
103+
</section>
104+
105+
<!-- /.examples -->
106+
107+
<!-- C interface documentation. -->
108+
109+
* * *
110+
111+
<section class="c">
112+
113+
## C APIs
114+
115+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
116+
117+
<section class="intro">
118+
119+
</section>
120+
121+
<!-- /.intro -->
122+
123+
<!-- C usage documentation. -->
124+
125+
<section class="usage">
126+
127+
### Usage
128+
129+
```c
130+
#include "stdlib/math/base/special/cabs2f.h"
131+
```
132+
133+
#### stdlib_base_cabs2f( z )
134+
135+
Computes the squared [absolute value][absolute-value] of a single-precision complex floating-point number.
136+
137+
```c
138+
#include <complex.h>
139+
140+
float y = stdlib_base_cabs2f( 5.0+3.0*I );
141+
// returns 34.0f
142+
```
143+
144+
The function accepts the following arguments:
145+
146+
- **z**: `[in] float complex` input value.
147+
148+
```c
149+
float stdlib_base_cabs2f( const float complex z );
150+
```
151+
152+
</section>
153+
154+
<!-- /.usage -->
155+
156+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
157+
158+
<section class="notes">
159+
160+
</section>
161+
162+
<!-- /.notes -->
163+
164+
<!-- C API usage examples. -->
165+
166+
<section class="examples">
167+
168+
### Examples
169+
170+
```c
171+
#include "stdlib/math/base/special/cabs2f.h"
172+
#include <stdio.h>
173+
#include <complex.h>
174+
175+
int main() {
176+
float complex x[] = { 3.14f+1.0f*I, -3.14f-1.0f*I, 0.0f+0.0f*I, 0.0f/0.0f+0.0f/0.0f*I };
177+
178+
float complex v;
179+
float y;
180+
int i;
181+
for ( i = 0; i < 4; i++ ) {
182+
v = x[ i ];
183+
y = stdlib_base_cabs2f( v );
184+
printf( "f(%f + %f) = %f\n", crealf( v ), cimagf( v ), y );
185+
}
186+
}
187+
```
188+
189+
</section>
190+
191+
<!-- /.examples -->
192+
193+
</section>
194+
195+
<!-- /.c -->
196+
197+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
198+
199+
<section class="related">
200+
201+
</section>
202+
203+
<!-- /.related -->
204+
205+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
206+
207+
<section class="links">
208+
209+
[absolute-value]: https://en.wikipedia.org/wiki/Absolute_value
210+
211+
[@stdlib/math/base/special/cabsf]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/cabsf
212+
213+
[@stdlib/complex/float32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/complex/float32
214+
215+
</section>
216+
217+
<!-- /.links -->

‎lib/node_modules/@stdlib/math/base/special/cabs2f/benchmark/benchmark.js

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2021 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var uniform = require( '@stdlib/random/base/uniform' );
25+
var isnanf = require( '@stdlib/math/base/assert/is-nanf' );
26+
var Complex64 = require( '@stdlib/complex/float32' );
27+
var pkg = require( './../package.json' ).name;
28+
var cabs2f = require( './../lib' );
29+
30+
31+
// MAIN //
32+
33+
bench( pkg, function benchmark( b ) {
34+
var values;
35+
var y;
36+
var i;
37+
38+
values = [
39+
new Complex64( uniform( -500.0, 500.0 ), uniform( -500.0, 500.0 ) ),
40+
new Complex64( uniform( -500.0, 500.0 ), uniform( -500.0, 500.0 ) )
41+
];
42+
43+
b.tic();
44+
for ( i = 0; i < b.iterations; i++ ) {
45+
y = cabs2f( values[ i%values.length ] );
46+
if ( isnanf( y ) ) {
47+
b.fail( 'should not return NaN' );
48+
}
49+
}
50+
b.toc();
51+
if ( isnanf( y ) ) {
52+
b.fail( 'should not return NaN' );
53+
}
54+
b.pass( 'benchmark finished' );
55+
b.end();
56+
});

0 commit comments

Comments
 (0)