Skip to content

Commit 175ab01

Browse files
headlessNodeheadlessNode
committed
feat: add blas/ext/base/scartesian-power
1 parent be59f0c commit 175ab01

33 files changed

Lines changed: 4610 additions & 0 deletions

‎lib/node_modules/@stdlib/blas/ext/base/scartesian-power/README.md‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
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+
# scartesianPower
22+
23+
> Compute the Cartesian power for a single-precision floating-point strided array.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var scartesianPower = require( '@stdlib/blas/ext/base/scartesian-power' );
31+
```
32+
33+
#### scartesianPower( order, N, k, x, strideX, out, LDO )
34+
35+
Computes the Cartesian power for a single-precision floating-point strided array.
36+
37+
```javascript
38+
var Float32Array = require( '@stdlib/array/float32' );
39+
40+
var x = new Float32Array( [ 1.0, 2.0 ] );
41+
var out = new Float32Array( 8 );
42+
43+
scartesianPower( 'row-major', x.length, 2, x, 1, out, 2 );
44+
// out => <Float32Array>[ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]
45+
```
46+
47+
The function has the following parameters:
48+
49+
- **order**: storage layout. Must be either `'row-major'` or `'column-major'`.
50+
- **N**: number of indexed elements.
51+
- **k**: power.
52+
- **x**: input [`Float32Array`][@stdlib/array/float32].
53+
- **strideX**: stride length for `x`.
54+
- **out**: output [`Float32Array`][@stdlib/array/float32].
55+
- **LDO**: stride length between successive contiguous vectors of the matrix `out` (a.k.a., leading dimension of `out`).
56+
57+
The `N`, `k`, and stride parameters determine which elements in the strided arrays are accessed at runtime. For example, to compute the Cartesian power of every other element:
58+
59+
```javascript
60+
var Float32Array = require( '@stdlib/array/float32' );
61+
62+
var x = new Float32Array( [ 1.0, 0.0, 2.0, 0.0 ] );
63+
var out = new Float32Array( 8 );
64+
65+
scartesianPower( 'row-major', 2, 2, x, 2, out, 2 );
66+
// out => <Float32Array>[ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]
67+
```
68+
69+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
70+
71+
```javascript
72+
var Float32Array = require( '@stdlib/array/float32' );
73+
74+
// Initial array:
75+
var x0 = new Float32Array( [ 0.0, 1.0, 2.0, 3.0 ] );
76+
77+
// Create an offset view:
78+
var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
79+
80+
// Output array:
81+
var out = new Float32Array( 8 );
82+
83+
scartesianPower( 'row-major', 2, 2, x1, 1, out, 2 );
84+
// out => <Float32Array>[ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]
85+
```
86+
87+
<!-- lint disable maximum-heading-length -->
88+
89+
#### scartesianPower.ndarray( N, k, x, strideX, offsetX, out, strideOut1, strideOut2, offsetOut )
90+
91+
<!-- lint enable maximum-heading-length -->
92+
93+
Computes the Cartesian power for a single-precision floating-point strided array using alternative indexing semantics.
94+
95+
```javascript
96+
var Float32Array = require( '@stdlib/array/float32' );
97+
98+
var x = new Float32Array( [ 1.0, 2.0 ] );
99+
var out = new Float32Array( 8 );
100+
101+
scartesianPower.ndarray( x.length, 2, x, 1, 0, out, 2, 1, 0 );
102+
// out => <Float32Array>[ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]
103+
```
104+
105+
The function has the following parameters:
106+
107+
- **N**: number of indexed elements.
108+
- **k**: power.
109+
- **x**: input [`Float32Array`][@stdlib/array/float32].
110+
- **strideX**: stride length for `x`.
111+
- **offsetX**: starting index for `x`.
112+
- **out**: output [`Float32Array`][@stdlib/array/float32].
113+
- **strideOut1**: stride length of the first dimension of `out`.
114+
- **strideOut2**: stride length of the second dimension of `out`.
115+
- **offsetOut**: starting index for `out`.
116+
117+
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameters support indexing semantics based on starting indices. For example, to access only the last two elements:
118+
119+
```javascript
120+
var Float32Array = require( '@stdlib/array/float32' );
121+
122+
var x = new Float32Array( [ 0.0, 0.0, 1.0, 2.0 ] );
123+
var out = new Float32Array( 8 );
124+
125+
scartesianPower.ndarray( 2, 2, x, 1, 2, out, 2, 1, 0 );
126+
// out => <Float32Array>[ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]
127+
```
128+
129+
</section>
130+
131+
<!-- /.usage -->
132+
133+
<section class="notes">
134+
135+
## Notes
136+
137+
- `k`-tuples are stored as rows in the output matrix, where the `j`-th column contains the `j`-th element of each tuple.
138+
- For an input array of length `N`, the output array must contain at least `N^k * k` indexed elements.
139+
- For row-major order, the `LDO` parameter must be greater than or equal to `max(1,k)`. For column-major order, the `LDO` parameter must be greater than or equal to `max(1,N^k)`.
140+
- If `N <= 0` or `k <= 0`, both functions return `out` unchanged.
141+
142+
</section>
143+
144+
<!-- /.notes -->
145+
146+
<section class="examples">
147+
148+
## Examples
149+
150+
<!-- eslint no-undef: "error" -->
151+
152+
```javascript
153+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
154+
var Float32Array = require( '@stdlib/array/float32' );
155+
var pow = require( '@stdlib/math/base/special/pow' );
156+
var scartesianPower = require( '@stdlib/blas/ext/base/scartesian-power' );
157+
158+
var N = 2;
159+
var k = 3;
160+
var x = discreteUniform( N, 1, 10, {
161+
'dtype': 'float32'
162+
});
163+
console.log( x );
164+
165+
var out = new Float32Array( pow( N, k ) * k );
166+
scartesianPower( 'row-major', N, k, x, 1, out, k );
167+
console.log( out );
168+
```
169+
170+
</section>
171+
172+
<!-- /.examples -->
173+
174+
<!-- C interface documentation. -->
175+
176+
* * *
177+
178+
<section class="c">
179+
180+
## C APIs
181+
182+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
183+
184+
<section class="intro">
185+
186+
</section>
187+
188+
<!-- /.intro -->
189+
190+
<!-- C usage documentation. -->
191+
192+
<section class="usage">
193+
194+
### Usage
195+
196+
```c
197+
#include "stdlib/blas/ext/base/scartesianpower.h"
198+
```
199+
200+
#### stdlib_strided_scartesian_power( order, N, k, \*X, strideX, \*Out, LDO )
201+
202+
Computes the Cartesian power for a single-precision floating-point strided array.
203+
204+
```c
205+
#include "stdlib/blas/base/shared.h"
206+
207+
const float x[] = { 1.0f, 2.0f };
208+
float out[ 8 ];
209+
210+
stdlib_strided_scartesian_power( CblasRowMajor, 2, 2, x, 1, out, 2 );
211+
```
212+
213+
The function accepts the following arguments:
214+
215+
- **order**: `[in] CBLAS_LAYOUT` storage layout.
216+
- **N**: `[in] CBLAS_INT` number of indexed elements.
217+
- **k**: `[in] CBLAS_INT` power.
218+
- **X**: `[in] float*` input array.
219+
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
220+
- **Out**: `[out] float*` output array.
221+
- **LDO**: `[in] CBLAS_INT` stride length between successive contiguous vectors of the matrix `Out` (a.k.a., leading dimension of `Out`). For row-major order, must be greater than or equal to `max(1,k)`. For column-major order, must be greater than or equal to `max(1,N^k)`.
222+
223+
```c
224+
void stdlib_strided_scartesian_power( const CBLAS_LAYOUT order, const CBLAS_INT N, const CBLAS_INT k, const float *X, const CBLAS_INT strideX, float *Out, const CBLAS_INT LDO );
225+
```
226+
227+
<!-- lint disable maximum-heading-length -->
228+
229+
#### stdlib_strided_scartesian_power_ndarray( N, k, \*X, strideX, offsetX, \*Out, strideOut1, strideOut2, offsetOut )
230+
231+
<!-- lint enable maximum-heading-length -->
232+
233+
Computes the Cartesian power for a single-precision floating-point strided array using alternative indexing semantics.
234+
235+
```c
236+
const float x[] = { 1.0f, 2.0f };
237+
float out[ 8 ];
238+
239+
stdlib_strided_scartesian_power_ndarray( 2, 2, x, 1, 0, out, 2, 1, 0 );
240+
```
241+
242+
The function accepts the following arguments:
243+
244+
- **N**: `[in] CBLAS_INT` number of indexed elements.
245+
- **k**: `[in] CBLAS_INT` power.
246+
- **X**: `[in] float*` input array.
247+
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
248+
- **offsetX**: `[in] CBLAS_INT` starting index for `X`.
249+
- **Out**: `[out] float*` output array.
250+
- **strideOut1**: `[in] CBLAS_INT` stride length of the first dimension of `Out`.
251+
- **strideOut2**: `[in] CBLAS_INT` stride length of the second dimension of `Out`.
252+
- **offsetOut**: `[in] CBLAS_INT` starting index for `Out`.
253+
254+
```c
255+
void stdlib_strided_scartesian_power_ndarray( const CBLAS_INT N, const CBLAS_INT k, const float *X, const CBLAS_INT strideX, const CBLAS_INT offsetX, float *Out, const CBLAS_INT strideOut1, const CBLAS_INT strideOut2, const CBLAS_INT offsetOut );
256+
```
257+
258+
</section>
259+
260+
<!-- /.usage -->
261+
262+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
263+
264+
<section class="notes">
265+
266+
</section>
267+
268+
<!-- /.notes -->
269+
270+
<!-- C API usage examples. -->
271+
272+
<section class="examples">
273+
274+
### Examples
275+
276+
```c
277+
#include "stdlib/blas/ext/base/scartesianpower.h"
278+
#include "stdlib/blas/base/shared.h"
279+
#include <stdio.h>
280+
#include <math.h>
281+
282+
int main( void ) {
283+
// Create a strided input array:
284+
const float x[] = { 1.0f, 2.0f };
285+
286+
// Specify the number of indexed elements and power:
287+
const int N = 2;
288+
const int k = 2;
289+
290+
// Create an output array (N^k tuples, each tuple has k elements):
291+
float out[ 8 ];
292+
293+
// Specify strides:
294+
const int strideX = 1;
295+
const int LDO = 2;
296+
297+
// Compute the Cartesian power:
298+
stdlib_strided_scartesian_power( CblasRowMajor, N, k, x, strideX, out, LDO );
299+
300+
// Print the result:
301+
const int len = (int)pow( N, k );
302+
for ( int i = 0; i < len; i++ ) {
303+
printf( "out[ %i ] = ( %f, %f )\n", i, out[ i*2 ], out[ (i*2)+1 ] );
304+
}
305+
}
306+
```
307+
308+
</section>
309+
310+
<!-- /.examples -->
311+
312+
</section>
313+
314+
<!-- /.c -->
315+
316+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
317+
318+
<section class="related">
319+
320+
</section>
321+
322+
<!-- /.related -->
323+
324+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
325+
326+
<section class="links">
327+
328+
[@stdlib/array/float32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/float32
329+
330+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
331+
332+
</section>
333+
334+
<!-- /.links -->

0 commit comments

Comments
 (0)