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
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
: arrayflags
: 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 arraynd
: 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 arraynd
: 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 arraynd
: 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_copy_from_host
(GpuArray * a, gpucontext * ctx, void * buf, int typecode, unsigned int nd, const size_t * dims, const ssize_t * strides)¶
-
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 arraya
: 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 arraya
: the source arraystarts
: 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
andi
respectively) need to be C contiguous.The dimension 0 of
a
has to match dimension 0 ofi
and the others have to match their equivalent onv
.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 arrayv
: 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 arraya
: the source arraynd
: new dimensions ordernewdims
: new dimensions (length is nd)ord
: the desired resulting ordernocopy
: if 0 error out if a data copy is required.
-
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. Ifnew_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 arraya
: the source arraynew_axes
: either NULL or a list of a->nd elements
-
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
Checks if two arrays may share device memory.
- Return
- 1 if
a
andb
may share a portion of their data. - Parameters
a
: an arrayb
: 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
anddst
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 arraysrc
: 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 arraya
: 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
whereaxis
is divided according to the values inp
. No checks are performed on the values inp
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 splitn
: number of splits (length of p)p
: list of split pointsaxis
: 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 axisaxis
.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 arrayas
: list of pointer to arrays to concatenaten
: number of array in listas
axis
: the axis along which to concatenaterestype
: 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 arrayerr
: 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 writinga
: an array
-
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
dstMax
: The resulting tensor of maximadstArgmax
: the resulting tensor of arguments at maximasrc
: The source tensor.reduxLen
: The number of axes reduced. Must be >= 1 and <= src->nd.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.