13.2 ELL_Matrix Class

The ELL_Matrix Class is used to describe a matrix in the CÆSAR Code Package. The storage format is ELL, a common storage format originally used by the ELLPACK package. In this storage format, two rectangular arrays are used to store the matrix. The arrays have the same number of rows as the original matrix, but only have as many columns as the maximum number of nonzeros on a row of the original matrix. One of the arrays holds the matrix entries, and the other array holds the column numbers from the original matrix.

As an example, this original matrix:

$$\left[\vphantom{ \begin{array}{cccccc} 1 & 2 & 3 & 0 & 0 & 0 ... ... 0 & 0 & 5 & 0 & 0 & 0 0 & 0 & 4 & 0 & 3 & 0 \end{array} }\right. \begin{array}{cccccc} 1 & 2 & 3 & 0 & 0 & 0 0 & 4 & 5 & 0 & ... ... & 7 & 6 0 & 0 & 5 & 0 & 0 & 0 0 & 0 & 4 & 0 & 3 & 0 \end{array} \left.\vphantom{ \begin{array}{cccccc} 1 & 2 & 3 & 0 & 0 & 0 ... ... 0 & 0 & 5 & 0 & 0 & 0 0 & 0 & 4 & 0 & 3 & 0 \end{array} }\right]$$ (13.1)

which has a maximum number of nonzeros per row of 3, would be stored as

$$\left[\vphantom{ \begin{array}{cccccc} 1 & 2 & 3 4 & 5 & 6 \... ... & 8 & 9 8 & 7 & 6 5 & 0 & 0 4 & 3 & 0 \end{array} }\right. \begin{array}{cccccc} 1 & 2 & 3 4 & 5 & 6 7 & 8 & 9 8 & 7 & 6 5 & 0 & 0 4 & 3 & 0 \end{array} \left.\vphantom{ \begin{array}{cccccc} 1 & 2 & 3 4 & 5 & 6 \... ... & 8 & 9 8 & 7 & 6 5 & 0 & 0 4 & 3 & 0 \end{array} }\right] \left[\vphantom{ \begin{array}{cccccc} 1 & 2 & 3 2 & 3 & 5 ... ... & 3 & 5 2 & 5 & 6 3 & 0 & 0 3 & 5 & 0 \end{array} }\right. \begin{array}{cccccc} 1 & 2 & 3 2 & 3 & 5 1 & 3 & 5 2 & 5 & 6 3 & 0 & 0 3 & 5 & 0 \end{array} \left.\vphantom{ \begin{array}{cccccc} 1 & 2 & 3 2 & 3 & 5 ... ... & 3 & 5 2 & 5 & 6 3 & 0 & 0 3 & 5 & 0 \end{array} }\right]$$ (13.2)

This storage format is most efficient when every row in the original matrix has the same number of nonzeros. It is somewhat easier to work with than the compressed sparse row (CSR) format, but it can use more memory if the matrix has an uneven number of nonzeros per row.

In addition to this, the ELL_Matrix Class is a parallel data structure. The row dimension in the Values and Columns arrays is distributed across the processors.

The ELL_Matrix methods section describes the methods used in the ELL_Matrix Class.

