Seldon user's guide

First, methods and functions related to sparse matrices stored as a vector of sparse rows are detailed. This type of matrix is interesting because it allows fast insertion of elements in the matrix. Then the matrices using Harwell-Boeing format are detailed. Functions related to sparse matrices are explained. Row and column indices start at 0, as for dense matrices.

Basic declaration of easily modifiable sparse matrices:

These matrices are available only after SeldonSolver.hxx (or SeldonLib.hxx) has been included.

Classes :

Matrix<T, Prop, ArrayRowSparse>
Matrix<T, Prop, ArrayColSparse>
Matrix<T, Prop, ArrayRowSymSparse>
Matrix<T, Prop, ArrayColSymSparse>

Example :

// sparse matrix of doubles
Matrix<double, General, ArrayRowSparse> A;

// sparse symmetric matrix
Matrix<float, Symmetric, ArrayRowSymSparse> B;

// changing size of the matrix
A.Reallocate(m, n);

// a_13 = a_13 + 1.5
A.AddInteraction(1, 3, 1.5);

Methods for easily modifiable sparse matrices :

Matrix constructors
Matrix operators
GetM	returns the number of rows in the matrix
GetN	returns the number of columns in the matrix
GetDataSize	returns the number of elements effectively stored
GetNonZeros	returns the number of elements effectively stored
GetMemorySize	returns the memory used to store the matrix
GetData	returns a pointer to the array containing the values
GetIndex	returns a pointer to the array containing column numbers
SetData	sets the pointer to the arrays containing values and column numbers
Nullify	removes elements of the matrix without releasing memory
Clear	removes all elements of the matrix
Reallocate	changes the size of matrix (does not keep previous elements)
Resize	changes the size of matrix (keeps previous elements)
Value	direct access to a value
Index	direct access to a column number
Val	direct access to A(i, j)
Get	access to A(i, j)
Set	modification of A(i, j)
RemoveSmallEntry	drops small values of the matrix
Zero	sets all elements to zero
SetIdentity	sets matrix to identity matrix
Fill	sets all elements to a given value
FillRand	fills randomly the matrix
ReallocateRow / ReallocateColumn	changes the size of a row
ResizeRow / ResizeColumn	changes the size of a row and keeps previous values
ClearRow / ClearColumn	clears a row
SwapRow / SwapColumn	exchanges two rows
ReplaceIndexRow / ReplaceIndexColumn	changes column numbers
GetRowSize / GetColumnSize	returns the number of elements in the row
PrintRow / PrintColumn	prints a row
AssembleRow / AssembleColumn	assembles a row
Assemble	assembles the matrix
AddInteraction	adds/inserts an element in the matrix
AddInteractionRow	adds/inserts an element in a matrix row
AddInteractionColumn	adds/inserts elements in a matrix column
Print	displays the matrix
Write	writes the vector in binary format
Read	reads the vector in binary format
WriteText	writes the vector in text format
ReadText	reads the vector in text format

Another class of storage of sparse matrices is available, the so-called Harwell-Boeing format. The values are stored in a single array, preventing from a fast insertion of elements. Nevertheless, this type of storage requires slightly less memory and the associated matrix-vector product is more efficient.

Basic declaration of Harwell-Boeing sparse matrices:

Classes :

Matrix<T, Prop, RowSparse>
Matrix<T, Prop, ColSparse>
Matrix<T, Prop, RowSymSparse>
Matrix<T, Prop, ColSymSparse>

Example :

// sparse matrix of doubles 
Matrix<double, General, RowSparse> A;

// sparse symmetric matrix
Matrix<float, Symmetric, RowSymSparse> B;

Methods for Harwell-Boeing sparse matrices :

Matrix constructors
Matrix operators
GetM	returns the number of rows in the matrix
GetN	returns the number of columns in the matrix
GetDataSize	returns the number of elements effectively stored
GetNonZeros	returns the number of elements effectively stored
GetData	returns a pointer to the array containing the values
GetInd	returns a pointer to the array containing column numbers
GetPtr	returns a pointer to the array containing start indices of rows
GetPtrSize	returns size of array Ptr
GetIndSize	returns size of array Ind
Clear	removes all elements of the matrix
SetData	sets the pointer to the array containing the values
Nullify	clears the matrix without releasing memory
Reallocate	modifies the size of the matrix
Resize	modifies the size of the matrix
Val	direct access to A(i, j)
Get	access to A(i, j)
Val	modification of A(i, j)
SetIdentity	initializes the sparse matrix to identity
Fill	fills non-zero entries to a given value
FillRand	fills non-zero entries to random values
Print	displays the matrix
Write	writes the vector in binary format
Read	reads the vector in binary format
WriteText	writes the vector in text format
ReadText	reads the vector in text format

Functions :

