Vector Arguments

Vector Arguments in BLAS

Vector arguments are passed in one-dimensional arrays. The array dimension (length) and vector increment are passed as integer variables. The length determines the number of elements in the vector. The increment (also called stride) determines the spacing between vector elements and the order of the elements in the array in which the vector is passed.

A vector of length n and increment incx is passed in a one-dimensional array x whose values are defined as:
x(1), x(1+|incx|), ..., x(1+(n-1)* |incx|)

If incx is positive, then the elements in array x are stored in increasing order. If incx is negative, the elements in array x are stored in decreasing order with the first element defined as x(1+(n-1)*|incx|). If incx is zero, then all elements of the vector have the same value, x(1).

The dimension of the one-dimensional array that stores the vector must always be at least idimx = 1+(n-1)* |incx|.

Vector Arguments in Sparse BLAS

Sparse BLAS routines handle two types of vectors: compressed sparse vectors and full-storage vectors.

Compressed sparse vectors. Let a be a vector stored in an array, and assume that the only non-zero elements of a are the following:
a(k₁), a(k₂), a(k₃), ..., a(k_nz), where nz is the total number of non-zero elements in a.
In Sparse BLAS, this vector can be represented in compressed form by two FORTRAN arrays, x (values) and indx (indices). Each array has nz elements:
x(1)=a(k₁), x(2)=a(k₂), ..., x(nz)=a(k_nz),
indx(1)=k₁, indx(2)=k₂, ..., indx(nz)=k_nz.
The triple (nz, x, indx) fully determines a sparse vector. If a negative or zero value of nz is passed to Sparse BLAS, the subroutines do not modify any arrays or variables.

Full-storage vectors. Sparse BLAS routines can also use a vector argument fully stored in a single FORTRAN array (a full-storage vector). If y is a full-storage vector, its elements must be stored contiguously: the first element in y(1), the second in y(2), and so on. This corresponds to an increment incy =1 in BLAS Level 1. No increment value for full-storage vectors is passed as an argument to Sparse BLAS routines or functions.

Vector Arguments in VML

Vector arguments of VML mathematical functions are passed in one-dimensional arrays with unit vector increment. It means that a vector of length n is passed contiguously in an array a whose values are defined as a[0], a[1], ..., a[n-1] (for C-interface).
To accommodate for arrays with other increments, or more complicated indexing, VML contains auxiliary pack/unpack functions that gather the array elements into a contiguous vector and then scatter them after the computation is complete.
Generally, if the vector elements are stored in a one-dimensional array a as
a[m₀], a[m₁], ..., a[m_n-1]
and need to be regrouped into an array y as
y[k₀], y[k₁], ..., y[k_n-1],
VML pack/unpack functions can use one of the following indexing methods:

Positive Increment Indexing
k_j = incy * y, m_j = inca * j, j = 0, ..., n-1
Constraint: incy > 0 and inca > 0.
For example, setting incy = 1 specifies gathering array elements into a contiguous vector.
This method is similar to that used in BLAS, with the exception that negative and zero increments are not permitted.

Index Vector Indexing
k_j = iy[j], m_j = ia[j], j = 0, ..., n-1,
where ia and iy are arrays of length n that contain index vectors for the input and output arrays a and y, respectively.

Mask Vector Indexing
Indices k_j, m_j are such that:
my[k_j] ≠ 0, ma[m_j] ≠ 0, j = 0, ..., n-1,
where ma and my are arrays that contain mask vectors for the input and output arrays a and y, respectively.