com.imsl.math
Class SparseMatrix

java.lang.Object
  com.imsl.math.SparseMatrix

All Implemented Interfaces:

Serializable

public class SparseMatrix
extends Object
implements Serializable

Sparse matrix of type double. The class represents a general real sparse matrix. It is intended to be efficiently and easily updated.

A SparseMatrix can be constructed from a set of arrays, or it can be abstractly created as an empty array and then incrementally built into final form. It is usually easier to create an empty SparseMatrix of set size and then use the set method to set the elements of the array. When setting the elements of the sparse array, their positions should be thought of as their positions in the dense array. Elements can be set in any order, but only the elements actually set are stored.

This class includes methods to update the sparse matrix. There are also methods to multiply a sparse matrix and a vector or to multiply two sparse matrices. To solve a sparse linear system use SparseCholesky or SuperLU.

See Also:

SparseCholesky, SuperLU, Example 1: Create from arrays, Example 2: Read Matrix Market format, Serialized Form

Nested Class Summary

static class

SparseMatrix.SparseArray The SparseArray class uses public fields to hold the data for a sparse matrix in the Java Sparse Array format.

Constructor Summary

SparseMatrix(int nRows, int nColumns)
Creates a new instance of SparseMatrix.

SparseMatrix(int nRows, int nColumns, int[][] index, double[][] values)
Constructs a sparse matrix from SparseArray (Java Sparse Array) data.

SparseMatrix(SparseMatrix.SparseArray jsa)
Constructs a sparse matrix from a SparseArray object.

SparseMatrix(SparseMatrix A)
Creates a new instance of SparseMatrix which is a copy of another SparseMatrix.

Method Summary

static SparseMatrix	add(double alpha, double beta, SparseMatrix A, SparseMatrix B) Performs element-wise addition of two real sparse matrices A, B of type SparseMatrix,
void	checkSquareMatrix() Check that the matrix is square.
double	frobeniusNorm() Returns the Frobenius norm of the matrix.
double	get(int iRow, int jColumn) Returns the value of an element in the matrix.
int	getNumberOfColumns() Returns the number of columns in the matrix.
long	getNumberOfNonZeros() Returns the number of nonzeros in the matrix.
int	getNumberOfRows() Returns the number of rows in the matrix.
double	infinityNorm() Returns the infinity norm of the matrix.
double[]	multiply(double[] x) Multiply the matrix by a vector.
static double[]	multiply(double[] x, SparseMatrix A) Multiply row array x and sparse matrix A, .
static double[]	multiply(SparseMatrix A, double[] x) Multiply sparse matrix A and column array x, .
static SparseMatrix	multiply(SparseMatrix A, SparseMatrix B) Multiply two sparse matrices A and B, .
static double[]	multiplySymmetric(SparseMatrix A, double[] x) Multiply sparse symmetric matrix A and column vector x.
double	oneNorm() Returns the matrix one norm of the sparse matrix.
double	plusEquals(int iRow, int jColumn, double x) Adds a value to an element in the matrix.
void	set(int iRow, int jColumn, double x) Sets the value of an element in the matrix.
double[][]	toDenseMatrix() Returns the sparse matrix as a dense matrix.
SparseMatrix.SparseArray	toSparseArray() Returns the sparse matrix in the SparseArray form.
SparseMatrix	transpose() Returns the transpose of the matrix.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SparseMatrix

public SparseMatrix(int nRows,
                    int nColumns)

Creates a new instance of SparseMatrix. Initially this is the zero matrix.

Parameters:

nRows - an int containing the number of rows in the sparse matrix.

nColumns - an int containing the number of columns in the sparse matrix.

SparseMatrix

public SparseMatrix(int nRows,
                    int nColumns,
                    int[][] index,
                    double[][] values)

Constructs a sparse matrix from SparseArray (Java Sparse Array) data.

Parameters:

nRows - an int containing the number of rows in the sparse matrix.

nColumns - an int containing the number of columns in the sparse matrix.

index - an int jagged array containing the column indices of all nonzero elements corresponding to the compressed representation of the sparse matrix in values. The size of index must be identical to the size of values. The i-th row contains the column indices of all nonzero elements of row i of the sparse matrix. The j-th element of row i is the column index of the value located at the same position in values.

values - a double jagged array containing the compressed representation of a real sparse matrix of size nRows by nColumns. The number of rows in values must be nRows. The i-th row contains all nonzero elements of row i of the full sparse matrix.

SparseMatrix

public SparseMatrix(SparseMatrix.SparseArray jsa)

Constructs a sparse matrix from a SparseArray object.

Parameters:

jsa - is a SparseArray used to initialize the sparse matrix. The field numberOfNonZeros in jsa is not used for initialization, so it does not have to be set.

SparseMatrix

public SparseMatrix(SparseMatrix A)

Creates a new instance of SparseMatrix which is a copy of another SparseMatrix.

Parameters:

A - the SparseMatrix object containing the sparse matrix to be copied.

Method Detail

add

public static SparseMatrix add(double alpha,
                               double beta,
                               SparseMatrix A,
                               SparseMatrix B)

