public class SparseMatrix extends DMatrix implements java.lang.Iterable<SparseMatrix.Entry>
Operations using standard dense matrix structures and algorithms are slow and consume large amounts of memory when applied to large sparse matrices. Indeed, some very large sparse matrices are infeasible to manipulate with the standard dense algorithms. Sparse data is by nature easily compressed, and this compression almost always results in significantly less computer data storage usage.
This class employs Harwell-Boeing column-compressed sparse matrix format. Nonzero values are stored in an array (top-to-bottom, then left-to-right-bottom). The row indices corresponding to the values are also stored. Besides, a list of pointers are indexes where each column starts. This format is efficient for arithmetic operations, column slicing, and matrix-vector products. One typically uses SparseDataset for construction of SparseMatrix.
For iteration through the elements of a matrix, this class provides a functional API to iterate through the non-zero elements. This iteration can be done by passing a lambda to be called on each non-zero element or by processing a stream of objects representing each non-zero element. The direct functional API is faster (and is about as fast as writing the low-level loops against the internals of the matrix itself) while the streaming interface is more flexible.
Modifier and Type | Class and Description |
---|---|
class |
SparseMatrix.Entry
Encapsulates an entry in a matrix for use in streaming.
|
Constructor and Description |
---|
SparseMatrix(double[][] A)
Constructor.
|
SparseMatrix(double[][] A,
double tol)
Constructor.
|
SparseMatrix(int m,
int n,
double[] nonzeros,
int[] rowIndex,
int[] colIndex)
Constructor.
|
Modifier and Type | Method and Description |
---|---|
SparseMatrix |
aat()
Returns A * A'
|
SparseMatrix |
ata()
Returns A' * A
|
SparseMatrix |
clone() |
double[] |
diag()
Returns the diagonal elements.
|
void |
forEachNonZero(DoubleConsumer consumer)
For each loop on non-zero elements.
|
void |
forEachNonZero(int beginColumn,
int endColumn,
DoubleConsumer consumer)
For each loop on non-zero elements.
|
double |
get(int index)
Returns the element at the storage index.
|
double |
get(int i,
int j)
Returns A[i, j].
|
static SparseMatrix |
harwell(java.nio.file.Path path)
Reads a sparse matrix from a Harwell-Boeing Exchange Format file.
|
java.util.Iterator<SparseMatrix.Entry> |
iterator()
Returns an iterator of nonzero entries.
|
java.util.Iterator<SparseMatrix.Entry> |
iterator(int beginColumn,
int endColumn)
Returns an iterator of nonzero entries.
|
SparseMatrix |
mm(SparseMatrix B)
Returns the matrix multiplication C = A * B.
|
void |
mv(double[] work,
int inputOffset,
int outputOffset)
Matrix-vector multiplication A * x.
|
void |
mv(Transpose trans,
double alpha,
double[] x,
double beta,
double[] y)
Matrix-vector multiplication.
|
int |
ncols()
Returns the number of columns.
|
java.util.stream.Stream<SparseMatrix.Entry> |
nonzeros()
Provides a stream over all of the non-zero elements of a sparse matrix.
|
java.util.stream.Stream<SparseMatrix.Entry> |
nonzeros(int beginColumn,
int endColumn)
Provides a stream over all of the non-zero elements of range of columns of a sparse matrix.
|
int |
nrows()
Returns the number of rows.
|
static SparseMatrix |
rutherford(java.nio.file.Path path)
Reads a sparse matrix from a Rutherford-Boeing Exchange Format file.
|
double |
set(int index,
double value)
Sets the element at the storage index.
|
SparseMatrix |
set(int i,
int j,
double x)
Sets A[i, j] = x.
|
long |
size()
Returns the number of stored matrix elements.
|
static SparseMatrix |
text(java.nio.file.Path path)
Reads a sparse matrix from a text file.
|
SparseMatrix |
transpose()
Returns the transpose of matrix.
|
void |
tv(double[] work,
int inputOffset,
int outputOffset)
Matrix-vector multiplication A' * x.
|
apply, market, mv, mv, mv, trace, tv, tv, tv, update
colName, colNames, colNames, rowName, rowNames, rowNames, toString, toString, toString
public SparseMatrix(int m, int n, double[] nonzeros, int[] rowIndex, int[] colIndex)
m
- the number of rows in the matrix.n
- the number of columns in the matrix.rowIndex
- the row indices of nonzero values.colIndex
- the index of the start of columns.nonzeros
- the array of nonzero values stored column by column.public SparseMatrix(double[][] A)
A
- a dense matrix to converted into sparse matrix format.public SparseMatrix(double[][] A, double tol)
A
- a dense matrix to converted into sparse matrix format.tol
- the tolerance to regard a value as zero if |x| < tol.public SparseMatrix clone()
clone
in class java.lang.Object
public int nrows()
IMatrix
public int ncols()
IMatrix
public long size()
IMatrix
public java.util.stream.Stream<SparseMatrix.Entry> nonzeros()
public java.util.stream.Stream<SparseMatrix.Entry> nonzeros(int beginColumn, int endColumn)
beginColumn
- The beginning column, inclusive.endColumn
- The end column, exclusive.public java.util.Iterator<SparseMatrix.Entry> iterator()
iterator
in interface java.lang.Iterable<SparseMatrix.Entry>
public java.util.Iterator<SparseMatrix.Entry> iterator(int beginColumn, int endColumn)
beginColumn
- The beginning column, inclusive.endColumn
- The end column, exclusive.public void forEachNonZero(DoubleConsumer consumer)
Note that the consumer could be called on values that are either effectively or actually zero. The only guarantee is that no values that are known to be zero based on the structure of the matrix will be processed.
consumer
- The matrix element consumer.public void forEachNonZero(int beginColumn, int endColumn, DoubleConsumer consumer)
Note that the consumer could be called on values that are either effectively or actually zero. The only guarantee is that no values that are known to be zero based on the structure of the matrix will be processed.
beginColumn
- The beginning column, inclusive.endColumn
- The end column, exclusive.consumer
- The matrix element consumer.public double get(int index)
public double set(int index, double value)
public double get(int i, int j)
DMatrix
public SparseMatrix set(int i, int j, double x)
DMatrix
public void mv(Transpose trans, double alpha, double[] x, double beta, double[] y)
DMatrix
y = alpha * op(A) * x + beta * y
where op is the transpose operation.public void mv(double[] work, int inputOffset, int outputOffset)
IMatrix
public void tv(double[] work, int inputOffset, int outputOffset)
IMatrix
public SparseMatrix transpose()
public SparseMatrix mm(SparseMatrix B)
public SparseMatrix ata()
public SparseMatrix aat()
public double[] diag()
DMatrix
public static SparseMatrix harwell(java.nio.file.Path path) throws java.io.IOException
path
- the input file path.java.io.IOException
public static SparseMatrix rutherford(java.nio.file.Path path) throws java.io.IOException
path
- the input file path.java.io.IOException
public static SparseMatrix text(java.nio.file.Path path) throws java.io.IOException
Following the first line, there are m + 1 integers that are the indices of columns, where m is the number of columns. Then there are n integers that are the row indices of nonzero entries, where n is the number of nonzero entries. Finally, there are n float numbers that are the values of nonzero entries.
path
- the input file path.java.io.IOException