Array Manipulation Routines

Basic manipulations

cupy.copyto(dst, src, casting='same_kind', where=None)[source]

Copies values from one array to another with broadcasting.

This function can be called for arrays on different devices. In this case, casting, where, and broadcasting is not supported, and an exception is raised if these are used.

Parameters:
  • dst (cupy.ndarray) – Target array.
  • src (cupy.ndarray) – Source array.
  • casting (str) – Casting rule. See numpy.can_cast() for detail.
  • where (cupy.ndarray of bool) – If specified, this array acts as a mask, and an element is copied only if the corresponding element of where is True.

See also

numpy.copyto()

Shape manipulation

cupy.reshape(a, newshape)[source]

Returns an array with new shape and same elements.

It tries to return a view if possible, otherwise returns a copy.

This function currently does not support order option.

Parameters:
  • a (cupy.ndarray) – Array to be reshaped.
  • newshape (int or tuple of ints) – The new shape of the array to return. If it is an integer, then it is treated as a tuple of length one. It should be compatible with a.size. One of the elements can be -1, which is automatically replaced with the appropriate value to make the shape compatible with a.size.
Returns:

A reshaped view of a if possible, otherwise a copy.
Return type:

cupy.ndarray

See also

numpy.reshape()

cupy.ravel(a)[source]

Returns a flattened array.

It tries to return a view if possible, otherwise returns a copy.

This function currently does not support order option.

Parameters:a (cupy.ndarray) – Array to be flattened.
Returns:A flattened view of a if possible, otherwise a copy.
Return type:cupy.ndarray

See also

numpy.ravel()

Transposition

cupy.rollaxis(a, axis, start=0)[source]

Moves the specified axis backwards to the given place.

Parameters:
  • a (cupy.ndarray) – Array to move the axis.
  • axis (int) – The axis to move.
  • start (int) – The place to which the axis is moved.
Returns:

A view of a that the axis is moved to start.
Return type:

cupy.ndarray

See also

numpy.rollaxis()

cupy.swapaxes(a, axis1, axis2)[source]

Swaps the two axes.

Parameters:
  • a (cupy.ndarray) – Array to swap the axes.
  • axis1 (int) – The first axis to swap.
  • axis2 (int) – The second axis to swap.
Returns:

A view of a that the two axes are swapped.
Return type:

cupy.ndarray

See also

numpy.swapaxes()

cupy.transpose(a, axes=None)[source]

Permutes the dimensions of an array.

Parameters:
  • a (cupy.ndarray) – Array to permute the dimensions.
  • axes (tuple of ints) – Permutation of the dimensions. This function reverses the shape by default.
Returns:

A view of a that the dimensions are permuted.
Return type:

cupy.ndarray

See also

numpy.transpose()

Edit dimensionalities

cupy.atleast_1d(*arys)[source]

Converts arrays to arrays with dimensions >= 1.

Parameters:arys (tuple of arrays) – Arrays to be converted. All arguments must be cupy.ndarray objects. Only zero-dimensional array is affected.
Returns:If there are only one input, then it returns its converted version. Otherwise, it returns a list of converted arrays.

See also

numpy.atleast_1d()

cupy.atleast_2d(*arys)[source]

Converts arrays to arrays with dimensions >= 2.

If an input array has dimensions less than two, then this function inserts new axes at the head of dimensions to make it have two dimensions.

Parameters:arys (tuple of arrays) – Arrays to be converted. All arguments must be cupy.ndarray objects.
Returns:If there are only one input, then it returns its converted version. Otherwise, it returns a list of converted arrays.

See also

numpy.atleast_2d()

cupy.atleast_3d(*arys)[source]

Converts arrays to arrays with dimensions >= 3.

If an input array has dimensions less than three, then this function inserts new axes to make it have three dimensions. The place of the new axes are following:

  • If its shape is (), then the shape of output is (1, 1, 1).
  • If its shape is (N,), then the shape of output is (1, N, 1).
  • If its shape is (M, N), then the shape of output is (M, N, 1).
  • Otherwise, the output is the input array itself.
Parameters:arys (tuple of arrays) – Arrays to be converted. All arguments must be cupy.ndarray objects.
Returns:If there are only one input, then it returns its converted version. Otherwise, it returns a list of converted arrays.

