Go to the previous, next section.

## Matrix Manipulation

The following functions create, resize, reshape, permute and compose matrices. In this list of functions, symbols A, B and C are of the class `integer_matrix`; a and c are a single row of the matrix (class `integer_row`) and m, n, i and j are integers.

`integer_matrix A();`
`A.init();`
Create/initialize an empty matrix.

`integer_matrix A(i, j);`
`A.init(i, j);`
Create/initialize a matrix of i rows and j columns.

`integer_matrix A(B);`
`integer_matrix A(&B);`
`A.init(B);`
`A.init(&B);`
Create/initialize matrix A to be identical to B.

`integer_matrix A(B, m);`
`integer_matrix A(&B, m);`
`A.init(B, m);`
`A.init(&B, m);`
Create/initialize matrix A such that it has m rows identical to the first m rows of B. If B has less that m rows, A is padded with rows (with elements set to 0).

`immed_list ilist;`
`j = A.init(ilist);`
`j = A.init(ilist, i);`
These conversion routines are useful for storing and retrieving matrices to/from SUIF annotations. `immed` is a class abstraction used by SUIF compiler to store values of different types. Matrix A is initialized from a specially created list of `immed`s (starting from position i). The integer variable j gets the next position of the list after reading in the matrix.
`immed_list * il = A.cvt_immed_list();`
Create an `immed_list` from the matrix A. These functions are used when matrices are stored as annotations.

`A = Compose(row, col, int, int, int, ...)`
Compose a matrix using individual elements.
```A = Compose(2, 3,
i11, i12, i13,
i21, i22, i23);
```

will create a 2x3 matrix initialized to the integers given. Thus A is:

```        [ i11, i12, i13 ]
[ i21, i22, i23 ]
```

`nim_op O;`
`A = Compose(row, col, O.NIM(...) or NULL, O.NIM(...) or NULL, ...)`
Compose a matrix by combining many different matrices.
```nim_op O;
A = Compose(2, 3,
O.NIM(B11), O.NIM(B12), NULL,
NULL,       O.NIM(B22), O.NIM(i,j));
```

will create the matrix:

```        [ [B11]  [B12]    0   ]
[   0    [B21]  [ixj] ]
```

where all the matrices contributing to a row have the same number of rows and matrices contributing to a column have the same number of columns -- except when an entry is NULL. Then, that space is stuffed with zeros according to the size dictated by other elements in its row and column. Thus, each row and column should have at least one entry that is not NULL. The function `NIM` is used as a wrap-around for all the input matrices. `NIM(i, j)` creates an ixj matrix and `NIM(x)` creates a single element with the value x. The wrappers created by the calls to `O.NIM(...)` will be deleted when the `nim_op` object O is deleted.

The following example further illustrates the use of `Compose`.
```lin_ineq A = Compose(2, 2,
1  2
3  4);
lin_ineq B(1, 3);
B = 2;
nim_op O;
lin_ineq C = Compose(2, 2,
O.NIM(A),   0,
O.NIM(1,2), 0,
0,     O.NIM(B));
```

The matrices are:

```A =  [ 1  2 ]            [ 1  2  0  0  0 ]
[ 3  4 ]       C =  [ 3  4  0  0  0 ]
[ 0  0  0  0  0 ]
B =  [ 2  2  2 ]         [ 0  0  2  2  2 ]
```

`A = Ident(i);`
Create an identity matrix of size i.

`A.del_row(i);`
`A.del_row(i, j);`
Delete the i-th row (or rows i to j) from matrix A.

`A.del_col(i);`
`A.del_col(i, j);`
Delete the i-th column (or columns i to j) from matrix A.

`B = A.del_columns(a);`
If the k-th entry of the row a is non zero (set to 1) then the k-th column of the matrix A is eliminated from the output.

`A.insert_col(i);`
Insert a column initialized to 0 at the i-th position.

`B = A.swap(i, j);`
`A[i] ^= A[j];`
Swap the rows i and j. In using `^=`, the current matrix A is updated.

`B = A.swap_col(i, j);`
Swap the columns i and j.

`B = A%a;`
Permute the rows of A using the position given by a; where, for each row x, B[x] = A[a[x]].

`B = A.resize(il, iu, jl, ju);`
`B = A.resize(il, iu, jl, ju, fill);`
If il >= 0, the first row of matrix B will be the il-th row of matrix A, otherwise (il < 0) the first (-il)-th rows of B are all zeros while the (1-il)-th row is the first row of A. If iu<=A.m(), the last row of B is the iu-th row of A, while if iu>A.m() the last iu-A.m() rows of B are zeros. The technique using jl and ju applies to the columns. If fill is set, the padded rows and columns will have the value fill instead of zero.
For example:
```  B  = A.resize(1, 3, 2, 7);
```

where

```
[  0   1   2   3   4 ]      [ 12  13  14  0  0  0 ]
[ 10  11  12  13  14 ]  B = [ 22  23  24  0  0  0 ]
A = [ 20  21  22  23  24 ]      [ 32  33  34  0  0  0 ]
[ 30  31  32  33  34 ]
[ 40  41  42  43  44 ]
```

`B = A.resize_offset(il, iu, jl, ju);`
`B = A.resize_offset(il, iu, jl, ju, fill);`
Create a matrix B by resizing A. If il >= 0, the il-th row of A is the first row of B, otherwise (-il)-blank rows are inserted in B before the first row of A is inserted. If iu <= 0, the last row of B is (B.m()+iu)-th row of A. Otherwise, iu blank rows are inserted in B after the last row of A. The same applies for the columns. If fill is set, the padded rows and columns will have the value fill instead of zero.
For example:
```  B  = A.resize_offset(1, -1, 2, 3);
```

where

```    [  0   1   2   3   4 ]      [ 12  13  14  0  0  0 ]
[ 10  11  12  13  14 ]  B = [ 22  23  24  0  0  0 ]
A = [ 20  21  22  23  24 ]      [ 32  33  34  0  0  0 ]
[ 30  31  32  33  34 ]
[ 40  41  42  43  44 ]
```

`C = A & B;`
`C = r_merge(A, B);`
The resulting matrix C is:
```        [ A ]
[ B ]
```

This is same as `C = Compose(2, 1, O.NIM(A), O.NIM(B));`.

`C = A | B;`
`C = c_merge(A, B);`
The resulting matrix C is:
```        [ A  B ]
```

This is same as `C = Compose(1, 2, O.NIM(A), O.NIM(B));`.

The matrix library also can create permutation matrices and row-column switch and add matrices.

`B = rowswitch(A, i, j);`
B*A will result in a matrix that is identical to A except the i and j rows are interchanged.

`B = colswitch(A, i, j);`
A*B will result in a matrix that is identical to A except the i and j columns are interchanged.

`B = rowadd(A, i, j, x);`
B*A will result in a matrix that is identical to A except the i-th row. The values in that row are, for 0<=k<A.n() B[i][k] = A[i][k] + x*A[j][k].

`B = coladd(A, i, j, x);`
B*A will result in a matrix that is identical to A except for the i-th column. The values in that column are 0<=k<A.m() B[k][i] = A[k][i] + x*A[k][j].

Go to the previous, next section.