Performs element-wise addition of two real sparse matrices A, B of type SparseMatrix,

Parameters:

alpha - a double scalar.

beta - a double scalar.

A - a SparseMatrix matrix.

B - a SparseMatrix matrix.

Returns:

a SparseMatrix matrix representing the computed sum.

Throws:

IllegalArgumentException - This exception is thrown when the matrices are not of the same size.

checkSquareMatrix

public void checkSquareMatrix()

Check that the matrix is square.

Throws:

IllegalArgumentException - is thrown if the matrix is not square.

frobeniusNorm

public double frobeniusNorm()

Returns the Frobenius norm of the matrix.

Returns:

a double scalar value equal to the Frobenius norm of the matrix.

get

public double get(int iRow,
                  int jColumn)

Returns the value of an element in the matrix.

Parameters:

iRow - an int containing the row index of the element.

jColumn - an int containing the column index of the element.

Returns:

a double containing the value of the iRow-th and jColumn-th element. If the element was never set, its value is zero.

getNumberOfColumns

public int getNumberOfColumns()

Returns the number of columns in the matrix.

Returns:

an int containing the number of columns in the matrix.

getNumberOfNonZeros

public long getNumberOfNonZeros()

Returns the number of nonzeros in the matrix.

Returns:

a long containing the number of nonzeros in the matrix.

getNumberOfRows

public int getNumberOfRows()

Returns the number of rows in the matrix.

Returns:

an int containing the number of rows in the matrix.

infinityNorm

public double infinityNorm()

Returns the infinity norm of the matrix.

Returns:

a double scalar value equal to the maximum of the row sums of the absolute values of the array elements of the sparse matrix.

multiply

public double[] multiply(double[] x)

Multiply the matrix by a vector.

Parameters:

x - a double column vector.

Returns:

a double vector representing the product of this matrix times x.

Throws:

IllegalArgumentException - This exception is thrown if the number of columns in the SparseMatrix object is not equal to the number of elements in the input column vector.

multiply

public static double[] multiply(double[] x,
                                SparseMatrix A)

Multiply row array x and sparse matrix A, .

Parameters:

x - a double row array.

A - a SparseMatrix matrix.

Returns:

a double vector representing the product of the arguments, .

Throws:

IllegalArgumentException - This exception is thrown when the number of elements in the input vector is not equal to the number of rows of the matrix.

multiply

public static double[] multiply(SparseMatrix A,
                                double[] x)

Multiply sparse matrix A and column array x, .

Parameters:

A - a SparseMatrix matrix.

x - a double column array.

Returns:

a double vector representing the product of the arguments, .

Throws:

IllegalArgumentException - This exception is thrown when the number of columns in the input matrix is not equal to the number of elements in the input column vector.

multiply

public static SparseMatrix multiply(SparseMatrix A,
                                    SparseMatrix B)

Multiply two sparse matrices A and B, .

Parameters:

A - a SparseMatrix sparse matrix.

B - a SparseMatrix sparse matrix.

Returns:

the SparseMatrix product AB of A and B.

Throws:

IllegalArgumentException - This exception is thrown when the number of columns of matrix A is not equal to the number of rows of matrix B.

multiplySymmetric

public static double[] multiplySymmetric(SparseMatrix A,
                                         double[] x)

Multiply sparse symmetric matrix A and column vector x.

Parameters:

A - a SparseMatrix sparse symmetric matrix, where only the lower triangular part of the matrix is to be used.

x - a double vector.

Returns:

a double vector representing the product of the arguments, .

Throws:

IllegalArgumentException - This exception is thrown when the input matrix is not square or the number of columns in the input matrix is not equal to the number of elements in the input column vector.

oneNorm

public double oneNorm()

Returns the matrix one norm of the sparse matrix.

Returns:

a double value equal to the maximum of the column sums of the absolute values of the array elements.

plusEquals

public double plusEquals(int iRow,
                         int jColumn,
                         double x)

Adds a value to an element in the matrix.

Parameters:

iRow - an int containing the row index of the element.

jColumn - an int containing the column index of the element.

x - a double containing the value to be added to the iRow-th and jColumn-th element.

Returns:

a double containing the updated value of the element, which equals its old value plus x.

set

public void set(int iRow,
                int jColumn,
                double x)

Sets the value of an element in the matrix.

Parameters:

iRow - an int containing the row index of the element.

jColumn - an int containing the column index of the element.

x - a double containing the value of the iRow-th and jColumn-th element.

toDenseMatrix

public double[][] toDenseMatrix()

Returns the sparse matrix as a dense matrix.

Returns:

a rectangular Java array of type double containing this matrix with all of the zeros explicitly present. The number of rows and columns in the returned matrix is the same as in the sparse matrix.

toSparseArray

public SparseMatrix.SparseArray toSparseArray()

Returns the sparse matrix in the SparseArray form.

transpose

public SparseMatrix transpose()

Returns the transpose of the matrix.

Returns:

a SparseMatrix object which is the transpose of the constructed SparseMatrix object.