See also

numpy.atleast_3d()

class cupy.broadcast

Object that performs broadcasting.

CuPy actually uses this class to support broadcasting in various operations. Note that this class does not provide an iterator.

Parameters:

arrays (tuple of arrays) – Arrays to be broadcasted.
Variables:
  • shape (tuple of ints) – The broadcasted shape.
  • nd (int) – Number of dimensions of the broadcasted shape.
  • size (int) – Total size of the broadcasted shape.
  • values (list of arrays) – The broadcasted arrays.

See also

numpy.broadcast

cupy.broadcast_arrays(*args)[source]

Broadcasts given arrays.

Parameters:args (tuple of arrays) – Arrays to broadcast for each other.
Returns:A list of broadcasted arrays.
Return type:list

See also

numpy.broadcast_arrays()

cupy.broadcast_to(array, shape)[source]

Broadcast an array to a given shape.

Parameters:
  • array (cupy.ndarray) – Array to broadcast.
  • shape (tuple of int) – The shape of the desired array.
Returns:

Broadcasted view.
Return type:

cupy.ndarray

See also

numpy.broadcast_to()

cupy.expand_dims(a, axis)[source]

Expands given arrays.

Parameters:
  • a (cupy.ndarray) – Array to be expanded.
  • axis (int) – Position where new axis is to be inserted.
Returns:

The number of dimensions is one greater than that of

the input array.
Return type:

cupy.ndarray

See also

numpy.expand_dims()

cupy.squeeze(a, axis=None)[source]

Removes size-one axes from the shape of an array.

Parameters:
  • a (cupy.ndarray) – Array to be reshaped.
  • axis (int or tuple of ints) – Axes to be removed. This function removes all size-one axes by default. If one of the specified axes is not of size one, an exception is raised.
Returns:

An array without (specified) size-one axes.
Return type:

cupy.ndarray

See also

numpy.squeeze()

Changing kind of array

cupy.asfortranarray(a, dtype=None)[source]

Return an array laid out in Fortran order in memory.

Parameters:
  • a (ndarray) – The input array.
  • dtype (str or dtype object, optional) – By default, the data-type is inferred from the input data.
Returns:

The input a in Fortran, or column-major, order.
Return type:

ndarray

See also

numpy.asfortranarray()

Joining arrays along axis

cupy.column_stack(tup)[source]

Stacks 1-D and 2-D arrays as columns into a 2-D array.

A 1-D array is first converted to a 2-D column array. Then, the 2-D arrays are concatenated along the second axis.

Parameters:tup (sequence of arrays) – 1-D or 2-D arrays to be stacked.
Returns:A new 2-D array of stacked columns.
Return type:cupy.ndarray

See also

numpy.column_stack()

cupy.concatenate(tup, axis=0)[source]

Joins arrays along an axis.

Parameters:
  • tup (sequence of arrays) – Arrays to be joined. All of these should have same dimensionalities except the specified axis.
  • axis (int) – The axis to join arrays along.
Returns:

Joined array.
Return type:

cupy.ndarray

See also

numpy.concatenate()

cupy.vstack(tup)[source]

Stacks arrays vertically.

If an input array has one dimension, then the array is treated as a horizontal vector and stacked along the additional axis at the head. Otherwise, the array is stacked along the first axis.

Parameters:tup (sequence of arrays) – Arrays to be stacked. Each array is converted by cupy.atleast_2d() before stacking.
Returns:Stacked array.
Return type:cupy.ndarray

See also

numpy.dstack()

cupy.hstack(tup)[source]

Stacks arrays horizontally.

If an input array has one dimension, then the array is treated as a horizontal vector and stacked along the first axis. Otherwise, the array is stacked along the second axis.

Parameters:tup (sequence of arrays) – Arrays to be stacked.
Returns:Stacked array.
Return type:cupy.ndarray

See also

numpy.hstack()

cupy.dstack(tup)[source]

Stacks arrays along the third axis.

Parameters:tup (sequence of arrays) – Arrays to be stacked. Each array is converted by cupy.atleast_3d() before stacking.
Returns:Stacked array.
Return type:cupy.ndarray

See also

numpy.dstack()

cupy.stack(tup, axis=0)[source]