Mlt	multiplication by a scalar or matrix-vector product
MltAdd	performs a matrix-vector product
Add	adds two matrices
Copy	copies/converts one matrix into another one
ApplyPermutation	applies permutation to matrix
ApplyInversePermutation	applies inverse permutation to matrix
ScaleMatrix	applies a scaling both for columns and rows
ScaleLeftMatrix	applies a left scaling (on rows)
ScaleRightMatrix	applies a left scaling (on columns)
GetRow	returns a matrix row
SetRow	changes a matrix row
GetCol	returns a matrix column
SetCol	changes a matrix column
GetLU	performs a LU (or LDL^t) factorization
MaxAbs	returns infinity norm of a matrix
Norm1	returns 1-norm of a matrix
NormInf	returns infinity-norm of a matrix
Transpose	computes transpose of a matrix
TransposeConj	computes conjugate transpose of a matrix
Conjugate	conjugates a matrix
SolveLU	solves linear system by using LU factorization
SOR	applies successive over-relaxations to matrix
Cg, Gmres, BiCgSTAB, etc	solves iteratively a linear system
ReadCoordinateMatrix	reads a matrix in coordinate format (as in Matlab)
WriteCoordinateMatrix	writes a matrix in coordinate format (as in Matlab)
ReadHarwellBoeing	reads a matrix in Harwell-Boeing format
WriteHarwellBoeing	writes a matrix in Harwell-Boeing format
ReadMatrixMarket	reads a matrix in Matrix Market format
WriteMatrixMarket	writes a matrix in Matrix Market format

Matrix constructors for ArrayRowSparse, ArrayRowSymSparse

Syntax :

  Matrix();
  Matrix(int m, int n);

Example :

// default constructor -> empty matrix
Matrix<double, General, ArrayRowSparse> V;
cout << "Number of elements "<< V.GetDataSize() << endl; // should return 0 
// then you can use Reallocate to set the number of rows and columns
V.Reallocate(3, 2);
// the last command doesn't create any non-zero element
// you can create one with AddInteraction for example
V.AddInteraction(0, 1, 1.5);

// we construct symmetric matrix with 4 rows
Matrix<double, Symmetric, ArrayRowSymSparse> W(4, 4);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Matrix constructors for RowSparse, RowSymSparse

Syntax :

  Matrix();
  Matrix(int m, int n);
  Matrix(int m, int n, int nnz);
  Matrix(m, n, values, ptr, ind);

Example :

// default constructor -> empty matrix
Matrix<double, General, RowSparse> V;
cout << "Number of elements "<< V.GetDataSize() << endl; // should return 0 

// with this constructor, an empty matrix with 4 rows and columns is constructed
Matrix<double, Symmetric, RowSymSparse> W(4, 4);

// Here a matrix with 3 rows, 4 columns and 10 non-zero entries
// however non-zero entries are not initialized, you can
// set them by modifying arrays returned by GetPtr(), GetInd(), GetData()
Matrix<double, General, RowSparse> A(3, 4, 10);

// in the last constructor you provide
int m = 5; // number of rows
int n = 6; // number of columns
int nnz = 12; // number of non-zero entries
Vector<double> values(nnz); // values
values.FillRand(); // you have to initialize values
Vector<int> columns(nnz); // for each value column number
// for each row, column numbers are sorted
// first row
columns(0) = 0;
columns(1) = 2;
columns(2) = 4;
// second row
columns(3) = 1;
// third row
columns(4) = 0;
columns(5) = 1;
columns(6) = 3;
// fourth row
columns(7) = 4;
columns(8) = 5;
// last row
columns(9) = 2;
columns(10) = 3;
columns(11) = 5;
// for each row, index of first value
Vector<int> ptr(m+1); 
ptr(0) = 0;
ptr(1) = 3;
ptr(2) = 4;
ptr(3) = 7;
ptr(4) = 9;
ptr(5) = 12;
// values on the row are to be seeked between ptr(i) and ptr(i+1)

// Now the constructor:
Matrix<double, General, RowSparse> M(m, n, values, ptr, columns);
// Note that 'values', 'ptr' and 'columns' are nullified (that is, emptied):
// the arrays to which they pointed have been transferred to M.

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx

Matrix operators for ArrayRowSparse, ArrayRowSymSparse

Syntax :

  const T& operator (int i, int j) const;
  Matrix& operator =(const T0& alpha)

The operator () cannot be used to insert or modify elements of matrix, unless the flag SELDON_WITH_MODIFIABLE_PARENTHESIS_OPERATOR is set during the compilation. Use rather the methods Get or Val.

Example :

Matrix<double, General, ArrayRowSparse> V(3, 3);
// use of operator () to know the value of A(i, j);
cout << V(2, 0) << endl;

// this command will add a non-zero entry v_20
cout << V(2, 0) << endl;

// set all elements to a given value
V = 1;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Matrix operators for RowSparse, RowSymSparse

Syntax :

  T operator (int i, int j) const;

The operator () cannot be used to insert or modify elements of matrix.

Example :

Matrix<double, General, RowSparse> V(3, 3);
// use of operator () to read elements of matrix
cout << "V(0,0) = " << V(0, 0) << endl;

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx

GetM

Syntax :

  int GetM() const;

This method returns the number of rows.

Example :