ELL_Matrix public procedures:

	Fundamental procedures
	Initialize		Initializes an ELL_Matrix object.
	Finalize		Finalizes an ELL_Matrix object.
	Valid_State		Returns false iff an ELL_Matrix object is in an invalid state.
	Initialized		Returns true iff an ELL_Matrix object has been initialized.
	Operations
	Add_Values		Increments the values of an ELL_Matrix object.
	Average		Returns the arithmetic mean of the ELL_Matrix object.
	First_Row_PE		Returns the global number of the first row on this PE of the ELL_Matrix object.
	Frobenius_Norm		Returns the Frobenius norm of the ELL_Matrix object.
	Get_Columns		Returns the column locations for an ELL_Matrix object (also has an assignment interface).
	Get_Values		Returns the values for an ELL_Matrix object (also has an assignment interface).
	Infinity_Norm		Returns the infinity norm of the ELL_Matrix object.
	Last_Row_PE		Returns the global number of the last row on this PE of the ELL_Matrix object.
	MatVec		Returns the global matrix-vector product of an ELL_Matrix object and a Mathematic_Vector object.
	Max_Nonzeros		Returns the maximum number of nonzeros of the ELL_Matrix object (the array storage dimension for the columns).
	Maximum		Returns the maximum of the ELL_Matrix object.
	Mean		Returns the mean value of the ELL_Matrix object.
	Minimum		Returns the minimum of the ELL_Matrix object.
	Name		Returns the name of the ELL_Matrix object.
	Norm		Returns the Frobenius norm of the ELL_Matrix object.
	NColumns		Returns the number of columns of the ELL_Matrix object.
	NRows_PE		Returns the number of rows on this PE of the ELL_Matrix object.
	NRows_Total		Returns the total number of rows of the ELL_Matrix object.
	One_Norm		Returns the one norm of the ELL_Matrix object.
	Output		Writes out the ELL_Matrix object.
	Read		Reads in an ELL_Matrix object from a Harwell-Boeing formatted file. Also reads in Mathematic_Vector objects from the file.
	Read_Harwell_Boeing		Reads in an ELL_Matrix object from a Harwell-Boeing formatted file. Also reads in Mathematic_Vector objects from the file.
	Residual		Calculates the residual vector ( r = Ax - b) for a linear system.
	Set_0_Diagonal_to_1		Sets the diagonal of the matrix to unity if all entries on a row are equal to zero.
	Set_Not_Up_to_Date		Puts an ELL Matrix into a ``not up-to-date'' state. Can be used externally to force recalculation of norms, extrema, etc.
	Set_Value		Sets all values to a specified scalar (often zero) for an ELL_Matrix object. Does not modify sparsity pattern or any other internal structure.
	Set_Values		Sets the values for an ELL_Matrix object.
	Sum		Returns the sum of the ELL_Matrix object.
	Total		Returns the sum of the ELL_Matrix object.
	Two_Norm_Estimate		Returns an estimate of the two norm of the ELL_Matrix object.
	Two_Norm_Range		Returns the range of possible values for the two norm of the ELL_Matrix object.

ELL_Matrix public defined types:

	ELL_Matrix type
	Average		Global average of the ELL Matrix.
	Average_is_Updated		Updated? toggle for Average.
	Column_Structure		Column base structure for the ELL Matrix.
	Columns		Array of column numbers for the ELL Matrix.
	Dimensionality		Number of dimensions for the ELL Matrix (always unity).
	Index		Data Index that is used for matvecs.
	Index_is_Updated		Updated? toggle for Index.
	Index_Match_Number		Index Match Number that is used for matvecs.
	Frobenius_Norm		Frobenius norm of the ELL Matrix.
	Frobenius_Norm_is_Updated		Updated? toggle for Frobenius_Norm.
	Infinity_Norm		Infinity norm of the ELL Matrix.
	Infinity_Norm_is_Updated		Updated? toggle for Infinity_Norm.
	Initialized		Initialization status.
	Max_Nonzeros		Maximum number of nonzero columns on a row in the matrix.
	Maximum		Global maximum of the ELL Matrix.
	Maximum_is_Updated		Updated? toggle for Maximum.
	Minimum		Global minimum of the ELL Matrix.
	Minimum_is_Updated		Updated? toggle for Minimum.
	Name		The name for this variable (especially useful in a vector of ELL Matrices).
	One_Norm		One norm of the ELL Matrix.
	One_Norm_is_Updated		Updated? toggle for One_Norm.
	OV		A vector of Overlapped Vectors that is used for matvecs.
	Row_Structure		Row base structure for the ELL Matrix.
	Sum		Global sum of the ELL Matrix.
	Sum_is_Updated		Updated? toggle for Sum.
	Two_Norm_Estimate		An estimate of the two norm of the ELL Matrix, taken to be the midpoint of the range.
	Two_Norm_is_Updated		Updated? toggle for Two_Norm.
	Two_Norm_Range		The possible range of the two norm of the ELL Matrix.
	Values		Values for the ELL Matrix.

The ELL_Matrix Class code listing contains additional documentation. The ELL_Matrix Class also contains a Unit Test Program.