Skip to content

README.md

Latest commit

 

History

History
192 lines (127 loc) · 6.44 KB

README.md

File metadata and controls

192 lines (127 loc) · 6.44 KB

gcartesianPower

Compute the Cartesian power for a strided array.

Usage

var gcartesianPower = require( '@stdlib/blas/ext/base/gcartesian-power' );

gcartesianPower( order, N, k, x, strideX, out, LDO )

Computes the Cartesian power for a strided array.

var x = [ 1.0, 2.0 ];
var out = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ];

gcartesianPower( 'row-major', x.length, 2, x, 1, out, 2 );
// out => [ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]

The function has the following parameters:

  • order: storage layout. Must be either 'row-major' or 'column-major'.
  • N: number of indexed elements.
  • k: power.
  • x: input Array or typed array.
  • strideX: stride length for x.
  • out: output Array or typed array.
  • LDO: stride length between successive contiguous vectors of the matrix out (a.k.a., leading dimension of out).

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:

var x = [ 1.0, 0.0, 2.0, 0.0 ];
var out = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ];

gcartesianPower( 'row-major', 2, 2, x, 2, out, 2 );
// out => [ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]

Note that indexing is relative to the first index. To introduce an offset, use typed array views.

var Float64Array = require( '@stdlib/array/float64' );

// Initial array:
var x0 = new Float64Array( [ 0.0, 1.0, 2.0, 3.0 ] );

// Create an offset view:
var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element

// Output array:
var out = new Float64Array( 8 );

gcartesianPower( 'row-major', 2, 2, x1, 1, out, 2 );
// out => <Float64Array>[ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]

gcartesianPower.ndarray( N, k, x, strideX, offsetX, out, strideOut1, strideOut2, offsetOut )

Computes the Cartesian power for a strided array using alternative indexing semantics.

var x = [ 1.0, 2.0 ];
var out = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ];

gcartesianPower.ndarray( x.length, 2, x, 1, 0, out, 2, 1, 0 );
// out => [ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]

The function has the following parameters:

  • N: number of indexed elements.
  • k: power.
  • x: input Array or typed array.
  • strideX: stride length for x.
  • offsetX: starting index for x.
  • out: output Array or typed array.
  • strideOut1: stride length for the first dimension of out.
  • strideOut2: stride length for the second dimension of out.
  • offsetOut: starting index for out.

While 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:

var x = [ 0.0, 0.0, 1.0, 2.0 ];
var out = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ];

gcartesianPower.ndarray( 2, 2, x, 1, 2, out, 2, 1, 0 );
// out => [ 1.0, 1.0, 1.0, 2.0, 2.0, 1.0, 2.0, 2.0 ]

Notes

  • k-tuples are stored as rows in the output matrix, where the j-th column contains the j-th element of each tuple.
  • For an input array of length N, the output array must contain at least N^k * k indexed elements.
  • 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).
  • If N <= 0 or k <= 0, both functions return out unchanged.
  • Both functions support array-like objects having getter and setter accessors for array element access (e.g., @stdlib/array/base/accessor).
  • Depending on the environment, the typed versions (dcartesianPower, scartesianPower, etc.) are likely to be significantly more performant.

Examples

var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var zeros = require( '@stdlib/array/zeros' );
var pow = require( '@stdlib/math/base/special/pow' );
var gcartesianPower = require( '@stdlib/blas/ext/base/gcartesian-power' );

var N = 2;
var k = 3;
var x = discreteUniform( N, 1, 10, {
    'dtype': 'generic'
});
console.log( x );

var out = zeros( pow( N, k ) * k, 'generic' );
gcartesianPower( 'row-major', N, k, x, 1, out, k );
console.log( out );