Manipulating and restructuring arrays

Stefan ArrayFire Leave a Comment

One of the most common questions we see on the ArrayFire Google Group pertains to methods to manipulate the dimensions of ArrayFire array objects. Thus we will continue the "Learning ArrayFire from scratch" blog series by providing a detailed discussion of the numerous functions that permit you to change the dimentionality, flatten, flip, join, shift, transpose, and tile arrays.

ArrayFire provides several different methods for manipulating arrays and matrices. The functionality includes:

  • moddims() - change the dimensions of an array without changing the data
  • array() - create a (shallow) copy of an array with different dimensions.
  • flat() - flatten an array to one dimension
  • flip() - flip an array along a dimension
  • join() - join up to 4 arrays
  • reorder() - changes the dimension order within the array
  • shift() - shifts data along a dimension
  • tile() - repeats an array along a dimension
  • transpose() - performs a matrix transpose
  • T() - transpose a matrix or vector (shorthand notation)
  • H() - Hermitian Transpose (conjugate-transpose) a matrix

Below we provide several examples of these functions and their use. However, if you come to this page far in the future, we suggest you visit the documentation on this topic to see the latest information on these topics.

flat()

The flat() function flattens an array to one dimension:

The flat function can be called from C and C++ as follows:

flip()

The flip() function flips the contents of an array along a chosen dimension. In the example below, we show the 5x2 array flipped along the zeroth (i.e. within a column) and first (e.g. across rows) axes:

The flip function can be called from C and C++ as follows:

join()

The join() function joins arrays along a specific dimension. The C++ interface can join up to four arrays whereas the C interface supports up to 10 arrays. Here is an example of how to use join an array to itself:

The join function has several candidate functions in C:

and in C++:

moddims()

The moddims() function changes the dimensions of an array without changing its data or order. Note that this function modifies only the metadata associated with the array. It does not modify the content of the array. Here is an example of moddims() converting an 8x1 array into a 2x4 and then back to a 8x1:

The moddims function has a single form in the C API:

And several overloaded candidates in the C++ API:

reorder()

The reorder() function modifies the order of data within an array by exchanging data according to the change in dimensionality. The linear ordering of data within the array is preserved.

The reorder function has several candidates functions in the C/C++ APIs:

shift()

The shift() function shifts data in a circular buffer fashion along a chosen dimension. Consider the following example:

The shift function can be called from C and C++ as follows:

tile()

The tile() function repeats an array along the specified dimension. For example below we show how to tile an array along the zeroth and first dimensions of an array:

The C interface for tile is as follows:

The C++ interface has two overloads

transpose()

The transpose() function performs a standard matrix transpose. The input array must have the dimensions of a 2D-matrix.

The C interfaces for transpose are as follows:

The C++ interface has two primary functions and two shorthand versions:

Here is an example of how the shorthand versions might be used:

array()

array() can be used to create a (shallow) copy of a matrix with different dimensions. The total number of elements must remain the same. This function is a wrapper over the moddims() function discussed earlier.

Combining re-ordering functions to enumerate grid coordinates

By using a combination of the array restructuring functions, one can quickly code complex manipulation patterns with a few lines of code. For example, consider generating (x,y) coordinates for a grid where each axis goes from 1 to n. Instead of using several loops to populate our arrays we can just use a small combination of the above functions.

We hope you have found these instructions to be useful. As always, if you have questions about ArrayFire, feel free to drop us a line on the Google Group.

Facebooktwittergoogle_plusredditlinkedinmail