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.
- Parameters
a – array
- Returns
true if the data area of
a
is writable
-
GpuArray_ISALIGNED(a)¶
Checks if the array elements are aligned.
- Parameters
a – array
- Returns
true if the elements of
a
are aligned.
-
GpuArray_ISONESEGMENT(a)¶
Checks if the array elements are contiguous in memory.
- Parameters
a – array
- Returns
true if the data area of
a
is contiguous
-
GpuArray_IS_C_CONTIGUOUS(a)¶
Checks if the array elements are c contiguous in memory.
- Parameters
a – array
- Returns
true if the data area of
a
is contiguous
-
GpuArray_IS_F_CONTIGUOUS(a)¶
Checks if the array elements are f contiguous in memory.
- Parameters
a – array
- Returns
true if the data area of
a
is contiguous
-
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.
- Parameters
a – array
- Returns
true if the data area of
a
is Fortran-contiguous
-
GpuArray_ITEMSIZE(a)¶
Retrive the size of the elements in the array.
- Parameters
a – array
- Returns
the size of the array elements.
Enums
Functions
-
static inline int GpuArray_CHKFLAGS(const GpuArray *a, int flags)¶
Checks if all the specified flags are set.
- Parameters
a – array
flags – flags to check
- Returns
true if all flags in
flags
are set and false otherwise.
-
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.
- 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.
- Returns
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.
-
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.
- 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.
- Returns
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.
-
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.- 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.
- Returns
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.
-
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.
- Parameters
v – the result array
a – the source array
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
int GpuArray_sync(GpuArray *a)¶
Blocks until all operations (kernels, copies) involving
a
are finished.- Parameters
a – the array to synchronize
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.
- 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)
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.- 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
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.
- Parameters
a – the destination array
v – the value array
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.- 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.
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.- Parameters
res – the result array
a – the source array
new_axes – either NULL or a list of a->nd elements
- Returns
GA_NO_ERROR if the operation was successful.
- Returns
an error code otherwise
-
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.
- Parameters
a – an array
b – an array
- Returns
1 if
a
andb
may share a portion of their data.
-
gpucontext *GpuArray_context(const GpuArray *a)¶
Retursns the context of an array.
- Parameters
a – an array
- Returns
the context in which
a
was allocated.
-
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.- Parameters
dst – destination array
src – source array
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
int GpuArray_write(GpuArray *dst, const void *src, size_t src_sz)¶
Copy data from the host memory to the device memory.
- Parameters
dst – destination array (must be contiguous)
src – source host memory (contiguous block)
src_sz – size of data to copy (in bytes)
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
int GpuArray_read(void *dst, size_t dst_sz, const GpuArray *src)¶
Copy data from the device memory to the host memory.
- Parameters
dst – destination host memory (contiguous block)
dst_sz – size of data to copy (in bytes)
src – source array (must be contiguous)
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
int GpuArray_memset(GpuArray *a, int data)¶
Set all of an array’s data to a byte pattern.
- Parameters
a – an array (must be contiguous)
data – the byte to repeat
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
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.
- Parameters
res – result array
a – array to transfer
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.
- 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
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.
- 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
- Returns
GA_NO_ERROR if the operation was succesful.
- Returns
an error code otherwise
-
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.
- Parameters
a – an array
err – the error code returned
- Returns
A user-readable string describing the nature of the error.
-
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_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
where (i3,i4,i1) are the coordinates of the maximum- valued element within subtensor [i0,:,i2,:,:] of src.dstArgmax[i0,i2] = i3 * src.shape[4] * src.shape[1] + i4 * src.shape[1] + i1
- Parameters
dstMax – [out] The resulting tensor of maxima
dstArgmax – [out] the resulting tensor of arguments at maxima
src – [in] The source tensor.
reduxLen – [in] The number of axes reduced. Must be >= 1 and <= src->nd.
reduxList – [in] 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.
- Returns
GA_NO_ERROR if the operation was successful, or a non-zero error code otherwise.
-
struct GpuArray¶
- #include <array.h>
Main array structure.