Skip to content

Commit 013635d

Browse files
kgrytekgryte
committed
Add strided interface which computes the principal square root of each element according to a mask array
1 parent 0683fde commit 013635d

33 files changed

+4701
-0
lines changed

‎lib/node_modules/@stdlib/math/strided/special/dmsksqrt/README.md

+305
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
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+
# dmsksqrt
22+
23+
> Compute the principal [square root][@stdlib/math/base/special/sqrt] for each element in a double-precision floating-point strided array according to a strided mask array.
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var dmsksqrt = require( '@stdlib/math/strided/special/dmsksqrt' );
37+
```
38+
39+
#### dmsksqrt( N, x, sx, m, sm, y, sy )
40+
41+
Computes the principal [square root][@stdlib/math/base/special/sqrt] for each element in a double-precision floating-point strided array according to a strided mask array.
42+
43+
```javascript
44+
var Float64Array = require( '@stdlib/array/float64' );
45+
var Uint8Array = require( '@stdlib/array/uint8' );
46+
47+
var x = new Float64Array( [ 0.0, 4.0, 9.0, 12.0, 24.0 ] );
48+
var m = new Uint8Array( [ 0, 0, 1, 0, 1 ] );
49+
var y = new Float64Array( x.length );
50+
51+
dmsksqrt( x.length, x, 1, m, 1, y, 1 );
52+
// y => <Float64Array>[ 0.0, 2.0, 0.0, ~3.464, 0.0 ]
53+
```
54+
55+
The function accepts the following arguments:
56+
57+
- **N**: number of indexed elements.
58+
- **x**: input [`Float64Array`][@stdlib/array/float64].
59+
- **sx**: index increment for `x`.
60+
- **m**: mask [`Uint8Array`][@stdlib/array/uint8].
61+
- **sm**: index increment for `m`.
62+
- **y**: output [`Float64Array`][@stdlib/array/float64].
63+
- **sy**: index increment for `y`.
64+
65+
The `N` and stride parameters determine which strided array elements are accessed at runtime. For example, to index every other value in `x` and to index the first `N` elements of `y` in reverse order,
66+
67+
```javascript
68+
var Float64Array = require( '@stdlib/array/float64' );
69+
var Uint8Array = require( '@stdlib/array/uint8' );
70+
71+
var x = new Float64Array( [ 0.0, 4.0, 9.0, 12.0, 24.0, 64.0 ] );
72+
var m = new Uint8Array( [ 0, 0, 1, 0, 1, 1 ] );
73+
var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
74+
75+
dmsksqrt( 3, x, 2, m, 2, y, -1 );
76+
// y => <Float64Array>[ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]
77+
```
78+
79+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][@stdlib/array/float64] views.
80+
81+
```javascript
82+
var Float64Array = require( '@stdlib/array/float64' );
83+
var Uint8Array = require( '@stdlib/array/uint8' );
84+
85+
// Initial arrays...
86+
var x0 = new Float64Array( [ 0.0, 4.0, 9.0, 12.0, 24.0, 64.0 ] );
87+
var m0 = new Uint8Array( [ 0, 0, 1, 0, 1, 1 ] );
88+
var y0 = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
89+
90+
// Create offset views...
91+
var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
92+
var m1 = new Uint8Array( m0.buffer, m0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
93+
var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element
94+
95+
dmsksqrt( 3, x1, -2, m1, -2, y1, 1 );
96+
// y0 => <Float64Array>[ 0.0, 0.0, 0.0, 0.0, ~3.464, 2.0 ]
97+
```
98+
99+
#### dmsksqrt.ndarray( N, x, sx, ox, m, sm, om, y, sy, oy )
100+
101+
Computes the principal [square root][@stdlib/math/base/special/sqrt] for each element in a double-precision floating-point strided array according to a strided mask array using alternative indexing semantics.
102+
103+
```javascript
104+
var Float64Array = require( '@stdlib/array/float64' );
105+
var Uint8Array = require( '@stdlib/array/uint8' );
106+
107+
var x = new Float64Array( [ 0.0, 4.0, 9.0, 12.0, 24.0 ] );
108+
var m = new Uint8Array( [ 0, 0, 1, 0, 1 ] );
109+
var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0 ] );
110+
111+
dmsksqrt.ndarray( x.length, x, 1, 0, m, 1, 0, y, 1, 0 );
112+
// y => <Float64Array>[ 0.0, 2.0, 0.0, ~3.464, 0.0 ]
113+
```
114+
115+
The function accepts the following additional arguments:
116+
117+
- **ox**: starting index for `x`.
118+
- **om**: starting index for `m`.
119+
- **oy**: starting index for `y`.
120+
121+
While [`typed array`][@stdlib/array/float64] views mandate a view offset based on the underlying `buffer`, the offset parameters support indexing semantics based on starting indices. For example, to index every other value in `x` starting from the second value and to index the last `N` elements in `y`,
122+
123+
```javascript
124+
var Float64Array = require( '@stdlib/array/float64' );
125+
var Uint8Array = require( '@stdlib/array/uint8' );
126+
127+
var x = new Float64Array( [ 0.0, 4.0, 9.0, 12.0, 24.0, 64.0 ] );
128+
var m = new Uint8Array( [ 0, 0, 1, 0, 1, 1 ] );
129+
var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
130+
131+
dmsksqrt.ndarray( 3, x, 2, 1, m, 2, 1, y, -1, y.length-1 );
132+
// y => <Float64Array>[ 0.0, 0.0, 0.0, 0.0, ~3.464, 2.0 ]
133+
```
134+
135+
</section>
136+
137+
<!-- /.usage -->
138+
139+
<section class="notes">
140+
141+
</section>
142+
143+
<!-- /.notes -->
144+
145+
<section class="examples">
146+
147+
## Examples
148+
149+
<!-- eslint no-undef: "error" -->
150+
151+
```javascript
152+
var uniform = require( '@stdlib/random/base/uniform' );
153+
var Float64Array = require( '@stdlib/array/float64' );
154+
var Uint8Array = require( '@stdlib/array/uint8' );
155+
var dmsksqrt = require( '@stdlib/math/strided/special/dmsksqrt' );
156+
157+
var x = new Float64Array( 10 );
158+
var m = new Uint8Array( 10 );
159+
var y = new Float64Array( 10 );
160+
161+
var i;
162+
for ( i = 0; i < x.length; i++ ) {
163+
x[ i ] = uniform( 0.0, 200.0 );
164+
if ( uniform( 0.0, 1.0 ) < 0.5 ) {
165+
m[ i ] = 1;
166+
}
167+
}
168+
console.log( x );
169+
console.log( m );
170+
console.log( y );
171+
172+
dmsksqrt.ndarray( x.length, x, 1, 0, m, 1, 0, y, -1, y.length-1 );
173+
console.log( y );
174+
```
175+
176+
</section>
177+
178+
<!-- /.examples -->
179+
180+
<!-- C interface documentation. -->
181+
182+
* * *
183+
184+
<section class="c">
185+
186+
## C APIs
187+
188+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
189+
190+
<section class="intro">
191+
192+
</section>
193+
194+
<!-- /.intro -->
195+
196+
<!-- C usage documentation. -->
197+
198+
<section class="usage">
199+
200+
### Usage
201+
202+
```c
203+
#include "stdlib/math/strided/special/dmsksqrt.h"
204+
```
205+
206+
#### stdlib_strided_dmsksqrt( N, \*X, strideX, \*Mask, strideMask, \*Y, strideY )
207+
208+
Computes the principal [square root][@stdlib/math/base/special/sqrt] for each element in a double-precision floating-point strided array according to a strided mask array.
209+
210+
```c
211+
#include <stdint.h>
212+
213+
double X[] = { 0.0, 4.0, 9.0, 12.0, 24.0, 64.0, 81.0, 101.0 };
214+
uint8_t Mask[] = { 0, 0, 1, 0, 1, 1, 0, 0 };
215+
double Y[] = { 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 };
216+
217+
int64_t N = 4;
218+
219+
stdlib_strided_dmsksqrt( N, X, 2, Mask, 2, Y, 2 );
220+
```
221+
222+
The function accepts the following arguments:
223+
224+
- **N**: `[in] int64_t` number of indexed elements.
225+
- **X**: `[in] double*` input array.
226+
- **strideX**: `[in] int64_t` index increment for `X`.
227+
- **Mask**: `[in] uint8_t*` input array.
228+
- **strideMask**: `[in] int64_t` index increment for `Mask`.
229+
- **Y**: `[out] double*` output array.
230+
- **strideY**: `[in] int64_t` index increment for `Y`.
231+
232+
```c
233+
void stdlib_strided_dmsksqrt( const int64_t N, const double *X, const int64_t strideX, const uint8_t *Mask, const int64_t strideMask, double *Y, const int64_t strideY );
234+
```
235+
236+
</section>
237+
238+
<!-- /.usage -->
239+
240+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
241+
242+
<section class="notes">
243+
244+
</section>
245+
246+
<!-- /.notes -->
247+
248+
<!-- C API usage examples. -->
249+
250+
<section class="examples">
251+
252+
### Examples
253+
254+
```c
255+
#include "stdlib/math/strided/special/dmsksqrt.h"
256+
#include <stdint.h>
257+
#include <stdio.h>
258+
259+
int main() {
260+
// Create an input strided array:
261+
double X[] = { 0.0, 4.0, 9.0, 12.0, 24.0, 64.0, 81.0, 101.0 };
262+
263+
// Create a mask strided array:
264+
uint8_t M[] = { 0, 0, 1, 0, 1, 1, 0, 0 };
265+
266+
// Create an output strided array:
267+
double Y[] = { 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 };
268+
269+
// Specify the number of elements:
270+
int64_t N = 4;
271+
272+
// Specify the stride lengths:
273+
int64_t strideX = 2;
274+
int64_t strideM = 2;
275+
int64_t strideY = 2;
276+
277+
// Compute the results:
278+
stdlib_strided_dmsksqrt( N, X, strideX, M, strideM, Y, strideY );
279+
280+
// Print the results:
281+
for ( int i = 0; i < 8; i++ ) {
282+
printf( "Y[ %i ] = %lf\n", i, Y[ i ] );
283+
}
284+
}
285+
```
286+
287+
</section>
288+
289+
<!-- /.examples -->
290+
291+
</section>
292+
293+
<!-- /.c -->
294+
295+
<section class="links">
296+
297+
[@stdlib/array/float64]: https://github.com/stdlib-js/stdlib
298+
299+
[@stdlib/math/base/special/sqrt]: https://github.com/stdlib-js/stdlib
300+
301+
[@stdlib/array/uint8]: https://github.com/stdlib-js/stdlib
302+
303+
</section>
304+
305+
<!-- /.links -->

0 commit comments

Comments
 (0)