# TOMNET  
# REGISTER (TOMNET)
# LOGIN  
# myTOMNET
TOMLAB LOGO

« Previous « Start » Next »

10  Sparse Matrix Handling

These sections outline the functionality available for sparse matrix handling included with TOMNET.

10.1  Create

The following functions are available to create sparse matrices.

10.1.1  Sparse Constructors

There are three Constructors for Sparse.
  • Sparse(Sparse S)
  • Sparse(int m, int n, int nnz, int[] ir, int[] jc, double[] pr)
  • Sparse(int m, int n, int nnz, int[] RowIdx, int[] ColIdx, double[] Values, int dummy)
The first one creates a copy of an already created sparse - to avoid shallow copying. The other two constructors are for creating instances from three arrays and three integers. Since they both require the same types of inputs a dummy parameter is needed to separate the two.

Sparse(int m, int n, int nnz, int[] ir, int[] jc, double[] pr)

Description
Initiate a sparse matrix from three arrays and three integers. One array with matrix element values, and two arrays defining the pattern of the Sparse. The integers describe the number of rows, number of columns and number of nonzero elements in the Sparse.

Description of Inputs
int m Number of rows in S.
 
int n Number of columns in S.
 
int nnz Number of elements that are not zero in S.
 
int[] ir ir stores at position i the row-index of the value pr[i].
 
int[] jc The number jc[i+1] - jc[i+1] equals the number of elements in column i stores at position i the index of pr.
 
double[] pr Values of the Sparse. The element pr[i] correponds to the i'th non-zero element (counting row-wise).
 

Calling Syntax
const int n = 5;
const int m = 3;
const int nnz = 7;

int[] ir = new int[nnz] { 0, 1, 0, 1, 2, 0, 1 };
int[] jc = new int[n + 1] { 0, 2, 2, 3, 5, 7 };
double[] pr = new double[nnz] { 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7 };
Sparse S = new Sparse(m, n, nnz, ir, jc, pr);
Sparse(int m, int n, int nnz, int[] RowIdx, int[] ColIdx, double[] Values, int dummy)

Description
Initiate a sparse matrix from three arrays and three integers. One array with matrix element values, and two arrays with column and row indices of the values. The integers describe the number of rows, number of columns and number of nonzero elements in the Sparse.

Description of Inputs
int m An integer equal to the number of rows in A.
 
int n An integer equal to the number of columns in A.
 
int nnz An integer equal to the number of columns in A.
 
int[] RowIdx Array row index. The array contains row index corresponding to the array of values.
 
int[] ColIdx Array column index. The array contains column index corresponding to the array of values.
 
double[] Values Array value. The array contains matrix element values.
 

Calling Syntax
const int n = 5;
const int m = 3;
const int nnz = 7;

int[] RowIdx = new int[nnz] { 0, 1, 0, 1, 2, 0, 1 };
int[] ColIdx = new int[nnz] { 0, 0, 2, 3, 3, 4, 4 };
double[] Values = new double[nnz] { 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7 };
Sparse S = new Sparse(m, n, nnz, RowIdx, ColIdx, Values, 0);

10.1.2  Sparse.Eye

There are four Sparse.Eye methods for initiating a Sparse with a diagonal, for example the Identity Matrix.
  • Eye(int m)
  • Eye(int m, double value)
  • Eye(int m, int n)
  • Eye(int m, int n, double value)
Description
Initiate a sparse identity matrix from one or two integers and optionally a value. The integers describe the number of rows and columns in the identity matrix and the optional value the diagonal entries (default 1).

Description of Inputs
int m An integer equal to the number of rows in matrix I.
 
int n An (optional) integer equal to the number of columns in matrix I.
 
double value An (optional) value to use instead of 1.0 in the diagonal.
 

Description of Outputs
I A sparse identity matrix with size described by the inputs.

Calling Syntax
Sparse I = Sparse.Eye(5);
// Sparse I = Sparse.Eye(5, 3.0);
// Sparse I = Sparse.Eye(5, 4);
// Sparse I = Sparse.Eye(5, 4, 3.0);