Matrix<float, General, ArrayRowSparse> V(3, 2);
// V.GetM() should return 3 
cout << "Number of rows of V " << V.GetM() << endl;

Location :

Class Matrix_Base
Class Matrix_ArraySparse
Matrix_Base.hxx Matrix_Base.cxx
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

GetN

Syntax :

  int GetN() const;

This method returns the number of columns.

Example :

Matrix<float, Symmetric, ArrayRowSymSparse> V(3, 2);
// V.GetN() should return 2 
cout << "Number of rows of V " << V.GetN() << endl;

Location :

Class Matrix_Base
Class Matrix_ArraySparse
Matrix_Base.hxx Matrix_Base.cxx
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

GetDataSize, GetNonZeros

Syntax :

  int GetDataSize() const;
  int GetNonZeros() const;

These methods returns the number of elements effectively stored in the matrix.

Example :

Matrix<float, Symmetric, ArrayRowSymSparse> V(3, 3);
V.AddInteraction(0, 1, 1.0);
// V.GetDataSize() should return 1
cout << "Number of elements of V " << V.GetDataSize() << endl;

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Class Matrix_ArraySparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

GetMemorySize

Syntax :

  size_t GetMemorySize() const;

This methods returns the memory used to store in the matrix in bytes.

Example :

Matrix<float, Symmetric, ArrayRowSymSparse> V(3, 3);
V.AddInteraction(0, 1, 1.0);
// V.GetDataSize() should return 1
cout << "Memory used to store V " << V.GetMemorySize() << endl;

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Class Matrix_ArraySparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

GetData for ArrayRowSparse, ArrayRowSymSparse

Syntax :

  T* GetData(int i) const;
  Vector<T, Vect_Sparse, Allocator>* GetData() const;

These methods are useful to retrieve the pointer to the values, but they need to be used with caution.

Example :

Matrix<double, General, ArrayRowSparse> V(3, 4); V.Fill();
// values of second row are retrieved
int irow = 1;
double* data = V.GetData(irow);
// you can use data as a normal C array
// here the sum of elements of the row is computed
double sum = 0;
for (int i = 0; i < V.GetRowSize(irow); i++)
  sum += data[i];

// you can also retrieve all the rows
Vector<double, Vect_Sparse>* all_rows = V.GetData();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

GetIndex for ArrayRowSparse, ArrayRowSymSparse

Syntax :

  void GetIndex(int);

This method returns the pointer to the array containing column numbers of the specified row.

Example :

Matrix<double, General, ArrayRowSparse> A;
// you retrieve column numbers of row 1
IVect col;
int irow = 1;
col.SetData(A.GetRowSize(irow), A.GetIndex(irow));
// after use of col, don't forget to call Nullify
col.Nullify();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

SetData for ArrayRowSparse, ArrayRowSymSparse

Syntax :

  void SetData(int, int, T*, int*);
  void SetData(int, int, Vector<T, Vect_Sparse>*);

This method changes a row of the matrix or all the rows by directly changing pointers. This is a low-level method and should be used very cautiously. It is better to use other methods to modify the matrix.

Example :

// first use, you construct all the rows
int m = 10, n = 9;
Vector<Vector<double, Vect_Sparse> > rows(m);

rows(0).AddInteraction(1, 2.4);
rows(1).AddInteraction(3, -1.2);
// ...

// then you can feed a sparse matrix with rows
Matrix<double, General, ArrayRowSparse> A;
A.SetData(m, n, rows.GetData());
// you nullify rows to avoid segmentation fault
rows.Nullify();

// second use, you specify one row
Vector<double, Vect_Sparse> one_row;
one_row.AddInteraction(4, 2.3);
one_row.AddInteraction(0, -0.7);
// and you put it in the matrix
int irow = 2;
A.SetData(irow, one_row.GetM(), one_row.GetData(), one_row.GetIndex());
one_row.Nullify();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Nullify for ArrayRowSparse, ArrayRowSymSparse

Syntax :

  void Nullify();
  void Nullify(int);

This method clears the matrix without releasing memory. You can also clear a single row. This method should be used carefully, and generally in conjunction with method SetData.

Example :

Matrix<double, General, ArrayRowSparse> A;
// you retrieve one row of A
int irow = 2;
Vector<double, Vect_Sparse> one_row;
one_row.SetData(A.GetRowSize(irow), A.GetData(irow), A.GetIndex(irow));
// you need to call Nullify to avoid segmentation fault
A.Nullify(irow);

// you can retrieve all the rows
Vector<Vector<double, Vect_Sparse> > rows;
rows.SetData(m, A.GetData());
// again Nullify is necessary
A.Nullify();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Clear

Syntax :

  void Clear();

This method removes all the elements of the matrix.

Example :

Matrix<double, General, ArrayRowSparse> A(3, 3);
A.AddInteraction(0, 2, 2.8);
// clears matrix A
A.Clear();

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Class Matrix_ArraySparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Reallocate

Syntax :

  void Reallocate(int, int);

