Skip to content

README.md

Latest commit

 

History

History
143 lines (91 loc) · 5.21 KB

README.md

File metadata and controls

143 lines (91 loc) · 5.21 KB

circshift

Circularly shift the elements of an input ndarray by a specified number of positions along one or more ndarray dimensions.

Usage

var circshift = require( '@stdlib/blas/ext/circshift' );

circshift( x, k[, options] )

Circularly shifts the elements of an input ndarray by a specified number of positions along one or more ndarray dimensions.

var array = require( '@stdlib/ndarray/array' );

var x = array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
// returns <ndarray>[ 1.0, 2.0, 3.0, 4.0, 5.0 ]

var y = circshift( x, 2 );
// returns <ndarray>[ 4.0, 5.0, 1.0, 2.0, 3.0 ]

var bool = ( x === y );
// returns true

The function has the following parameters:

  • x: input ndarray.
  • k: number of positions to shift. May be either an integer scalar value or an ndarray having a real-valued or "generic" data type. If provided an ndarray, the value must have a shape which is broadcast-compatible with the complement of the shape defined by options.dims. For example, given the input shape [2, 3, 4] and options.dims=[0], an ndarray for k must have a shape which is broadcast-compatible with the shape [3, 4]. Similarly, when performing the operation over all elements in a provided input ndarray, an ndarray for k must be a zero-dimensional ndarray.
  • options: function options (optional).

The function accepts the following options:

  • dims: list of dimensions over which to perform operation. If not provided, the function performs the operation over all elements in a provided input ndarray.

By default, the function circularly shifts all elements. To perform the operation over specific dimensions, provide a dims option.

var array = require( '@stdlib/ndarray/array' );

var x = array( [ 1.0, 2.0, 3.0, 4.0 ], {
    'shape': [ 2, 2 ],
    'order': 'row-major'
});
// returns <ndarray>[ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ]

var y = circshift( x, 1, {
    'dims': [ 0 ]
});
// returns <ndarray>[ [ 3.0, 4.0 ], [ 1.0, 2.0 ] ]

Notes

  • The input ndarray is shifted in-place (i.e., the input ndarray is mutated).
  • When shifting elements along a single dimension, a positive k shifts elements to the right (toward higher indices), and a negative k shifts elements to the left (toward lower indices). If k is zero, the input ndarray is left unchanged.
  • The function iterates over ndarray elements according to the memory layout of the input ndarray. Accordingly, performance degradation is possible when operating over multiple dimensions of a large non-contiguous multi-dimensional input ndarray. In such scenarios, one may want to copy an input ndarray to contiguous memory before performing the circular shift.

Examples

var discreteUniform = require( '@stdlib/random/discrete-uniform' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var circshift = require( '@stdlib/blas/ext/circshift' );

// Generate an ndarray of random numbers:
var x = discreteUniform( [ 5, 5 ], -20, 20, {
    'dtype': 'generic'
});
console.log( ndarray2array( x ) );

// Perform operation:
circshift( x, 2, {
    'dims': [ 0 ]
});

// Print the results:
console.log( ndarray2array( x ) );