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 \( \ell ^{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 \( \ell ^{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 \( \ell ^{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 (\( \ell ^{2} \)) norm of a real dense or sparse vector.
    static double
    norm(double[] src, double p)
    Computes the \( \ell ^{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 \( \ell ^{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 (\( \ell ^{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 \( \ell ^{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 \( \ell ^{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 (\( \ell ^{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 (\( \ell ^{2} \)) norm

    • norm

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

      Computes the Euclidean (\( \ell ^{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 (\( \ell ^{2} \)) norm

    • norm

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

      Computes the \( \ell ^{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 \( \ell ^{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 \( \ell ^{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 \( \ell ^{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 \( \ell ^{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 \( \ell ^{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 \( \ell ^{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 \( \ell ^{2} \) (Euclidean) norm of the specified sub-vector of src.
      Throws:
      IndexOutOfBoundsException - If start + (n-1)*stride exceeds src.length - 1.