This method changes the size of the matrix, but removes previous elements.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 4);
A.AddInteraction(0, 2, 2.8);
// resizes matrix A
A.Reallocate(4, 3);
// previous elements are removed : A is empty
cout << "number of non-zero entries " << A.GetDataSize() << endl;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Resize

Syntax :

  void Resize(int, int);

This method changes the size of the matrix, and keeps previous elements.

Example :

Matrix<double, Symmetric, ArrayRowSymSparse> A(4,4);
A(1,3) = 2.0;
A(0,2) = -1.0;
// resizes matrix A and keeps previous added interactions
A.Resize(5,5);
// GetDataSize() should return 2
cout << "number of non-zero entries of A " << A.GetDataSize() << endl;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

GetData for RowSparse, RowSymSparse

Syntax :

  T* GetData() const;

This method retrieves the pointer to the values.

Example :

// construction of a sparse matrix
Matrix<double, General, RowSparse> V(m, n, nnz, values, ptr, columns);
// values of non-zero entries are retrieved
double* data = V.GetData();
// you can use data as a normal C array
// here the sum of elements is computed
double sum = 0;
for (int i = 0; i < V.GetDataSize(); i++)
  sum += data[i];

Location :

Class Matrix_Base
Matrix_Base.hxx Matrix_Base.cxx

GetInd, GetIndSize for RowSparse, RowSymSparse

Syntax :

  int* GetInd() const;
  int GetIndSize() const;

This method retrieves the pointer to the column numbers of each row, GetIndSize giving the size of this array.

Example :

// construction of a sparse matrix (m = number of rows)
Matrix<double, General, RowSparse> V(m, n, nnz, values, ptr, columns);
// we get column numbers
int* ind = V.GetInd();
// and also the size of this array (should be nnz)
int size = V.GetIndSize();
// you can use data as a normal C array
// here the number of elements of each column is computed
Vector<int> size_col(n);
size_col.Zero();
for (int i = 0; i < nnz; i++)
  size_col(ind[i])++;

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx

GetPtr, GetPtrSize for RowSparse, RowSymSparse

Syntax :

  int* GetPtr() const;
  int GetPtrSize() const;

This method retrieves the pointer to the indices of the first element of each row. GetPtrSize() returns the size of this array, it should be equal to m+1 for RowSparse and n+1 for ColSparse storage.

Example :

// construction of a sparse matrix (m = number of rows)
Matrix<double, General, RowSparse> V(m, n, nnz, values, ptr, columns);
// we get indices of the first element of each row
int* ptr = V.GetPtr();
// and also the size of this array (should be number of rows + 1)
int size = V.GetPtrSize();
// you can use data as a normal C array
// here the number of elements of each row is computed
Vector<int> size_row(m);
for (int i = 0; i < m; i++)
  size_row(i) = ptr[i+1] - ptr[i];

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx

SetData for RowSparse, RowSymSparse

Syntax :

  void SetData(int, int, int, T*, int*, int*);
  void SetData(int, int, Vector<T>, Vector<int>, Vector<int>);

This method initializes the matrix and is equivalent to a call to the constructor.

Example :

// first you construct the matrix by using arrays ptr, values, columns
int m = 5; // number of rows
int n = 6; // number of columns
int nnz = 12; // number of non-zero entries
Vector<double> values(nnz); // values
values.FillRand(); // you have to initialize values
Vector<int> columns(nnz); // for each value column number
// for each row, column numbers are sorted
// first row
columns(0) = 0;
columns(1) = 2;
columns(2) = 4;
// second row
columns(3) = 1;
// third row
columns(4) = 0;
columns(5) = 1;
columns(6) = 3;
// fourth row
columns(7) = 4;
columns(8) = 5;
// last row
columns(9) = 2;
columns(10) = 3;
columns(11) = 5;
// for each row, index of first value
Vector<int> ptr(m+1); 
ptr(0) = 0;
ptr(1) = 3;
ptr(2) = 4;
ptr(3) = 7;
ptr(4) = 9;
ptr(5) = 12;

// then you call SetData
Matrix<double, General, RowSparse> A;
A.SetData(m, n, values, ptr, columns);

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx

Nullify

Syntax :

  void Nullify();

This method clears the matrix without releasing memory. This method should be used carefully, and generally in conjunction with method SetData. You can look at the example shown in the explanation of method SetData.

Location :

Class Matrix_Sparse
Class Matrix_SymSparse
Matrix_Sparse.hxx Matrix_Sparse.cxx
Matrix_SymSparse.hxx Matrix_SymSparse.cxx

Value

Syntax :

  const T& Value(int, int) const;
  T& Value(int, int);

This method allows the user to modify directly the values.

Example :

// declaration of a sparse matrix
int m = 5;
int n = 4;
Matrix<double, General, ArrayRowSparse> V(m, n);

// we set the number of non-zero entries of first row
V.ReallocateRow(0, 2);
// you initialize column numbers with Index, and values with Value
V.Index(0, 0) = 1; V.Value(0, 0) = 0.5;
V.Index(0, 1) = 3; V.Value(0, 1) = -0.5;
// now matrix should be equal to [0 1 -0.5; 0 3 -0.5]
cout << " V = " << V << endl;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Index

