Moving data
DAPPLE has many ways of rearranging the data in a vector or matrix,
or more correctly, producing a new vector or matrix with the
rearranged data of another matrix.
The elements of a vector may be shifted left (toward smaller-numbered
positions) or right (toward higher-numbered positions). All
elements participate, regardless of the active set. (Note there is some
subtlety here.) As elements
are shifted to the right, the left side of the vector
fills with zeros. Similarly, as elements are shifted left, the right
side fills with zeros. For example,
<![CDATA[
intVector A(N), B(N);
...
A = shift(B, 3); // shift right: A[i+3] = B[i], except A[0..2] = 0
A = shift(B, -2); // shift left: A[i-2] = B[i], except A[N-2..N-1] = 0
]]>
Another form of shifting is pack : all active, non-zero
elements are pushed to the left, and zero elements pushed right, so
that all the active non-zeros are contiguous in the vector, in the
same relative order as they began.
<![CDATA[
intVector A(N), B(N);
...
A = pack(B);
]]>
A Matrix shift is similar, except that two offsets are specified: one
for rows, and one for columns.
<![CDATA[
floatMatrix A(N), B(N);
...
A = shift(B, 3, 4); // shift each element 3 down and 4 right
]]>
Sometimes it is convenient to shift each row (or column) of a matrix
a different amount.
<![CDATA[
floatMatrix A(N,N), B(N,N);
intVector S(N); // an amount to shift
...
A = shift_rows(B, S); // shift each row i by S[i]
A = shift_cols(B, S); // shift each column i by S[i]
]]>
In the above S could instead be an integer scalar, and all rows (or
columns) are shifted the same amount.
There is no Matrix pack() operation.
Rotating a vector is similar to shifting a vector, except that
instead of filling one side with zeros, the values wrap around.
All elements participate, regardless of the active set.
<![CDATA[
intVector A(N), B(N);
...
A = rotate(B, 3); // rotate right: A[i+3 mod N] = B[i]
A = rotate(B, -2); // rotate left: A[i-2+N mod N] = B[i]
]]>
Matrix rotations are similar to the vector rotations, in the same way
that matrix shifts are similar to the vector shifts. Thus,
<![CDATA[
floatMatrix A(N), B(N);
intVector S(N); // an amount to shift
...
A = rotate(B, 3, 4); // rotate each element 3 down and 4 right
A = rotate_rows(B, S); // rotate each row i by S[i]
A = rotate_cols(B, S); // rotate each column i by S[i]
]]>
Permutes.
Permuting a vector moves each active element of the input vector to a
destination in the output vector determined by a second input
(permutation) vector, whose elements contain the new position for each
active element. A permutation is always an intVector.
<![CDATA[
floatVector A(N), B(N);
intVector P(N); // a permutation, ie, each element is in 0..N-1
...
A = permute(B, P); // permute B by P
]]>
The result vector is initialized to be the same as the input vector,
and then overwritten by copying the active elements from the input
vector to the appropriate destination element in the result vector.
Thus, active elements may move to inactive positions.
There is no Matrix permutation operation.