Stacks arrays along a new axis.

Parameters:
  • tup (sequence of arrays) – Arrays to be stacked.
  • axis (int) – Axis along which the arrays are stacked.
Returns:

Stacked array.
Return type:

cupy.ndarray

See also

numpy.stack()

Splitting arrays along axis

cupy.array_split(ary, indices_or_sections, axis=0)[source]

Splits an array into multiple sub arrays along a given axis.

This function is almost equivalent to cupy.split(). The only difference is that this function allows an integer sections that does not evenly divide the axis.

See also

cupy.split() for more detail, numpy.array_split()

cupy.split(ary, indices_or_sections, axis=0)[source]

Splits an array into multiple sub arrays along a given axis.

Parameters:
  • ary (cupy.ndarray) – Array to split.
  • indices_or_sections (int or sequence of ints) – A value indicating how to divide the axis. If it is an integer, then is treated as the number of sections, and the axis is evenly divided. Otherwise, the integers indicate indices to split at. Note that the sequence on the device memory is not allowed.
  • axis (int) – Axis along which the array is split.
Returns:

A list of sub arrays. Each array is a view of the corresponding input array.

See also

numpy.split()

cupy.vsplit(ary, indices_or_sections)[source]

Splits an array into multiple sub arrays along the first axis.

This is equivalent to split with axis=0.

See also

cupy.split() for more detail, numpy.dsplit()

cupy.hsplit(ary, indices_or_sections)[source]

Splits an array into multiple sub arrays horizontally.

This is equivalent to split with axis=0 if ary has one dimension, and otherwise that with axis=1.

See also

cupy.split() for more detail, numpy.hsplit()

cupy.dsplit(ary, indices_or_sections)[source]

Splits an array into multiple sub arrays along the third axis.

This is equivalent to split with axis=2.

See also

cupy.split() for more detail, numpy.dsplit()

Repeating part of arrays along axis

cupy.tile(A, reps)[source]

Construct an array by repeating A the number of times given by reps.

Parameters:
Returns:

Transformed array with repeats.
Return type:

cupy.ndarray

See also

numpy.tile()

cupy.repeat(a, repeats, axis=None)[source]

Repeat arrays along an axis.

Parameters:
Returns:

Transformed array with repeats.
Return type:

cupy.ndarray

See also

numpy.repeat()

Rearranging elements

cupy.flip(a, axis)[source]

Reverse the order of elements in an array along the given axis.

Note that flip function has been introduced since NumPy v1.12. The contents of this document is the same as the original one.

Parameters:
  • a (ndarray) – Input array.
  • axis (int) – Axis in array, which entries are reversed.
Returns:

Output array.
Return type:

ndarray

See also

numpy.flip()

cupy.fliplr(a)[source]

Flip array in the left/right direction.

Flip the entries in each row in the left/right direction. Columns are preserved, but appear in a different order than before.

Parameters:a (ndarray) – Input array.
Returns:Output array.
Return type:ndarray

See also

numpy.fliplr()

cupy.flipud(a)[source]

Flip array in the up/down direction.

Flip the entries in each column in the up/down direction. Rows are preserved, but appear in a different order than before.

Parameters:a (ndarray) – Input array.
Returns:Output array.
Return type:ndarray

See also

numpy.flipud()

cupy.roll(a, shift, axis=None)[source]

Roll array elements along a given axis.

Parameters:
  • a (ndarray) – Array to be rolled.
  • shift (int) – The number of places by which elements are shifted.
  • axis (int or None) – The axis along which elements are shifted. If axis is None, the array is flattened before shifting, and after that it is reshaped to the original shape.
Returns:

Output array.
Return type:

ndarray

See also

numpy.roll()

cupy.rot90(a, k=1, axes=(0, 1))[source]

Rotate an array by 90 degrees in the plane specified by axes.

Note that axes argument has been introduced since NumPy v1.12. The contents of this document is the same as the original one.

Parameters:
  • a (ndarray) – Array of two or more dimensions.
  • k (int) – Number of times the array is rotated by 90 degrees.
  • axes – (tuple of ints): The array is rotated in the plane defined by the axes. Axes must be different.
Returns:

Output array.
Return type:

ndarray

See also

numpy.rot90()