Syntax :

  int Index(int, int) const;
  int& Index(int, int);

This method allows the user to modify directly the column numbers. The drawback of this method is that the user has to take care that the column numbers are sorted and unique (no duplicate). If this is not the case, you need to call AssembleRow in order to sort the row.

Example :

// declaration of a sparse matrix
int m = 5;
int n = 4;
Matrix<double, General, ArrayRowSparse> V(m, n);

// we set the number of non-zero entries of first row
V.ReallocateRow(0, 2);
// you initialize column numbers with Index, and values with Value
V.Index(0, 0) = 1; V.Value(0, 0) = 0.5;
V.Index(0, 1) = 3; V.Value(0, 1) = -0.5;
// now matrix should be equal to [0 1 -0.5; 0 3 -0.5]
cout << " V = " << V << endl;

// if you add a new value on the first row
V.ResizeRow(0, 3);
V.Index(0, 2) = 0; V.Value(0, 2) = 1.1;
// you better be careful because the new entry is not at the correct
position
// one way to fix that problem is to call AssembleRow
V.AssembleRow(0);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Val

Syntax :

  T& Val(int, int);

This method allows the user to modify A(i, j), if there is a non-zero entry present at this position. If no such non-zero entry exists, an exception is raised in the debug mode (and a segmentation fault may occur if the debugging flag is disabled).

Example :

// declaration of a sparse matrix
int m = 5;
int n = 4;
Matrix<double, General, ArrayRowSparse> V(m, n);

// use of Get to add non-zero entries
V.Get(4, 2) = 4.3;
V.Get(0, 3) = -1.5;
V.Get(1, 1) = 2.4;

// then created non-zero entries can be modified with Val
V.Val(0, 3) = 0.8;

// if you try to access an absent non-zero entry, an exception will be raised
V.Val(3, 3) = 1.1; // incorrect

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Get

Syntax :

  T& Get(int, int);

This method allows the user to modify A(i, j). If there is no non-zero entry at this position, it is created. If you want to be sure that this method does not create a non-zero entry (because you are sure that only the initial profile of the matrix is modified), you can call Val and see if an error occurs. If you want to modify more values of the row, it can be better to use AddInteractionRow.

Example :

// declaration of a sparse matrix
int m = 5;
int n = 4;
Matrix<double, General, ArrayRowSparse> V(m, n);

// use of Get to add non-zero entries
V.Get(4, 2) = 4.3;
V.Get(0, 3) = -1.5;
V.Get(1, 1) = 2.4;

// then created non-zero entries can be modified with Val
V.Val(0, 3) = 0.8;

// if you try to access an absent non-zero entry, an exception will be raised
V.Val(3, 3) = 1.1; // incorrect

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Set

Syntax :

  void Set(int i, int j, T val);

This method allows the user to set directly A(i, j). If there is no non-zero entry at this position, it is created. If you want to modify A(i, j) (by adding a value or multiplying it by a coefficient), it is better to use AddInteraction or Get.

Example :

// declaration of a sparse matrix
int m = 5;
int n = 4;
Matrix<double, General, ArrayRowSparse> V(m, n);

// use of Get to add non-zero entries
V.Get(4, 2) = 4.3;
V.Get(0, 3) = -1.5;
V.Get(1, 1) = 2.4;

// or use of Set
V.Set(1, 3, -2.1);
V.Set(4, 2, 1.8);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

RemoveSmallEntry

Syntax :

  void RemoveSmallEntry(const T& epsilon);

This method removes all non-zero entries whose value is below a threshold epsilon.

Example :

Matrix<double, General, ArrayRowSparse> V(5, 4);
// initialization with some values
V.Get(2, 3) = 1.5;
V.Get(4, 1) = -0.8;
V.Get(1, 2) = 0.01;
V.Get(0, 0) = 2.9;

// values below 0.1 are cleared (here, non-zero entry A(1, 2) will be removed)
V.RemoveSmallEntry(0.1);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Zero

Syntax :

  void Zero();

This method sets to 0 all values contained in non-zero entries. This is useful when you want to keep the pattern of the sparse matrix, but initialize values to 0. If you wish to remove the pattern, you can use Clear or Reallocate.

Example :

Matrix<double, General, ArrayRowSparse> V(5, 3);
// creation of pattern
V.AddInteraction(0, 3, 1.0);
V.AddInteraction(2, 4, -1.0);

// values are set to 0
V.Zero();

// then you can modify values of the pattern
V.Val(0, 3) += 1.5;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

SetIdentity

Syntax :

  void SetIdentity();

This method sets all elements to 0, except on the diagonal set to 1. This forms the so-called identity matrix.

Example :

Matrix<double, Symmetric, ArrayRowSymSparse> V(5, 5);
// initialization
V.SetIdentity();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Fill

Syntax :

  void Fill();
  void Fill(const T0& );

