File array.h

Array functions.

Defines

GA_C_CONTIGUOUS

Array is C-contiguous.

GA_F_CONTIGUOUS

Array is Fortran-contiguous.

GA_ALIGNED

Buffer data is properly aligned for the type. This should always be true for arrays allocated through this library.

If this isn’t true you can’t use kernels on the data, since they require aligned access.

GA_WRITEABLE

Can write to the data buffer. (This is always true for arrays allocated through this library).

GA_BEHAVED

Array data is behaved (properly aligned and writable).

GA_CARRAY

Array layout is that of a C array.

GA_FARRAY

Array layout is that of a Fortran array.

GpuArray_ISWRITEABLE(a)

Checks if the array data is writable.

Return

true if the data area of a is writable

Parameters
  • a: array

GpuArray_ISALIGNED(a)

Checks if the array elements are aligned.

Return

true if the elements of a are aligned.

Parameters
  • a: array

GpuArray_ISONESEGMENT(a)

Checks if the array elements are contiguous in memory.

Return

true if the data area of a is contiguous

Parameters
  • a: array

GpuArray_IS_C_CONTIGUOUS(a)

Checks if the array elements are c contiguous in memory.

Return

true if the data area of a is contiguous

Parameters
  • a: array

GpuArray_IS_F_CONTIGUOUS(a)

Checks if the array elements are f contiguous in memory.

Return

true if the data area of a is contiguous

Parameters
  • a: array

GpuArray_ISFORTRAN(a)

This is the same as GpuArray_IS_F_CONTIGUOUS, but not the same as PyArray_ISFORTRAN.

PyArray_ISFORTRAN checks if the array elements are laid out if Fortran order and NOT c order.

Return

true if the data area of a is Fortran-contiguous

Parameters
  • a: array

GpuArray_ITEMSIZE(a)

Retrive the size of the elements in the array.

Return

the size of the array elements.

Parameters
  • a: array

Enums

_ga_order

Type used to specify the desired order to some functions

Values:

1

Any order is fine.

0

C order is desired.

1

Fortran order is desired.

Functions

static int GpuArray_CHKFLAGS(const GpuArray * a, int flags)

Checks if all the specified flags are set.

Return

true if all flags in flags are set and false otherwise.

Parameters
  • a: array

  • flags: flags to check

void GpuArray_fix_flags(GpuArray * a)

Fix the flags of an array using the current strides and shape.

Parameters
  • a: GpuArray to fix flags for

int GpuArray_empty(GpuArray * a, gpucontext * ctx, int typecode, unsigned int nd, const size_t * dims, ga_order ord)

Initialize and allocate a new empty (uninitialized data) array.

Return

A return of GA_NO_ERROR means that the structure is properly initialized and that the memory requested is reserved on the device. Any other error code means that the structure is left uninitialized.

Parameters
  • a: the GpuArray structure to initialize. Content will be ignored so make sure to deallocate any previous array first.

  • ctx: context in which to allocate array data. Must come from the same backend as the operations vector.

  • typecode: type of the elements in the array

  • nd: desired order (number of dimensions)

  • dims: size for each dimension.

  • ord: desired layout of data.

int GpuArray_zeros(GpuArray * a, gpucontext * ctx, int typecode, unsigned int nd, const size_t * dims, ga_order ord)

Initialize and allocate a new zero-initialized array.

Return

A return of GA_NO_ERROR means that the structure is properly initialized and that the memory requested is reserved on the device. Any other error code means that the structure is left uninitialized.

Parameters
  • a: the GpuArray structure to initialize. Content will be ignored so make sure to deallocate any previous array first.

  • ctx: context in which to allocate array data. Must come from the same backend as the operations vector.

  • typecode: type of the elements in the array

  • nd: desired order (number of dimensions)

  • dims: size for each dimension.

  • ord: desired layout of data.

int GpuArray_fromdata(GpuArray * a, gpudata * data, size_t offset, int typecode, unsigned int nd, const size_t * dims, const ssize_t * strides, int writeable)

Initialize and allocate a new array structure from a pre-existing buffer.

The array will be considered to own the gpudata structure after the call is made and will free it when deallocated. An error return from this function will deallocate data. This increment the ref count of gpudata. This seem to contradict the above.

Return

A return of GA_NO_ERROR means that the structure is properly initialized. Any other error code means that the structure is left uninitialized and the provided buffer is deallocated.

Parameters
  • a: the GpuArray structure to initialize. Content will be ignored so make sure to deallocate any previous array first.

  • data: buffer to user.

  • offset: position of the first data element of the array in the buffer.

  • typecode: type of the elements in the array

  • nd: order of the data (number of dimensions).

  • dims: size for each dimension.

  • strides: stride for each dimension.

  • writeable: true if the buffer is writable false otherwise.

