Skip to content

Commit c3773d9

Browse files
anandkaranubcanandkaranubc
authored
feat: add blas/ext/base/zaxpb
PR-URL: #12342 Reviewed-by: Athan Reines <kgryte@gmail.com> Closes: stdlib-js/metr-issue-tracker#633
1 parent 4610fde commit c3773d9

33 files changed

Lines changed: 4583 additions & 0 deletions

‎lib/node_modules/@stdlib/blas/ext/base/zaxpb/README.md‎

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

0 commit comments

Comments
 (0)