This method fills matrix with 0, 1, 2, etc or with a given value. It fills values of the profile of the matrix (the profile is not modified here).

Example :

Matrix<double, General, ArrayRowSparse> A(5,5);
A(1,2) = 3;
A(2,4) = 5;
A(3,0) = 6;
A.Fill();
// A should contain [1 2 0.0, 2 4 1.0, 3 0 2.0]

A.Fill(2);
// A should contain [1 2 2.0, 2 4 2.0, 3 0 2.0]

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

FillRand

Syntax :

  void FillRand();
  void FillRand(int Nelement);

This method sets values of non-zero entries randomly, while keeping the profile. If you wish to construct a completely random sparse matrix (a random profile with random values), FillRand(Nelement) is available for RowSparse storage only. It creates Nelement non-zero entries with a random value.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 3);
A(1,2) = 0.1;
A(2,4) = 0.1;
A.FillRand();
// A should contain 2 non-zero entries with random values

// with RowSparse, you can create 100 non-zero entries placed randomly :
Matrix<double, General, RowSparse> B(45, 51);
B.FillRand(100);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

ReallocateRow / ReallocateColumn

Syntax :

  void ReallocateRow(int, int );

ReallocateColumn is the name used for storages ArrayColSparse and ArrayColSymSparse. This method creates n non-zero entries in specified row.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 6);
// for second row, we create 3 non-zero entries
int irow = 1;
int n = 3;
A.ReallocateRow(irow, n);
// you need to initialize elements of the row
A.Index(irow, 0) = 0; A.Value(irow, 0) = 0.5;
A.Index(irow, 1) = 2; A.Value(irow, 1) = -0.4;
A.Index(irow, 2) = 3; A.Value(irow, 2) = 0.6;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

ResizeRow / ResizeColumn

Syntax :

  void ResizeRow(int, int );

ResizeColumn is the name used for storages ArrayColSparse and ArrayColSymSparse. This method creates n non-zero entries in specified row, and keeps previous elements.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 6);
// for second row, we create 3 non-zero entries
int irow = 1;
int n = 3;
A.ReallocateRow(irow, n);
// you need to initialize elements of the row
A.Index(irow, 0) = 0; A.Value(irow, 0) = 0.5;
A.Index(irow, 1) = 2; A.Value(irow, 1) = -0.4;
A.Index(irow, 2) = 3; A.Value(irow, 2) = 0.6;

// you can change the size of the row
A.ResizeRow(irow, n+1);
// you need to initialize only the new entry
A.Index(irow, 3) = 5; A.Index(irow, 3) = 3.5;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

ClearRow / ClearColumn

Syntax :

  void ClearRow(int,);

ClearColumn is the name used for storages ArrayColSparse and ArrayColSymSparse. This method removes non-zero entries in specified row.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 6);
A(1, 3) = 4.0; // one non-zero entry in second row
// we clear second row
A.ClearRow(1);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

SwapRow / SwapColumn

Syntax :

  void ClearRow(int);

SwapColumn is the name used for storages ArrayColSparse and ArrayColSymSparse. This method swaps two rows. This method should be used very cautiously for symmetric matrices, since in that case only upper part of the matrix is stored.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 6);
A(1, 3) = 4.0; // one non-zero entry in second row
A(2, 4) = -1.0;
// we swap third and second row
A.SwapRow(1, 2);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

ReplaceIndexRow / ReplaceIndexColumn

Syntax :

  void ReplaceIndexRow(int, Vector<int>&);

ReplaceIndexColumn is the name used for storages ArrayColSparse and ArrayColSymSparse. This method changes column numbers of the specified row.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 6);
A(1, 3) = 4.0;
A(1, 4) = -1.0;
// we change column numbers of second row
IVect new_number(2);
new_number(0) = 0;
new_number(1) = 2;
A.ReplaceIndexRow(1, new_number);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

GetRowSize / GetColumnSize

Syntax :

  void GetRowSize(int) const;

GetColumnSize is the name used for storages ArrayColSparse and ArrayColSymSparse. This method returns the number of non-zero entries in the specified row.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 6);
A(1, 3) = 4.0; 
A(1, 4) = -1.0;
// two non-zero entries in second row
cout << "Number of elements in second row " << A.GetRowSize(1) << endl;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

PrintRow / PrintColumn

Syntax :

  void PrintRow(int) const;

PrintColumn is the name used for storages ArrayColSparse and ArrayColSymSparse. This method prints non-zero entries in the specified row.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 6);
A(1, 3) = 4.0; 
A(1, 4) = -1.0;
// we print second row
cout << "Second row of A " << A.PrintRow(1) << endl;

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

AssembleRow / AssembleColumn

Syntax :

  void AssembleRow(int);

AssembleColumn is the name used for storages ArrayColSparse and ArrayColSymSparse. This method sorts and merges non-zero entries of a row. You don't need to call this method if you are using methods AddInteraction, AddInteractionRow, Get or Set.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 5);
A.ReallocateRow(1, 3);
// we initialize non-zero entries but non-sorted and with duplicates
A.Index(1, 0) = 4; A.Value(1, 0) = 1.2;
A.Index(1, 1) = 2; A.Value(1, 1) = -0.7;
A.Index(1, 2) = 4; A.Value(1, 2) = 2.5;

