Skip to content

Commit 0c6b686

Browse files
rreusserrreusser
committed
feat: add blas/base/zdscal
1 parent abf124e commit 0c6b686

40 files changed

+5152
-0
lines changed

‎lib/node_modules/@stdlib/blas/base/zdscal/README.md‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2024 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+
# zdscal
22+
23+
> Scales a double-precision complex floating-point vector by a double-precision floating-point constant.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var zdscal = require( '@stdlib/blas/base/zdscal' );
31+
```
32+
33+
#### zdscal( N, da, zx, strideX )
34+
35+
Scales values from `zx` by `da`.
36+
37+
```javascript
38+
var Complex128Array = require( '@stdlib/array/complex128' );
39+
var real = require( '@stdlib/complex/float64/real' );
40+
var imag = require( '@stdlib/complex/float64/imag' );
41+
42+
var zx = new Complex128Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
43+
var da = 2.0;
44+
45+
zdscal( 3, da, zx, 1 );
46+
47+
var z = zx.get( 0 );
48+
// returns <Complex128>
49+
50+
var re = real( z );
51+
// returns 2.0
52+
53+
var im = imag( z );
54+
// returns 2.0
55+
```
56+
57+
The function has the following parameters:
58+
59+
- **N**: number of indexed elements.
60+
- **da**: scalar constant.
61+
- **zx**: input [`Complex128Array`][@stdlib/array/complex128].
62+
- **strideX**: index increment for `zx`.
63+
64+
The `N` and stride parameters determine how values from `zx` are scaled by `da`. For example, to scale every other value in `zx` by `da`,
65+
66+
```javascript
67+
var Complex128Array = require( '@stdlib/array/complex128' );
68+
var real = require( '@stdlib/complex/float64/real' );
69+
var imag = require( '@stdlib/complex/float64/imag' );
70+
71+
var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
72+
var da = 2.0;
73+
74+
zdscal( 2, da, zx, 2 );
75+
76+
var z = zx.get( 2 );
77+
// returns <Complex128>
78+
79+
var re = real( z );
80+
// returns 10.0
81+
82+
var im = imag( z );
83+
// returns 12.0
84+
```
85+
86+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
87+
88+
<!-- eslint-disable stdlib/capitalized-comments -->
89+
90+
```javascript
91+
var Complex128Array = require( '@stdlib/array/complex128' );
92+
var real = require( '@stdlib/complex/float64/real' );
93+
var imag = require( '@stdlib/complex/float64/imag' );
94+
95+
// Initial array:
96+
var zx0 = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
97+
98+
// Define a scalar constant:
99+
var da = 2.0;
100+
101+
// Create an offset view:
102+
var zx1 = new Complex128Array( zx0.buffer, zx0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
103+
104+
// Scales every other value from `zx1` by `da`...
105+
zdscal( 3, da, zx1, 1 );
106+
107+
var z = zx0.get( 1 );
108+
// returns <Complex128>
109+
110+
var re = real( z );
111+
// returns -2.0
112+
113+
var im = imag( z );
114+
// returns 14.0
115+
```
116+
117+
#### zdscal.ndarray( N, da, zx, strideX, offsetX )
118+
119+
Scales values from `zx` by `da` using alternative indexing semantics.
120+
121+
```javascript
122+
var Complex128Array = require( '@stdlib/array/complex128' );
123+
var real = require( '@stdlib/complex/float64/real' );
124+
var imag = require( '@stdlib/complex/float64/imag' );
125+
126+
var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
127+
var da = 2.0;
128+
129+
zdscal.ndarray( 3, da, zx, 1, 0 );
130+
131+
var z = zx.get( 0 );
132+
// returns <Complex128>
133+
134+
var re = real( z );
135+
// returns -2.0
136+
137+
var im = imag( z );
138+
// returns 6.0
139+
```
140+
141+
The function has the following additional parameters:
142+
143+
- **offsetX**: starting index for `zx`.
144+
145+
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to scale every other value in the input strided array starting from the second element,
146+
147+
```javascript
148+
var Complex128Array = require( '@stdlib/array/complex128' );
149+
var real = require( '@stdlib/complex/float64/real' );
150+
var imag = require( '@stdlib/complex/float64/imag' );
151+
152+
var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
153+
var da = 2.0;
154+
155+
zdscal.ndarray( 2, da, zx, 2, 1 );
156+
157+
var z = zx.get( 3 );
158+
// returns <Complex128>
159+
160+
var re = real( z );
161+
// returns -2.0
162+
163+
var im = imag( z );
164+
// returns 30.0
165+
```
166+
167+
</section>
168+
169+
<!-- /.usage -->
170+
171+
<section class="notes">
172+
173+
## Notes
174+
175+
- If `N <= 0` or `strideX <= 0` , both functions return `zx` unchanged.
176+
- `zdscal()` corresponds to the [BLAS][blas] level 1 function [`zdscal`][zdscal].
177+
178+
</section>
179+
180+
<!-- /.notes -->
181+
182+
<section class="examples">
183+
184+
## Examples
185+
186+
<!-- eslint no-undef: "error" -->
187+
188+
```javascript
189+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
190+
var filledarrayBy = require( '@stdlib/array/filled-by' );
191+
var Complex128 = require( '@stdlib/complex/float64/ctor' );
192+
var zdscal = require( '@stdlib/blas/base/zdscal' );
193+
194+
function rand() {
195+
return new Complex128( discreteUniform( 0, 10 ), discreteUniform( -5, 5 ) );
196+
}
197+
198+
var zx = filledarrayBy( 10, 'complex128', rand );
199+
console.log( zx.toString() );
200+
201+
var da = 2.0;
202+
console.log( da ) );
203+
204+
// Scales elements from `zx` by `da`:
205+
zdscal( zx.length, da, zx, 1 );
206+
console.log( zx.get( zx.length-1 ).toString() );
207+
```
208+
209+
</section>
210+
211+
<!-- /.examples -->
212+
213+
<!-- C interface documentation. -->
214+
215+
* * *
216+
217+
<section class="c">
218+
219+
## C APIs
220+
221+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
222+
223+
<section class="intro">
224+
225+
</section>
226+
227+
<!-- /.intro -->
228+
229+
<!-- C usage documentation. -->
230+
231+
<section class="usage">
232+
233+
### Usage
234+
235+
```c
236+
#include "stdlib/blas/base/zdscal.h"
237+
```
238+
239+
#### c_zdscal( N, da, \*ZX, strideX )
240+
241+
Scales values from `ZX` by `da`.
242+
243+
```c
244+
#include "stdlib/complex/float64/ctor.h"
245+
246+
double zx[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
247+
const stdlib_complex128_t da = stdlib_complex128( 2.0, 2.0 );
248+
249+
c_zdscal( 4, da, (void *)zx, 1 );
250+
```
251+
252+
The function accepts the following arguments:
253+
254+
- **N**: `[in] CBLAS_INT` number of indexed elements.
255+
- **da**: `[in] stdlib_complex128_t` scalar constant.
256+
- **ZX**: `[inout] void*` input array.
257+
- **strideX**: `[in] CBLAS_INT` index increment for `ZX`.
258+
259+
```c
260+
void c_zdscal( const CBLAS_INT N, const stdlib_complex128_t da, void *ZX, const CBLAS_INT strideX );
261+
```
262+
263+
</section>
264+
265+
<!-- /.usage -->
266+
267+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
268+
269+
<section class="notes">
270+
271+
</section>
272+
273+
<!-- /.notes -->
274+
275+
<!-- C API usage examples. -->
276+
277+
<section class="examples">
278+
279+
### Examples
280+
281+
```c
282+
#include "stdlib/blas/base/zdscal.h"
283+
#include "stdlib/complex/float64/ctor.h"
284+
#include <stdio.h>
285+
286+
int main( void ) {
287+
// Create a strided array of interleaved real and imaginary components:
288+
double zx[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
289+
290+
// Create a complex scalar:
291+
const stdlib_complex128_t ca = stdlib_complex128( 2.0, 2.0 );
292+
293+
// Specify the number of elements:
294+
const int N = 4;
295+
296+
// Specify stride length:
297+
const int strideX = 1;
298+
299+
// Scale the elements of the array:
300+
c_zdscal( N, da, (void *)zx, strideX );
301+
302+
// Print the result:
303+
for ( int i = 0; i < N; i++ ) {
304+
printf( "zx[ %i ] = %f + %fj\n", i, zx[ i*2 ], zx[ (i*2)+1 ] );
305+
}
306+
}
307+
```
308+
309+
</section>
310+
311+
<!-- /.examples -->
312+
313+
</section>
314+
315+
<!-- /.c -->
316+
317+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
318+
319+
<section class="related">
320+
321+
</section>
322+
323+
<!-- /.related -->
324+
325+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
326+
327+
<section class="links">
328+
329+
[blas]: http://www.netlib.org/blas
330+
331+
[zdscal]: https://www.netlib.org/lapack/explore-html/d2/de8/group__scal_ga40d50a435a5fcf16cf41fa80d746819f.html#ga40d50a435a5fcf16cf41fa80d746819f
332+
333+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
334+
335+
[@stdlib/array/complex128]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/complex128
336+
337+
[@stdlib/complex/float64/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/complex/float64/ctor
338+
339+
</section>
340+
341+
<!-- /.links -->

0 commit comments

Comments
 (0)