int GpuArray_view(GpuArray * v, const GpuArray * a)

Initialize an array structure to provide a view of another.

The new structure will point to the same data area and have the same values of properties as the source one. The data area is shared and writes from one array will be reflected in the other. The properties are copied and not shared and can be modified independantly.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • v: the result array

  • a: the source array

int GpuArray_sync(GpuArray * a)

Blocks until all operations (kernels, copies) involving a are finished.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • a: the array to synchronize

int GpuArray_index(GpuArray * r, const GpuArray * a, const ssize_t * starts, const ssize_t * stops, const ssize_t * steps)

Returns a sub-view of a source array.

The indexing follows simple basic model where each dimension is indexed separately. For a single dimension the indexing selects from the start index (included) to the end index (excluded) while selecting one over step elements. As an example for the array [ 0 1 2 3 4 5 6 7 8 9 ] indexed with start index 1 stop index 8 and step 2 the result would be [ 1 3 5 7 ].

The special value 0 for step means that only one element corresponding to the start index and the resulting array order will be one smaller.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • r: the result array

  • a: the source array

  • starts: the start of the subsection for each dimension (length must be a->nd)

  • stops: the end of the subsection for each dimension (length must be a->nd)

  • steps: the steps for the subsection for each dimension (length must be a->nd)

int GpuArray_index_inplace(GpuArray * a, const ssize_t * starts, const ssize_t * stops, const ssize_t * steps)
int GpuArray_take1(GpuArray * a, const GpuArray * v, const GpuArray * i, int check_error)

Take a portion of an array along axis 0.

This operation allows arbitrary indexing of an array along its first axis. The indexed array v can be of any dimension or strides. The result and index array (a and i respectively) need to be C contiguous.

The dimension 0 of a has to match dimension 0 of i and the others have to match their equivalent on v. i has to have a single dimension.

If check_error is not 0, the function will check for indexing errors in the kernel and will return GA_VALUE_ERROR in that case. No other error will produce that error code. This is not always done because it introduces a synchronization point which may affect performance.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • a: the result array (nd)

  • v: the source array (nd)

  • i: the index array (1d)

  • check_error: whether to check for index errors or not

int GpuArray_setarray(GpuArray * a, const GpuArray * v)

Sets the content of an array to the content of another array.

The value array must be smaller or equal in number of dimensions to the destination array. Each of its dimensions’ size must be either exactly equal to the destination array’s corresponding dimensions or 1. Dimensions of size 1 will be repeated to fill the full size of the destination array. Extra size 1 dimensions will be added at the end to make the two arrays shape-equivalent.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • a: the destination array

  • v: the value array

int GpuArray_reshape(GpuArray * res, const GpuArray * a, unsigned int nd, const size_t * newdims, ga_order ord, int nocopy)

Change the dimensions of an array.

Return a new array with the desired dimensions. The new dimensions must have the same total size as the old ones. A copy of the underlying data may be performed if necessary, unless nocopy is 0.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • res: the result array

  • a: the source array

  • nd: new dimensions order

  • newdims: new dimensions (length is nd)

  • ord: the desired resulting order

  • nocopy: if 0 error out if a data copy is required.

int GpuArray_reshape_inplace(GpuArray * a, unsigned int nd, const size_t * newdims, ga_order ord)
int GpuArray_transpose(GpuArray * res, const GpuArray * a, const unsigned int * new_axes)

Rearrange the axes of an array.

Return a new array with its shape and strides swapped accordingly to the new_axes parameter. If new_axes is NULL then the order is reversed. The returned array is a view on the data of the old one.

Return

GA_NO_ERROR if the operation was successful.

Return

an error code otherwise

Parameters
  • res: the result array

  • a: the source array

  • new_axes: either NULL or a list of a->nd elements

int GpuArray_transpose_inplace(GpuArray * a, const unsigned int * new_axes)
void GpuArray_clear(GpuArray * a)

Release all device and host memory associated with a.

This function frees all host memory, and releases the device memory if it is the owner. In case an array has views it is the responsability of the caller to ensure a base array is not cleared before its views.

This function will also zero out the structure to prevent accidental reuse.

Parameters
  • a: the array to clear

int GpuArray_share(const GpuArray * a, const GpuArray * b)

Checks if two arrays may share device memory.

Return

1 if a and b may share a portion of their data.

Parameters
  • a: an array

  • b: an array

gpucontext* GpuArray_context(const GpuArray * a)

Retursns the context of an array.

Return

the context in which a was allocated.

Parameters
  • a: an array

int GpuArray_move(GpuArray * dst, const GpuArray * src)

Copies all the elements of one array to another.