// we sort column numbers of row 1
A.AssembleRow(1);
// now A should be equal to [1 2 -0.7, 1 4 3.7]

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Assemble

Syntax :

  void Assemble();

This method sorts and merges non-zero entries of all the rows. You don't need to call this method if you are using methods AddInteraction, AddInteractionRow, Get or Set.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 5);
A.ReallocateRow(1, 3);
// we initialize non-zero entries but non-sorted and with duplicates
A.Index(1, 0) = 4; A.Value(1, 0) = 1.2;
A.Index(1, 1) = 2; A.Value(1, 1) = -0.7;
A.Index(1, 2) = 4; A.Value(1, 2) = 2.5;

A.ReallocateRow(2, 2);
// we initialize non-zero entries but non-sorted and with duplicates
A.Index(2, 0) = 3; A.Value(2, 0) = 0.9;
A.Index(2, 1) = 1; A.Value(2, 1) = 0.6;

// we sort column numbers for all the rows
A.Assemble();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

AddInteraction

Syntax :

  void AddInteraction(int, int, T);

This methods adds/inserts a value in the matrix. This is "almost" equivalent to use the method Get() in conjunction with operator +=. Indeed, this is truly equivalent for unsymmetric matrices. However, it is different for symmetric matrices, since in that case AddInteraction ignores values given on the lower part of the matrix, whereas Get() will modify the corresponding non-zero entry located in the upper part. The advantage here is that if you fill a matrix with AddInteraction/AddInteractionRow, you don't have to change your function if the matrix is symmetric or not. If you are using the methods Get or Set, you will have to be careful to not add twice the same value because A.Get(j, i) and A.Get(i, j) will point to the same address for symmetric matrices.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 5);
// insertion
A.AddInteraction(1, 3, 2.6);
// we add
A.AddInteraction(1, 3, -1.0);
// now A should be equal to [1 3 1.6]

// for symmetric matrices, only upper part is considered
Matrix<double, General, ArrayRowSymSparse> B(10, 10);
B.AddInteraction(4, 7, -0.8);
B.AddInteraction(7, 4, -0.8); 
// B(4, 7) and B(7, 4) will be equal to -0.8
B.AddInteraction(3, 5, 2.2);
B.AddInteraction(5, 3, 0.9);
// B(3, 5) and B(5, 3) will be equal to 2.2

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

AddInteractionRow

Syntax :

  void AddInteractionRow(int, int, Vector<int>, Vector<T>);

This methods adds/inserts several values in a row of the matrix. This is more efficient to use that method rather than calling AddInteraction several times. For symmetric matrices, the interactions belonging to the lower part of the matrix will be ignored. The advantage of this behaviour is that you can use the same code for filling a symmetric and an unsymmetric matrix.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 5);
// insertion, you don't need to sort column numbers
int irow = 2;
int nb_values = 3;
IVect col(nb_values);
Vector<double> values(nb_values);
col(0) = 0; values(0) = 0.1;
col(1) = 3; values(1) = 0.6;
col(2) = 2; values(2) = -1.4;

A.AddInteractionRow(irow, nb_values, col, values);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

AddInteractionColumn

Syntax :

  void AddInteractionColumns(int, int, Vector<int>, Vector<T>);

This methods adds/inserts several values in a column of the matrix. For symmetric matrices, the interactions belonging to the lower part of the matrix will be ignored. The advantage of this behaviour is that you can use the same code for filling a symmetric and an unsymmetric matrix.

Example :

Matrix<double, General, ArrayRowSparse> A(5, 5);
// insertion, you don't need to sort row numbers
int icol = 2;
int nb_values = 3;
IVect row(nb_values);
Vector<double> values(nb_values);
row(0) = 0; values(0) = 0.1;
row(1) = 3; values(1) = 0.6;
row(2) = 2; values(2) = -1.4;

A.AddInteractionColumn(icol, nb_values, row, values);

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Print

Syntax :

  void Print() const;

This method displays the matrix.

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Write

Syntax :

  void Write(string) const;
  void Write(ofstream&) const;

This method writes the matrix on a file/stream in binary format. The file will contain the number of rows, columns, non-zero entries, then the array of values, indices of first elements of rows, and finally the array of column numbers. The format will be different for each storage, therefore it is not very portable. It can be useful if you have written a matrix with Seldon on a disk, and you can read it (if the same storage, e.g. RowSparse is used). For "portable" formats, use rather WriteText.

Example :

// construction of a sparse matrix
Matrix<double, General, RowSparse> A(m, n, nnz, values, ptr, columns); 
// you can write directly in a file
A.Write("matrix.dat");

// or open a stream with other datas
ofstream file_out("matrix.dat");
int my_info = 3;
file_out.write(reinterpret_cast<char*>(&my_info), sizeof(int));
A.Write(file_out);
file_out.close();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Read

