# permute rows or columns of a matrix, or permute a vector

SYNOPSIS

#include "matrix.h"
MAT     *px_rows(PERM *pi, MAT *A, MAT *OUT)
MAT     *px_cols(PERM *pi, MAT *A, MAT *OUT)
VEC     *px_vec (PERM *pi, VEC *x, VEC *out)
VEC     *pxinv_vec(PERM *pi, VEC *x, VEC *out)

#include "zmatrix.h"
ZVEC    *px_zvec   (PERM *pi, ZVEC *x, ZVEC *out)
ZVEC    *pxinv_zvec(PERM *pi, ZVEC *x, ZVEC *out)


DESCRIPTION

The routines px_rows() and px_cols() are for permuting matrices, permuting respectively the rows and columns of the matrix A. In particular, for px_rows() the i-th row of OUT is the pi->pe[i]-th row of A. Thus $\hboxOUT=PA$ where $P$ is the permutation matrix described by pi. The routine px_cols() computes $\hboxOUT=AP$. The result is stored in OUT provide it has sufficient space for the result. If OUT is NULL or too small to contain the result then it is replaced by a matrix of the appropriate size. In either case the result is returned. Similarly, px_vec() and px_zvec() permute the entries of the vector x into the vector out by the rule that the i-th entry of out is the pi->pe[i]-th entry of x. Conversely, pxinv_vec() and pxinv_zvec() permute x into out by the rule that the pi->pe[i]-th entry of out is the i-th entry of x. This is equivalent to inverting the permutation pi and then applying px_vec(), respectively, px_zvec() for real, resp., complex vectors. If out is NULL or too small to contain the result, then a new vector is created and the result stored in it. In either case the result is returned.

EXAMPLE

PERM  *pi;
VEC   *x, *tmp;
ZVEC  *z, *ztmp;
MAT   *A, *B;
......
/* permute x to give tmp */
tmp = px_vec(pi,x,tmp);
ztmp = px_zvec(pi,z,ZVNULL);
/* restore x & z */
x = pxinv_vec(pi,tmp,x);
pxinv_zvec(pi,ztmp,z);
/* symmetric permutation */
B = px_rows(pi,A,MNULL);
A = px_cols(pi,B,A);