The arrays src and dst must have the same size (total number of elements) and be in the same context.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • dst: destination array

  • src: source array

int GpuArray_write(GpuArray * dst, const void * src, size_t src_sz)

Copy data from the host memory to the device memory.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • dst: destination array (must be contiguous)

  • src: source host memory (contiguous block)

  • src_sz: size of data to copy (in bytes)

int GpuArray_read(void * dst, size_t dst_sz, const GpuArray * src)

Copy data from the device memory to the host memory.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • dst: destination host memory (contiguous block)

  • dst_sz: size of data to copy (in bytes)

  • src: source array (must be contiguous)

int GpuArray_memset(GpuArray * a, int data)

Set all of an array’s data to a byte pattern.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • a: an array (must be contiguous)

  • data: the byte to repeat

int GpuArray_copy(GpuArray * res, const GpuArray * a, ga_order order)

Make a copy of an array.

This is analogue to GpuArray_view() except it copies the device memory and no data is shared.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

int GpuArray_transfer(GpuArray * res, const GpuArray * a)

Copy between arrays in different contexts.

This works like GpuArray_move() except it will work between arrays that aren’t in the same context.

Source and target arrays must be contiguous. This restriction may be lifted in the future.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • res: result array

  • a: array to transfer

int GpuArray_split(GpuArray ** rs, const GpuArray * a, size_t n, size_t * p, unsigned int axis)

Split an array into multiple views.

The created arrays will be sub-portions of a where axis is divided according to the values in p. No checks are performed on the values in p except to make sure that they don’t reference values outside of the bounds of the source array.

If an error occurs partway during the operation, the created arrays will be cleared before returning.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • rs: list of array pointers to store results (must be of length n+1)

  • a: array to split

  • n: number of splits (length of p)

  • p: list of split points

  • axis: axis to split

int GpuArray_concatenate(GpuArray * r, const GpuArray ** as, size_t n, unsigned int axis, int restype)

Concatenate the arrays in as along the axis axis.

If an error occurs during the operation, the result array may be cleared before returning.

Return

GA_NO_ERROR if the operation was succesful.

Return

an error code otherwise

Parameters
  • r: the result array

  • as: list of pointer to arrays to concatenate

  • n: number of array in list as

  • axis: the axis along which to concatenate

  • restype: the typecode of the result array

const char* GpuArray_error(const GpuArray * a, int err)

Get a description of the last error in the context of a.

The description may reflect operations with other arrays in the same context if other operations were performed between the occurence of the error and the call to this function.

Operations in other contexts, however have no incidence on the return value.

Return

A user-readable string describing the nature of the error.

Parameters
  • a: an array

  • err: the error code returned

void GpuArray_fprintf(FILE * fd, const GpuArray * a)

Print a textual description of a to the specified file descriptor.

Parameters
  • fd: a file descriptior open for writing

  • a: an array

int GpuArray_fdump(FILE * fd, const GpuArray * a)
int GpuArray_maxandargmax(GpuArray * dstMax, GpuArray * dstArgmax, const GpuArray * src, unsigned reduxLen, const unsigned * reduxList)

Computes simultaneously the maxima and the arguments of maxima over specified axes of the tensor.

Returns two tensors of identical shape. Both tensors’ axes are a subset of the axes of the original tensor. The axes to be reduced are specified by the caller, and the maxima and arguments of maxima are computed over them.

For example, if a 5D-tensor is reduced with an axis list of [3,4,1], then reduxLen shall be 3, and the index calculation in every point shall take the form

dstArgmax[i0,i2] = i3 * src.shape[4] * src.shape[1] +
                   i4 * src.shape[1]                +
                   i1
Parameters
  • [out] dstMax: The resulting tensor of maxima

  • [out] dstArgmax: the resulting tensor of arguments at maxima

  • [in] src: The source tensor.

  • [in] reduxLen: The number of axes reduced. Must be >= 1 and <= src->nd.

  • [in] reduxList: A list of integers of length reduxLen, indicating the axes to be reduced. The order of the axes matters for dstArgmax index calculations. All entries in the list must be unique, >= 0 and < src->nd.

where (i3,i4,i1) are the coordinates of the maximum- valued element within subtensor [i0,:,i2,:,:] of src.

Return

GA_NO_ERROR if the operation was successful, or a non-zero error code otherwise.

struct _GpuArray
#include <array.h>

Main array structure.

Public Members

gpudata* data

Device data buffer.

size_t* dimensions

Size of each dimension. The number of elements is nd.

ssize_t* strides

Stride for each dimension. The number of elements is nd.

size_t offset

Offset to the first array element into the device data buffer.

unsigned int nd

Number of dimensions.

int flags

Flags for this array (see Array Flags).

int typecode

Type of the array elements.