Class MatrixNorms

java.lang.Object
org.flag4j.linalg.MatrixNorms
public final class MatrixNorms extends Object

A utility class providing a range of matrix norm computations for both real and complex matrices.

Overview

This class includes static methods to compute:

  • Schatten norms (p-norms of the singular values), including:
  • Induced norms (operator norms) for specific values of p:
  • Lp,q norms for both dense and sparse (COO/CSR) matrices.
  • Common norms like the Frobenius norm, maximum absolute value (max norm), and infinite norm (maximum row sum) for real and complex matrices.
  • Entry-wise p-norms, computed by flattening the matrix and computing the vector p-norm.

Example Usage:


 Matrix A = ...; // some real matrix
 double fro = MatrixNorms.norm(A); // Frobenius norm
 double nuc = MatrixNorms.shattenNorm(A, 1.0); // nuclear norm
 double spec = MatrixNorms.inducedNorm(A, Double.POSITIVE_INFINITY); // spectral norm

For complex matrices, use the corresponding overloads that accept a CMatrix or other complex matrix type.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    entryWiseNorm(CMatrix src, double p)
    Computes the entry-wise p-norm of a complex dense matrix.
    static double
    entryWiseNorm(Matrix src, double p)
    Computes the entry-wise p-norm of a real dense matrix.
    static double
    inducedNorm(CMatrix src, double p)
    Computes the matrix operator norm of a complex dense matrix "induced" by the vector p-norm.
    static double
    inducedNorm(Matrix src, double p)
    Computes the matrix operator norm of a real dense matrix "induced" by the vector p-norm.
    static double
    infNorm(AbstractDenseRingMatrix<?,?,?> src)
    Computes the infinite norm of this matrix.
    static double
    infNorm(Matrix src)
    Computes the infinite norm of this matrix.
    static double
    maxNorm(AbstractDenseRingMatrix<?,?,?> src)
    Computes the maximum norm of this matrix.
    static double
    maxNorm(Matrix src)
    Computes the maximum norm of this matrix.
    static double
    maxNorm(CooCMatrix src)
    Computes the max norm of a matrix.
    static double
    maxNorm(CooMatrix src)
    Computes the max norm of a matrix.
    static double
    maxNorm(CsrCMatrix src)
    Computes the max norm of a matrix.
    static double
    maxNorm(CsrMatrix src)
    Computes the max norm of a matrix.
    static double
    norm(AbstractDenseRingMatrix<?,?,?> src)
    Computes the Frobenius (or \( L_{2, 2} \)) norm of a dense Ring matrix.
    static double
    norm(AbstractDenseRingMatrix<?,?,?> src, double p, double q)
    Computes the \( L_{p,q} \) norm of a dense Ring matrix.
    static double
    norm(Matrix src)
    Computes the Frobenius (or \( L_{2, 2} \)) norm of a real dense matrix.
    static double
    norm(Matrix src, double p, double q)
    Computes the \( L_{p,q} \) norm of a real dense matrix.
    static double
    norm(CooCMatrix src)
    Computes the Frobenius (\( L_{2, 2} \)) norm of this complex COO matrix.
    static double
    norm(CooCMatrix src, double p, double q)
    Computes the \( L_{p,q} \) norm of a complex COO matrix.
    static double
    norm(CooMatrix src)
    Computes the Frobenius (\( L_{2, 2} \)) norm of this complex COO matrix.
    static double
    norm(CooMatrix src, double p, double q)
    Computes the \( L_{p,q} \) norm of a real COO matrix.
    static double
    norm(CsrCMatrix src)
    Computes the Frobenius of this matrix.
    static double
    norm(CsrCMatrix src, double p, double q)
    Computes the \( L_{p,q} \) norm of a complex CSR matrix.
    static double
    norm(CsrMatrix src)
    Computes the Frobenius (\( L_{2, 2} \)) of this matrix.
    static double
    norm(CsrMatrix src, double p, double q)
    Computes the \( L_{p,q} \) norm of a real CSR matrix.
    static double
    schattenNorm(CMatrix src, double p)
    Computes the Schatten p-norm of a complex dense matrix.
    static double
    schattenNorm(Matrix src, double p)
    Computes the Schatten p-norm of a real dense matrix.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • schattenNorm

      public static double schattenNorm(Matrix src, double p)

      Computes the Schatten p-norm of a real dense matrix. This is equivalent to the p-norm of the vector of singular values of the matrix.

      This method accepts values of p which are negative. When p < 0 the result is not a true norm but may still have numerical uses.

      Parameters:
      src - The matrix to compute the norm of.
      p - The p value in the Schatten p-norm. Some common cases include:
      • p=1: The nuclear (or trace) norm. Equivalent to the sum of singular values.
      • p=2: Frobenius (or \( L_{2, 2} \)) norm. Equivalent to the square root of the sum of the absolute squares of all entries in the matrix.
      • p=Double.POSITIVE_INFINITY: The spectral norm. Equivalent to the maximum singular value.
      • p=Double.NEGATIVE_INFINITY: The minimum singular value.
      Returns:
      The Schatten p-norm of src.

    • schattenNorm

      public static double schattenNorm(CMatrix src, double p)

      Computes the Schatten p-norm of a complex dense matrix. This is equivalent to the p-norm of the vector of singular values of the matrix.

      Parameters:
      src - The matrix to compute the norm of.
      p - The p value in the Schatten p-norm. Must be greater than or equal to 1. Some common cases include:
      • p=1: The nuclear (or trace) norm. Equivalent to the sum of singular values.
      • p=2: Frobenius (or \( L_{2, 2} \)) norm. Equivalent to the square root of the sum of the absolute squares of all entries in the matrix.
      • p=Double.POSITIVE_INFINITY: The spectral norm. Equivalent to the largest singular value.
      Returns:
      The Schatten p-norm of src.
      Throws:
      IllegalArgumentException - If p < 1.

    • inducedNorm

      public static double inducedNorm(Matrix src, double p)

      Computes the matrix operator norm of a real dense matrix "induced" by the vector p-norm. Specifically, this method computes the operator norm of the matrix as: \[ ||A||_p = \sup_{x \ne 0} \cfrac{||Ax||_p}{||x||_p} \]

      This method supports a limited set of p values which yield simple formulas. When p < 1, the result this method returns is not a true mathematical norm. However, these values may still be useful for numerical purposes.

      • p=1: The maximum absolute column sum.
      • p=-1: The minimum absolute column sum.
      • p=2: The spectral norm. Equivalent to the largest singular value of the matrix.
      • p=-2: The smallest singular value of the matrix.
      • p=Double.POSITIVE_INFINITY: The maximum absolute row sum.
      • p=Double.NEGATIVE_INFINITY: The minimum absolute row sum.
      Parameters:
      src - Matrix to compute the norm of.
      p - The p value in the "induced" p-norm. Must be one of the following: 1, -1, 2, -2, Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY.
      Returns:
      Norm of the matrix.
      Throws:
      IllegalArgumentException - If p is not one of the following: 1, -1, 2, -2, Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY.

    • inducedNorm

      public static double inducedNorm(CMatrix src, double p)

      Computes the matrix operator norm of a complex dense matrix "induced" by the vector p-norm. Specifically, this method computes the operator norm of the matrix as: \[ ||A||_p = \sup_{x \ne 0} \cfrac{||Ax||_p}{||x||_p} \]

      This method supports a limited set of p values which yield simple formulas. When p < 1, the result this method returns is not a true mathematical norm. However, these values may still be useful for numerical purposes.

      • p=1: The maximum absolute column sum.
      • p=-1: The minimum absolute column sum.
      • p=2: The spectral norm. Equivalent to the largest singular value of the matrix.
      • p=-2: The smallest singular value of the matrix.
      • p=Double.POSITIVE_INFINITY: The maximum absolute row sum.
      • p=Double.NEGATIVE_INFINITY: The minimum absolute row sum.
      Parameters:
      src - Matrix to compute the norm of.
      p - The p value in the "induced" p-norm. Must be one of the following: 1, -1, 2, -2, Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY.
      Returns:
      Norm of the matrix.
      Throws:
      IllegalArgumentException - If p is not one of the following: 1, -1, 2, -2, Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY.

    • norm

      public static double norm(Matrix src)

      Computes the Frobenius (or \( L_{2, 2} \)) norm of a real dense matrix.

      The Frobenius norm is defined as the square root of the sum of absolute squares of all entries in the matrix.

      This method is equivalent to norm(src, 2, 2). However, this method should generally be preferred over norm(Matrix, double, double) as it may be slightly more efficient.

      Parameters:
      src - Matrix to compute theFrobenius norm of.
      Returns:
      the Frobenius of this tensor.
      See Also:

    • norm

      public static double norm(AbstractDenseRingMatrix<?,?,?> src)

      Computes the Frobenius (or \( L_{2, 2} \)) norm of a dense Ring matrix.

      The Frobenius norm is defined as the square root of the sum of absolute squares of all entries in the matrix.

      This method is equivalent to norm(src, 2, 2). However, this method should generally be preferred over norm(AbstractDenseRingMatrix, double, double) as it may be slightly more efficient.

      Parameters:
      src - Matrix to compute theFrobenius norm of.
      Returns:
      the Frobenius of this tensor.
      See Also:

    • maxNorm

      public static double maxNorm(Matrix src)
      Computes the maximum norm of this matrix. That is, the maximum value in the matrix.
      Parameters:
      src - Matrix to compute norm of.
      Returns:
      The maximum norm of this matrix.
      See Also:

    • maxNorm

      public static double maxNorm(AbstractDenseRingMatrix<?,?,?> src)
      Computes the maximum norm of this matrix. That is, the maximum value in the matrix.
      Parameters:
      src - Matrix to compute norm of.
      Returns:
      The maximum norm of this matrix.
      See Also:

    • infNorm

      public static double infNorm(Matrix src)
      Computes the infinite norm of this matrix. That is the maximum row sum in the matrix.
      Parameters:
      src - Matrix to compute norm of.
      Returns:
      The infinite norm of this matrix.
      See Also:

    • infNorm

      public static double infNorm(AbstractDenseRingMatrix<?,?,?> src)
      Computes the infinite norm of this matrix. That is the maximum row sum in the matrix.
      Parameters:
      src - Matrix to compute norm of.
      Returns:
      The infinite norm of this matrix.
      See Also:

    • norm

      public static double norm(Matrix src, double p, double q)

      Computes the \( L_{p,q} \) norm of a real dense matrix.

      Some common special cases are:

      • p=2, q=1: The sum of Euclidean norms of the column vectors of the matrix.
      • p=2, q=2: The Frobenius norm. Equivalent to the Euclidean norm of the vector of singular values of the matrix.

      The \( L_{p,q} \) norm is computed as if by: 

      
      double norm = 0;
      for(int j=0; j<src.numCols; j++) {
          double sum = 0;
          for(int i=0; i<src.numRows; i++)
              sum += Math.pow(Math.abs(src.get(i, j)), p);

          norm += Math.pow(sum, q / p);
      }

      return Math.pow(norm, 1.0 / q);
      Parameters:
      p - p value in the \( L_{p,q} \) norm.
      q - q value in the \( L_{p,q} \) norm.
      Returns:
      The \( L_{p,q} \) norm of src.

    • norm

      public static double norm(AbstractDenseRingMatrix<?,?,?> src, double p, double q)

      Computes the \( L_{p,q} \) norm of a dense Ring matrix.

      Some common special cases are:

      • p=2, q=1: The sum of Euclidean norms of the column vectors of the matrix.
      • p=2, q=2: The Frobenius norm. Equivalent to the Euclidean norm of the vector of singular values of the matrix.

      The \( L_{p,q} \) norm is computed as if by: 

      
      double norm = 0;
      for(int j=0; j<src.numCols; j++) {
          double sum = 0;
          for(int i=0; i<src.numRows; i++)
              sum += Math.pow(Math.abs(src.get(i, j)), p);

          norm += Math.pow(sum, q / p);
      }

      return Math.pow(norm, 1.0 / q);
      Parameters:
      p - p value in the \( L_{p,q} \) norm.
      q - q value in the \( L_{p,q} \) norm.
      Returns:
      The \( L_{p,q} \) norm of src.

    • entryWiseNorm

      public static double entryWiseNorm(Matrix src, double p)

      Computes the entry-wise p-norm of a real dense matrix.

      The entry-wise p-norm of a matrix is equivalent to the vector ℓp norm computed on the flattened matrix as if by src.toVector().norm(p);.

      Parameters:
      src - The matrix to compute the entry-wise norm of.
      p - The p value in the ℓp vector norm.
      Returns:
      The entry-wise norm of src.

    • entryWiseNorm

      public static double entryWiseNorm(CMatrix src, double p)

      Computes the entry-wise p-norm of a complex dense matrix.

      The entry-wise p-norm of a matrix is equivalent to the vector ℓp norm computed on the flattened matrix as if by src.toVector().norm(p);.

      Parameters:
      src - The matrix to compute the entry-wise norm of.
      p - The p value in the ℓp vector norm.
      Returns:
      The entry-wise norm of src.

    • norm

      public static double norm(CooMatrix src, double p, double q)

      Computes the \( L_{p,q} \) norm of a real COO matrix.

      Some common special cases are:

      • p=2, q=1: The sum of Euclidean norms of the column vectors of the matrix.
      • p=2, q=2: The Frobenius norm. Equivalent to the Euclidean norm of the vector of singular values of the matrix.
      Parameters:
      p - p value in the \( L_{p,q} \) norm.
      q - q value in the \( L_{p,q} \) norm.
      Returns:
      The \( L_{p,q} \) norm of src.

    • norm

      public static double norm(CooCMatrix src, double p, double q)

      Computes the \( L_{p,q} \) norm of a complex COO matrix.

      Some common special cases are:

      • p=2, q=1: The sum of Euclidean norms of the column vectors of the matrix.
      • p=2, q=2: The Frobenius norm. Equivalent to the Euclidean norm of the vector of singular values of the matrix.
      Parameters:
      p - p value in the \( L_{p,q} \) norm.
      q - q value in the \( L_{p,q} \) norm.
      Returns:
      The \( L_{p,q} \) norm of src.

    • norm

      public static double norm(CooMatrix src)
      Computes the Frobenius (\( L_{2, 2} \)) norm of this complex COO matrix. This is equivalent to norm(src, 2, 2).
      Parameters:
      src - Matrix to compute the \( L_{2, 2} \) norm of.
      Returns:
      the Frobenius (\( L_{2, 2} \)) norm of this tensor.

    • norm

      public static double norm(CooCMatrix src)
      Computes the Frobenius (\( L_{2, 2} \)) norm of this complex COO matrix. This is equivalent to norm(src, 2, 2).
      Parameters:
      src - Matrix to compute the \( L_{2, 2} \) norm of.
      Returns:
      the Frobenius (\( L_{2, 2} \)) norm of this tensor.

    • maxNorm

      public static double maxNorm(CooCMatrix src)
      Computes the max norm of a matrix.
      Parameters:
      src - Matrix to compute norm of.
      Returns:
      The max norm of this matrix.

    • maxNorm

      public static double maxNorm(CooMatrix src)
      Computes the max norm of a matrix.
      Parameters:
      src - Matrix to compute norm of.
      Returns:
      The max norm of this matrix.

    • norm

      public static double norm(CsrMatrix src, double p, double q)

      Computes the \( L_{p,q} \) norm of a real CSR matrix.

      Some common special cases are:

      • p=2, q=1: The sum of Euclidean norms of the column vectors of the matrix.
      • p=2, q=2: The Frobenius norm. Equivalent to the Euclidean norm of the vector of singular values of the matrix.
      Parameters:
      p - p value in the \( L_{p,q} \) norm.
      q - q value in the \( L_{p,q} \) norm.
      Returns:
      The \( L_{p,q} \) norm of src.

    • norm

      public static double norm(CsrCMatrix src, double p, double q)

      Computes the \( L_{p,q} \) norm of a complex CSR matrix.

      Some common special cases are:

      • p=2, q=1: The sum of Euclidean norms of the column vectors of the matrix.
      • p=2, q=2: The Frobenius norm. Equivalent to the Euclidean norm of the vector of singular values of the matrix.
      Parameters:
      p - p value in the \( L_{p,q} \) norm.
      q - q value in the \( L_{p,q} \) norm.
      Returns:
      The \( L_{p,q} \) norm of src.

    • maxNorm

      public static double maxNorm(CsrMatrix src)
      Computes the max norm of a matrix.
      Parameters:
      src - Matrix to compute norm of.
      Returns:
      The max norm of this matrix.

    • maxNorm

      public static double maxNorm(CsrCMatrix src)
      Computes the max norm of a matrix.
      Parameters:
      src - Matrix to compute norm of.
      Returns:
      The max norm of this matrix.

    • norm

      public static double norm(CsrMatrix src)
      Computes the Frobenius (\( L_{2, 2} \)) of this matrix. This is equivalent to norm (src, 2, 2).
      Parameters:
      src - Matrix to compute the norm of.
      Returns:
      the Frobenius of this matrix.

    • norm

      public static double norm(CsrCMatrix src)
      Computes the Frobenius of this matrix. This is equivalent to norm(src, 2, 2).
      Parameters:
      src - Matrix to compute the norm of.
      Returns:
      the Frobenius of this matrix.