10.2  Modify

The following functions are available to merge and modify existing sparse matrices.

10.2.1  Sparse.Transpose

Purpose
The function returns the transpose of the input matrix.

B = AT
where B ∈ Rn × m, A ∈ Rm × n.

Description of Inputs
Sparse A An instance of a Sparse matrix.

Description of Outputs
Sparse B Sparse B will be created as the transpose of the input matrix.

Description
The routine Sparse.Transpose uses optimal data handling and structures to return the transpose of a matrix.

Calling Syntax
Sparse B = A.Transpose();

10.2.2  Sparse.Concatenate

Description
Concatenates two sparse matrices either rowwise or columnwise. The Sparse.Concatenate uses optimal data handling to concatenate two sparse matrices eighter rowwise or columnwise.

C = [
A B
]    (dim = 0)
C = ⎡
⎣
A
B
⎤
⎦		    (dim = 1)


where C ∈ RmA × (nA+nB) or C ∈ R(mA+mB) × nA, A ∈ RmA × nA, B ∈ RmB × nB.

Description of Inputs
Sparse A An instance of a Sparse matrix.
 
Sparse B An instance of a Sparse matrix.
 
Int dim Eighter 0 for rowwise concatenation or 1 for columnwise concatenation.

Description of Outputs
Sparse C A new Sparse C.

Calling Syntax
// A and B are instances of Sparse of appropriate dimensions
Sparse C;
C = Sparse.Concatenate(A, B, 0);
C = Sparse.Concatenate(A, B, 1);

10.2.3  Alter value

Description
Set a matrix element to a given value. where A ∈ Rm × n, i integer, j integer, val is a scalar.

Description of Inputs
Sparse A An instance of a Sparse matrix.
 
int i Integer equal to the row index.
 
int j Integer equal to the column index.
 
double val The new element in A.

Description of Outputs
A new The modified sparse matrix.

Calling Syntax
// ok
A[1,2] = 3.14;

// bad
// A[1,200] = 1.337;
// Raises an exception with a message similar to
// "Index (1,200) not in Matrix (Sparse) of size (3 x 5)."

10.3  Properties

The following properties are available to obtain information about the sparse matrices.

10.3.1  Sparse.Cols

Description
Get the number of columns of the Sparse.

n =   number of columns in A
where A ∈ Rm × n.

Description of Outputs
int n An integer equal to the number of columns in A.

Calling Syntax
int n =  A.Cols;

10.3.2  Sparse.Rows

Description
Get the number of rows of the Sparse.

m =   number of rows in A
where A ∈ Rm × n.

Description of Outputs
m An integer equal to the number of rows in A.

Calling Syntax
int m =  A.Rows;

10.3.3  Sparse.Nnz

Description
Get the number of non zeros in a Sparse.

nnz=  number of nonzeros in A
where A ∈ Rm × n.

Description of Outputs
int nnz An integer equal to the number of non zeros in A.

Calling Syntax
int nnz =  A.Nnz;

10.3.4  get Value

Description
Get a matrix element value from a sparse 2-D matrix.

val = A[i,j]
where val is a scalar, A ∈ Rm × n, i integer, j integer.

Description of Inputs
Sparse A Sparse matrix A.
 
int i Integer equal to the row index.
 
int j Integer equal to the column index.

Description of Outputs
double val The element in A in the i:th row and j:th column.

Calling Syntax
double val =  A[1,2];

10.4  Operators

The following functions are available to perform calculations with sparse matrices.

10.4.1  Operator *

Description
multiplies two instances of Sparse matrices.

C = AB
where C ∈ RmA × nB, A ∈ RmA × nA and B ∈ RmB × nB.

Description of Inputs
Sparse A Sparse matrix A.
 
Sparse B Sparse matrix B.

Description of Outputs
C Sparse matrix C.

Calling Syntax
// A and B are instances of Sparse
// of appropriate size.
Sparse C = A * B;

« Previous « Start » Next »