Package org.apache.lucene.util

Class VectorUtil

  • public final class VectorUtil
extends Object
    Utilities for computations with numeric arrays

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void add​(float[] u, float[] v)
      Adds the second argument to the first
      static float cosine​(float[] v1, float[] v2)
      Returns the cosine similarity between the two vectors.
      static float cosine​(BytesRef a, BytesRef b)
      Returns the cosine similarity between the two vectors.
      static float dotProduct​(float[] a, float[] b)
      Returns the vector dot product of the two vectors.
      static float dotProduct​(BytesRef a, BytesRef b)
      Dot product computed over signed bytes.
      static float dotProductScore​(BytesRef a, BytesRef b)
      Dot product score computed over signed bytes, scaled to be in [0, 1].
      static float[] l2normalize​(float[] v)
      Modifies the argument to be unit length, dividing by its l2-norm.
      static float[] l2normalize​(float[] v, boolean throwOnZero)
      Modifies the argument to be unit length, dividing by its l2-norm.
      static float squareDistance​(float[] v1, float[] v2)
      Returns the sum of squared differences of the two vectors.
      static float squareDistance​(BytesRef a, BytesRef b)
      Returns the sum of squared differences of the two vectors.
      static BytesRef toBytesRef​(float[] vector)
      Convert a floating point vector to an array of bytes using casting; the vector values should be in [-128,127]

    • Method Detail

      • dotProduct

        public static float dotProduct​(float[] a,
                               float[] b)
        Returns the vector dot product of the two vectors.
        Throws:
        IllegalArgumentException - if the vectors' dimensions differ.

      • cosine

        public static float cosine​(float[] v1,
                           float[] v2)
        Returns the cosine similarity between the two vectors.
        Throws:
        IllegalArgumentException - if the vectors' dimensions differ.

      • cosine

        public static float cosine​(BytesRef a,
                           BytesRef b)
        Returns the cosine similarity between the two vectors.

      • squareDistance

        public static float squareDistance​(float[] v1,
                                   float[] v2)
        Returns the sum of squared differences of the two vectors.
        Throws:
        IllegalArgumentException - if the vectors' dimensions differ.

      • squareDistance

        public static float squareDistance​(BytesRef a,
                                   BytesRef b)
        Returns the sum of squared differences of the two vectors.

      • l2normalize

        public static float[] l2normalize​(float[] v)
        Modifies the argument to be unit length, dividing by its l2-norm. IllegalArgumentException is thrown for zero vectors.
        Returns:
        the input array after normalization

      • l2normalize

        public static float[] l2normalize​(float[] v,
                                  boolean throwOnZero)
        Modifies the argument to be unit length, dividing by its l2-norm.
        Parameters:
        v - the vector to normalize
        throwOnZero - whether to throw an exception when v has all zeros
        Returns:
        the input array after normalization
        Throws:
        IllegalArgumentException - when the vector is all zero and throwOnZero is true

      • add

        public static void add​(float[] u,
                       float[] v)
        Adds the second argument to the first
        Parameters:
        u - the destination
        v - the vector to add to the destination

      • dotProduct

        public static float dotProduct​(BytesRef a,
                               BytesRef b)
        Dot product computed over signed bytes.
        Parameters:
        a - bytes containing a vector
        b - bytes containing another vector, of the same dimension
        Returns:
        the value of the dot product of the two vectors

      • dotProductScore

        public static float dotProductScore​(BytesRef a,
                                    BytesRef b)
        Dot product score computed over signed bytes, scaled to be in [0, 1].
        Parameters:
        a - bytes containing a vector
        b - bytes containing another vector, of the same dimension
        Returns:
        the value of the similarity function applied to the two vectors

      • toBytesRef

        public static BytesRef toBytesRef​(float[] vector)
        Convert a floating point vector to an array of bytes using casting; the vector values should be in [-128,127]
        Parameters:
        vector - a vector
        Returns:
        a new BytesRef containing the vector's values cast to byte.