Enum Norm

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Norm>

    public enum Norm
    extends java.lang.Enum<Norm>
    Norm functions.

    The implementations provide increased numerical accuracy. Algorithms primary source is the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static interface  Norm.Array
      Function of array argument.
      private static interface  Norm.Three
      Function of 3 arguments.
      private static interface  Norm.Two
      Function of 2 arguments.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private Norm.Array array
      Function of array argument.
      private static int EXP_DIFF_THRESHOLD_2D
      Threshold for the difference between the exponents of two Euclidean 2D input values where the larger value dominates the calculation.
      private static double LARGE_THRESH
      Threshold for scaling large numbers.
      private static double SAFE_SCALE_UP_THRESH
      Threshold for scaling up a single value by SCALE_UP without risking overflow when the value is squared.
      private static double SCALE_DOWN
      Value used to scale down large numbers.
      private static double SCALE_UP
      Value used to scale up small numbers.
      private static double SMALL_THRESH
      Threshold for scaling small numbers.
      private Norm.Three three
      Function of 3 arguments.
      private Norm.Two two
      Function of 2 arguments.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private static void ensureNonEmpty​(double[] a)  
      private static double euclidean​(double[] v)
      Computes the Euclidean norm.
      private static double euclidean​(double x, double y)
      Computes the Euclidean norm.
      private static double euclidean​(double x, double y, double z)
      Computes the Euclidean norm.
      private static double euclideanNormSpecial​(double[] v, int start)
      Special cases of non-finite input.
      private static double manhattan​(double[] v)
      Computes the Manhattan norm.
      private static double manhattan​(double x, double y)
      Computes the Manhattan norm.
      private static double manhattan​(double x, double y, double z)
      Computes the Manhattan norm.
      private static double maximum​(double[] v)
      Computes the maximum norm.
      private static double maximum​(double x, double y)
      Computes the maximum norm.
      private static double maximum​(double x, double y, double z)
      Computes the maximum norm.
      double of​(double[] v)
      Computes the norm.
      double of​(double x, double y)
      Computes the norm.
      double of​(double x, double y, double z)
      Computes the norm.
      static Norm valueOf​(java.lang.String name)
      Returns the enum constant of this type with the specified name.
      static Norm[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      • Methods inherited from class java.lang.Enum

        clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Enum Constant Detail

      • L1

        public static final Norm L1
        Manhattan norm (sum of the absolute values of the arguments).
      • MANHATTAN

        public static final Norm MANHATTAN
        Alias for L1.
      • EUCLIDEAN

        public static final Norm EUCLIDEAN
        Alias for L2.
      • LINF

        public static final Norm LINF
        Maximum norm (maximum of the absolute values of the arguments).
      • MAXIMUM

        public static final Norm MAXIMUM
        Alias for LINF.
    • Field Detail

      • SMALL_THRESH

        private static final double SMALL_THRESH
        Threshold for scaling small numbers. This value is chosen such that doubles set to this value can be squared without underflow. Values less than this must be scaled up.
        See Also:
        Constant Field Values
      • LARGE_THRESH

        private static final double LARGE_THRESH
        Threshold for scaling large numbers. This value is chosen such that 2^31 doubles set to this value can be squared and added without overflow. Values greater than this must be scaled down.
        See Also:
        Constant Field Values
      • SAFE_SCALE_UP_THRESH

        private static final double SAFE_SCALE_UP_THRESH
        Threshold for scaling up a single value by SCALE_UP without risking overflow when the value is squared.
        See Also:
        Constant Field Values
      • SCALE_DOWN

        private static final double SCALE_DOWN
        Value used to scale down large numbers.
        See Also:
        Constant Field Values
      • SCALE_UP

        private static final double SCALE_UP
        Value used to scale up small numbers.
        See Also:
        Constant Field Values
      • EXP_DIFF_THRESHOLD_2D

        private static final int EXP_DIFF_THRESHOLD_2D
        Threshold for the difference between the exponents of two Euclidean 2D input values where the larger value dominates the calculation.
        See Also:
        Constant Field Values
      • two

        private final Norm.Two two
        Function of 2 arguments.
      • three

        private final Norm.Three three
        Function of 3 arguments.
      • array

        private final Norm.Array array
        Function of array argument.
    • Constructor Detail

      • Norm

        private Norm​(Norm.Two two,
                     Norm.Three three,
                     Norm.Array array)
        Parameters:
        two - Function of 2 arguments.
        three - Function of 3 arguments.
        array - Function of array argument.
      • Norm

        private Norm​(Norm alias)
        Parameters:
        alias - Alternative name.
    • Method Detail

      • values

        public static Norm[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
        for (Norm c : Norm.values())
            System.out.println(c);
        
        Returns:
        an array containing the constants of this enum type, in the order they are declared
      • valueOf

        public static Norm valueOf​(java.lang.String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.NullPointerException - if the argument is null
      • of

        public final double of​(double x,
                               double y)
        Computes the norm.

        Special cases:

        • If either value is Double.NaN, then the result is Double.NaN.
        • If either value is infinite and the other value is not Double.NaN, then the result is Double.POSITIVE_INFINITY.
        Parameters:
        x - Argument.
        y - Argument.
        Returns:
        the norm.
      • of

        public final double of​(double x,
                               double y,
                               double z)
        Computes the norm.

        Special cases:

        • If any value is Double.NaN, then the result is Double.NaN.
        • If any value is infinite and no value is not Double.NaN, then the result is Double.POSITIVE_INFINITY.
        Parameters:
        x - Argument.
        y - Argument.
        z - Argument.
        Returns:
        the norm.
      • of

        public final double of​(double[] v)
        Computes the norm.

        Special cases:

        • If any value is Double.NaN, then the result is Double.NaN.
        • If any value is infinite and no value is not Double.NaN, then the result is Double.POSITIVE_INFINITY.
        Parameters:
        v - Argument.
        Returns:
        the norm.
        Throws:
        java.lang.IllegalArgumentException - if the array is empty.
      • manhattan

        private static double manhattan​(double x,
                                        double y)
        Computes the Manhattan norm.
        Parameters:
        x - first input value
        y - second input value
        Returns:
        \(|x| + |y|\).
        See Also:
        L1, MANHATTAN, of(double,double)
      • manhattan

        private static double manhattan​(double x,
                                        double y,
                                        double z)
        Computes the Manhattan norm.
        Parameters:
        x - first input value
        y - second input value
        z - third input value
        Returns:
        \(|x| + |y| + |z|\)
        See Also:
        L1, MANHATTAN, of(double,double,double)
      • manhattan

        private static double manhattan​(double[] v)
        Computes the Manhattan norm.
        Parameters:
        v - input values
        Returns:
        \(|v_0| + ... + |v_i|\)
        See Also:
        L1, MANHATTAN, of(double[])
      • euclidean

        private static double euclidean​(double x,
                                        double y)
        Computes the Euclidean norm. This implementation handles possible overflow or underflow.

        Comparison with Math.hypot() While not guaranteed to return the same result, this method provides similar error bounds as Math.hypot(double, double) (and may run faster on some JVM).

        Parameters:
        x - first input
        y - second input
        Returns:
        \(\sqrt{x^2 + y^2}\).
        See Also:
        L2, EUCLIDEAN, of(double,double)
      • euclidean

        private static double euclidean​(double x,
                                        double y,
                                        double z)
        Computes the Euclidean norm. This implementation handles possible overflow or underflow.
        Parameters:
        x - first input
        y - second input
        z - third input
        Returns:
        \(\sqrt{x^2 + y^2 + z^2}\)
        See Also:
        L2, EUCLIDEAN, of(double,double,double)
      • euclidean

        private static double euclidean​(double[] v)
        Computes the Euclidean norm. This implementation handles possible overflow or underflow.
        Parameters:
        v - input values
        Returns:
        \(\sqrt{v_0^2 + ... + v_{n-1}^2}\).
        See Also:
        L2, EUCLIDEAN, of(double[])
      • euclideanNormSpecial

        private static double euclideanNormSpecial​(double[] v,
                                                   int start)
        Special cases of non-finite input.
        Parameters:
        v - input vector
        start - index to start examining the input vector from
        Returns:
        Euclidean norm special value
      • maximum

        private static double maximum​(double x,
                                      double y)
        Computes the maximum norm.
        Parameters:
        x - first input
        y - second input
        Returns:
        \(\max{(|x|, |y|)}\).
        See Also:
        LINF, MAXIMUM, of(double,double)
      • maximum

        private static double maximum​(double x,
                                      double y,
                                      double z)
        Computes the maximum norm.
        Parameters:
        x - first input
        y - second input
        z - third input
        Returns:
        \(\max{(|x|, |y|, |z|)}\).
        See Also:
        LINF, MAXIMUM, of(double,double,double)
      • maximum

        private static double maximum​(double[] v)
        Computes the maximum norm.
        Parameters:
        v - input values
        Returns:
        \(\max{(|v_0|, \ldots, |v_{n-1}|)}\)
        See Also:
        LINF, MAXIMUM, of(double[])
      • ensureNonEmpty

        private static void ensureNonEmpty​(double[] a)
        Parameters:
        a - Array.
        Throws:
        java.lang.IllegalArgumentException - for zero-size array.