Syntax :

  void Read(string);
  void Read(ifstream&);

This method sets the matrix from a file/stream in binary format. The file contains the number of rows, columns, non-zero entries, then the array of values, indices of first elements of each row, column numbers. The format will be different for each storage, therefore it is not very portable. It can be useful if you have written a matrix with Seldon on a disk, and you can read it (if the same storage, e.g. RowSparse is used). For "portable" formats, use rather WriteText.

Example :

Matrix<double, General RowSparse> A; 
// you can read directly on a file
A.Read("matrix.dat");

// or read from a stream
ifstream file_in("matrix.dat");
int my_info;
file_in.read(reinterpret_cast<char*>(&my_info), sizeof(int));
A.Read(file_in);
file_in.close();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

WriteText

Syntax :

  void WriteText(string) const;
  void WriteText(ofstream&) const;
  void WriteText(string, bool without_brackets) const;
  void WriteText(ofstream&, bool without_brackets) const;

This method writes the matrix on a file/stream in text format. The file will contain on each line a non-zero entry, i.e. :

row_number col_number value

The row numbers and columns numbers used 1-index convention, i.e. the first row has its row number equal to 1. An exemple of output file is

1 1 0.123
1 3 0.254
1 4 -0.928
2 1 -0.2
2 5 -0.3

If you are using Matlab, you can directly load the matrix with the command

A = spconvert(load('matrix.dat'));

With Python, it is similar :

from scipy.sparse import *

A = loadtxt('matrix.dat')
B = coo_matrix((A[:,2],(A[:,0]-1,A[:,1]-1)))

For complex matrices, the file will look like

1 3 (0.5432143,-2.34433)
2 4 (2.90843,0.0)
3 2 (-1.232409,-0.090982)

If you prefer to not have those brackets, but real part and imaginary part in separated columns, you have to put true in the optional argument. In that case, the file will be :

1 3 0.5432143 -2.34433
2 4 2.90843 0.0
3 2 -1.232409 -0.090982

The Matlab code would be in that last case :

M = load('matrix.dat');
A = spconvert(M(:,1:3)) + 1i*spconvert(M(:,[1,2,4]));

With Python, it is similar :

from scipy.sparse import *

A = loadtxt('matrix.dat')
B = coo_matrix((A[:,2],(A[:,0]-1,A[:,1]-1))) + 1j*coo_matrix((A[:,3],(A[:,0]-1,A[:,1]-1)))

Example :

Matrix<double, General, ArrayRowSparse> A(4,4);
A(1,3) = -1.0;
A(2,2) = 2.5;
// you can write directly in a file
A.WriteText("matrix.dat");

// or open a stream with other datas
ofstream file_out("matrix.dat");
int my_info = 3;
file_out << my_info << '\n';
A.WriteText(file_out);
file_out.close();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

ReadText

Syntax :

  void ReadText(string);
  void ReadText(ifstream&);

This method sets the matrix from a file/stream in text format. The format is detailed in method WriteText.

Example :

Matrix<double, Symmetric, ArrayRowSymSparse> V; 
// you can read directly on a file
V.ReadText("matrix.dat");

// or read from a stream
ifstream file_in("matrix.dat");
int my_info;
file_in >> my_info;
V.ReadText(file_in);
file_in.close();

Location :

Class Matrix_ArraySparse
Matrix_ArraySparse.hxx Matrix_ArraySparse.cxx

Basic declaration of easily modifiable sparse matrices:

Classes :

Example :

Related topics:

Methods for easily modifiable sparse matrices :

Basic declaration of Harwell-Boeing sparse matrices:

Classes :

Example :

Methods for Harwell-Boeing sparse matrices :

Functions :

Matrix constructors for ArrayRowSparse, ArrayRowSymSparse

Syntax :

Example :

Related topics :

Location :

Matrix constructors for RowSparse, RowSymSparse

Syntax :

Example :

Related topics :

Location :

Matrix operators for ArrayRowSparse, ArrayRowSymSparse

Syntax :

Example :

Related topics :

Location :

Matrix operators for RowSparse, RowSymSparse

Syntax :

Example :

Related topics :

Location :

GetM

Syntax :

Example :

Location :

GetN

Syntax :

Example :

Location :

GetDataSize, GetNonZeros

Syntax :

Example :

Location :

GetMemorySize

Syntax :

Example :

Location :

GetData for ArrayRowSparse, ArrayRowSymSparse

Syntax :

Example :

Location :

GetIndex for ArrayRowSparse, ArrayRowSymSparse

Syntax :

Example :

Related topics :

Location :

SetData for ArrayRowSparse, ArrayRowSymSparse

Syntax :

Example :

Related topics :

Location :

Nullify for ArrayRowSparse, ArrayRowSymSparse

Syntax :

Example :

Related topics :

Location :

Clear

Syntax :

Example :

Location :

Reallocate

Syntax :

Example :

Related topics :

Location :

Resize

Syntax :

Example :

Related topics :

Location :

GetData for RowSparse, RowSymSparse