JMSLTM Numerical Library 7.2.0
com.imsl.math

## Class 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`.

`SparseCholesky`, `SuperLU`, Example 1: Create from arrays, Example 2: Read Matrix Market format, Serialized Form
• ### Nested Class Summary

Nested Classes
Modifier and Type Class and Description
`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

Constructors
Constructor and Description
```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

Methods
Modifier and Type Method and Description
`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

```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.
JMSLTM Numerical Library 7.2.0