The matrix-info Tool

This page describes the usage of the matrix-info tool, which provides a fast and simple way to get some basic information about a matrix file.

This tool can provide information about:

• The matrix dimensions.
• The matrix sparsity pattern.
• The matrix content.

Once the matrix-info tool has been built, it can be used in the following way:

matrix-info <matrix-filename> [<matrix-format>] [options...]

where

• <matrix-filename> is the filename of the matrix that is to be analysed.
• <matrix-format> is the optional file format of the matrix file. If this argument is missing, then the file extension of the matrix filename is used as the format.
  The following formats are currently supported by this tool:
  • mtx: text-based MatrixMarket format.
  • coo: binary COO format
  • csr: binary CSR format.
  • ell: binary ELL format.
  • bm: binary banded format.

Furthermore, the following options are available:

• --nztol tol
  Specifies the relative tolerance for non-zero entries, where tol is a small non-negative floating point number. If not specified, \(\sqrt{\varepsilon}\approx \frac{3}{2} 10^{-8}\) is used.

In the following, for the given input matrix \(A\in \mathbb{R}^{m\times n}\), let \(\mathcal{S}(A) \subseteq \{1,\dots,m\}\times\{1,\dots,n\}\) denote the sparsity pattern of A, i.e. the set of all (i,j) pairs which exist in the sparse matrix A.

The tool provides the following information:

• Matrix Filename: self-explanatory
• Non-Zero Tolerance: the tolerance used by this tool for detecting non-zeros. A matrix entry \(a_{ij}\) is interpreted as zero, if \(|a_{ij}| < \mathrm{nztol}\cdot\|A\|_{\max}\).
• Number of Rows: self-explanatory
• Number of Columns: self-explanatory
• Max Row Degree: specifies the maximum number of symbolical non-zero entries per row, i.e.

  \[\max_{1\leq i\leq m}\mathrm{card}\Big(\big\{(i,j)\in\mathcal{S}(A)\big\}\Big)\]

• Max Column Degree: specifies the maximum number of symbolical non-zero entries per column
• Row Degree Distribution: 10 | 0 | 0 | 5 | 0 | 0 | 7 | 8 | 0 | 70 stands for a distribution of degrees per row, where 10% of the rows contain 0-9% of the maximum matrix row degree. 5 % of the rows contain 30-39% of the maximum matrix row degree. 70% of the rows contain 90-100% of the maximum matrix row degree. Thus we have 10% intervals ascending from left to right, which contain the percentage of rows, which have in common this percentage of row entries, relative to the maximum row degree.
• Average Row Degree: the sum of all row degrees divided by the number of rows.
• Max Row Bandwidth: specifies the maximum row bandwith, i.e.

  \[\max_{1\leq i\leq m}\Big\{ \underset{1\leq j\leq n}{\mathrm{argmax}}\big\{(i,j)\in\mathcal{S}(A)\big\} - \underset{1\leq j\leq n}{\mathrm{argmin}}\big\{(i,j)\in\mathcal{S}(A)\big\}\Big\}\]

• Max Column Bandwidth: specifies the maximum column bandwith.
• Symbolical Non-Zeros: specifies the total number of entries in the sparsity pattern of A, i.e.

  \[\mathrm{card}\Big(\mathcal{S}(A)\Big)\]

• Numerical Non-Zeros: specifies the total number of entries of A, which are non-zero, i.e.

  \[\mathrm{card}\Big(\big\{(i,j)\in\mathcal{S}(A)~:~|a_{ij}| \geq \mathrm{nztol}\cdot\|A\|_{\max}~\big\}\Big)\]

• Has Main Diag Structure: specifies whether the main diagonal is included in the matrix sparsity pattern.
• Has Symmetric Structure: specifies whether the matrix sparsity pattern is symmetric, i.e. specifies whether it holds that

  \[(i,j)\in\mathcal{S}(A) \Longleftrightarrow (j,i)\in\mathcal{S}(A)\]

• Has Symmetric Content: specifies whether the matrix is symmetric, i.e. specifies whether it holds that

  \[|a_{ij} - a_{ji}| < \mathrm{nztol}\cdot\|A\|_{\max}\]

  Note that this will always be false if the matrix sparsity pattern is not symmetric, even if the matrix is numerically symmetric.
• Matrix Content: classifies the entries in the sparsity pattern of the matrix. This can be one of the following eight:
  • empty: the sparsity pattern of the matrix is empty
  • zero: all entries in the sparsity pattern are zero
  • non-zero: all entries in the sparsity pattern are non-zero
  • positive: all entries in the sparsity pattern are positive
  • negative: all entries in the sparsity pattern are negative
  • non-positive: all entries in the sparsity pattern are non-positive
  • non-negative: all entries in the sparsity pattern are non-negative
  • mixed: the sparsity pattern contains positive, negative and zero elements
• Diagonal Content: classifies the entries which are on the main diagonal of the matrix. See Matrix Content for possible values.
• Lower Content: classifies the entries which are below the main diagonal of the matrix. See Matrix Content for possible values.
• Upper Content: classifies the entries which are above the main diagonal of the matrix. See Matrix Content for possible values.
• Row-Diag Dominance Factor: specifies the row-diagonal dominance factor, i.e.

  \[ \max_{1\leq i\leq m} \Big\{\frac{1}{|a_{ij}|}\Big(\sum_{j=1}^n |a_{ij}|\Big)-1\Big\}\]

  where
  • a value < 1 indicates that the matrix is strictly diagonal dominant
  • a value = 1 indicates that the matrix is weakly diagonal dominant
  • a value > 1 indicates that the matrix is not diagonal dominant
• Col-Diag Dominance Factor: specifies the column-diagonal dominance factor. See Row-Diag Dominance Factor.
• Frobenius Norm: specifies the Frobenius norm of the matrix, i.e.

  \[\|A\|_F = \Big(\sum_{i=1}^m\sum_{j=1}^n |a_{ij}|^2\Big)^{\frac{1}{2}}\]

• Col-Sum Norm: specifies the column-sum norm of the matrix, i.e.

  \[\|A\|_1 = \max_{1\leq j\leq n} \sum_{i=1}^m |a_{ij}|\]

• Row-Sum Norm: specifies the row-sum norm of the matrix, i.e.

  \[\|A\|_\infty = \max_{1\leq i\leq m} \sum_{j=1}^n |a_{ij}|\]

• Maximum Norm: specifies the maximum norm of the matrix, i.e.

  \[\|A\|_{\max} = \max_{\substack{1\leq i\leq m\\1\leq j\leq n}} |a_{ij}|\]