Skip to content

README.md

Latest commit

 

History

History
192 lines (125 loc) · 6.4 KB

README.md

File metadata and controls

192 lines (125 loc) · 6.4 KB
Raw

gcartesianSquare

Compute the Cartesian square for a strided array.

Usage

var gcartesianSquare = require( '@stdlib/blas/ext/base/gcartesian-square' );

gcartesianSquare( order, N, x, strideX, out, LDO )

Computes the Cartesian square 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 ];

gcartesianSquare( 'row-major', x.length, 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.
  • 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 and stride parameters determine which elements in the strided arrays are accessed at runtime. For example, to compute the Cartesian square 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 ];

gcartesianSquare( 'row-major', 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 );

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

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

Computes the Cartesian square 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 ];

gcartesianSquare.ndarray( x.length, 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.
  • 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 ];

gcartesianSquare.ndarray( 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

  • Pairs are stored as rows in the output matrix, where the first column contains the first element of each pair and the second column contains the second element.
  • For an input array of length N, the output array must contain at least N * N * 2 indexed elements.
  • For row-major order, the LDO parameter must be greater than or equal to 2. For column-major order, the LDO parameter must be greater than or equal to max(1,N*N).
  • If N <= 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 (dcartesianSquare, scartesianSquare, etc.) are likely to be significantly more performant.

Examples

var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var zeros = require( '@stdlib/array/zeros' );
var gcartesianSquare = require( '@stdlib/blas/ext/base/gcartesian-square' );

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

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