Class VectorNorms

java.lang.Object
org.flag4j.linalg.VectorNorms
public final class VectorNorms extends Object
A utility class for computing vector norms, including various types of ℓp norms, with support for both dense and sparse vectors. This class provides methods to compute norms for vectors with real entries as well as vectors with entries that belong to a Ring.

The methods in this class utilize scaling internally when computing the ℓp norm to protect against overflow and underflow for very large or very small values of p (in absolute value).

Note: When p < 1, the results of the ℓp norm methods are not technically true mathematical norms but may still be useful for numerical tasks. However, p = 0 will result in Double.NaN.

This class is designed to be stateless and is not intended to be instantiated.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    norm(double... src)
    Computes the Euclidean (ℓ2) norm of a real dense or sparse vector.
    static double
    norm(double[] src, double p)
    Computes the ℓp norm (or p-norm) of a real dense or sparse vector.
    static double
    norm(double[] src, int start, int n, int stride)
    Computes the ℓ2 (Euclidean) norm of a sub-vector within src, starting at index start and considering n elements spaced by stride.
    static <T extends Ring<T>>
    double
    norm(T... src)
    Computes the Euclidean (ℓ2) norm of a dense or sparse vector whose entries are members of a Ring.
    static <T extends Ring<T>>
    double
    norm(T[] src, double p)
    Computes the ℓp norm (or p-norm) of a dense or sparse vector whose entries are members of a Ring.
    static <T extends Ring<T>>
    double
    norm(T[] src, int start, int n, int stride)
    Computes the ℓ2 (Euclidean) norm of a sub-vector within src, starting at index start and considering n elements spaced by stride.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • norm

      public static double norm(double... src)

      Computes the Euclidean (ℓ2) norm of a real dense or sparse vector.

      Zeros do not contribute to this norm so this function may be called on the entries of a dense vector or the non-zero entries of a sparse vector.

      Parameters:
      src - Entries of the vector (or non-zero data if vector is sparse) to compute norm of.
      Returns:
      Euclidean (ℓ2) norm

    • norm

      public static <T extends Ring<T>> double norm(T... src)

      Computes the Euclidean (ℓ2) norm of a dense or sparse vector whose entries are members of a Ring.

      Zeros do not contribute to this norm so this function may be called on the entries of a dense vector or the non-zero entries of a sparse vector.

      Parameters:
      src - Entries of the vector (or non-zero data if vector is sparse) to compute norm of.
      Returns:
      Euclidean (ℓ2) norm

    • norm

      public static double norm(double[] src, double p)

      Computes the ℓp norm (or p-norm) of a real dense or sparse vector.

      Some common norms:

      • p=1: The taxicab, city block, or Manhattan norm.
      • p=2: The Euclidean or ℓ2 norm.

      Zeros do not contribute to this norm so this function may be called on the entries of a dense vector or the non-zero entries of a sparse vector.

      Parameters:
      src - Entries of the vector (or non-zero data if vector is sparse).
      p - The p value in the p-norm. When p < 1, the result of this method is not technically a true mathematical norm. However, it may be useful for various numerical tasks.
      • If p is finite, then the norm is computed as if by: 
        
     int norm = 0;

     for(double v : src)
         norm += Math.pow(Math.abs(v), p);

     return Math.pow(norm, 1.0/p);
      • If p is Double.POSITIVE_INFINITY, then this method computes the maximum/infinite norm.
      • If p is Double.NEGATIVE_INFINITY, then this method computes the minimum norm.

      Warning, if p is very large in absolute value, overflow errors may occur.

      Returns:
      The p-norm of the vector.

    • norm

      public static <T extends Ring<T>> double norm(T[] src, double p)

      Computes the ℓp norm (or p-norm) of a dense or sparse vector whose entries are members of a Ring.

      Some common norms:

      • p=1: The taxicab, city block, or Manhattan norm.
      • p=2: The Euclidean or ℓ2 norm.

      Zeros do not contribute to this norm so this function may be called on the entries of a dense vector or the non-zero entries of a sparse vector.

      Parameters:
      src - Entries of the vector (or non-zero data if vector is sparse).
      p - The p value in the p-norm. When p < 1, the result of this method is not technically a true mathematical norm. However, it may be useful for various numerical tasks.
      • If p is finite, then the norm is computed as if by: 
        
     int norm = 0;

     for(double v : src)
         norm += Math.pow(Math.abs(v), p);

     return Math.pow(norm, 1.0/p);
      • If p is Double.POSITIVE_INFINITY, then this method computes the maximum/infinite norm.
      • If p is Double.NEGATIVE_INFINITY, then this method computes the minimum norm.

      Warning, if p is very large in absolute value, overflow errors may occur.

      Returns:
      The p-norm of the vector.

    • norm

      public static double norm(double[] src, int start, int n, int stride)

      Computes the ℓ2 (Euclidean) norm of a sub-vector within src, starting at index start and considering n elements spaced by stride.

      More formally, this method examines and computes the norm of the elements at indices: start, start + stride, start + 2*stride, ..., start + (n-1)*stride.

      This method may be used to compute the norm of a row or column in a matrix a as follows:

      • Norm of row i: 
        norm(a.data, i*a.numCols, a.numCols, 1);
      • Norm of column j: 
        norm(a.data, j, a.numRows, a.numRows);
      Parameters:
      src - The array to containing sub-vector elements to compute norm of.
      start - The starting index in src to search. Must be positive but this is not explicitly enforced.
      n - The number of elements to consider within src1. Must be positive but this is not explicitly enforced.
      stride - The gap (in indices) between consecutive elements of the sub-vector within src. Must be positive but this is not explicitly enforced.
      Returns:
      The ℓ2 (Euclidean) norm of the specified sub-vector of src.
      Throws:
      IndexOutOfBoundsException - If start + (n-1)*stride exceeds src.length - 1.

    • norm

      public static <T extends Ring<T>> double norm(T[] src, int start, int n, int stride)

      Computes the ℓ2 (Euclidean) norm of a sub-vector within src, starting at index start and considering n elements spaced by stride.

      More formally, this method examines and computes the norm of the elements at indices: start, start + stride, start + 2*stride, ..., start + (n-1)*stride.

      This method may be used to compute the norm of a row or column in a matrix a as follows:

      • Norm of row i: 
        norm(a.data, i*a.numCols, a.numCols, 1);
      • Norm of column j: 
        norm(a.data, j, a.numRows, a.numRows);
      Parameters:
      src - The array to containing sub-vector elements to compute norm of.
      start - The starting index in src to search. Must be positive but this is not explicitly enforced.
      n - The number of elements to consider within src1. Must be positive but this is not explicitly enforced.
      stride - The gap (in indices) between consecutive elements of the sub-vector within src. Must be positive but this is not explicitly enforced.
      Returns:
      The ℓ2 (Euclidean) norm of the specified sub-vector of src.
      Throws:
      IndexOutOfBoundsException - If start + (n-1)*stride exceeds src.length - 1.