Package org.apache.lucene.util
Class VectorUtil
- java.lang.Object
-
- org.apache.lucene.util.VectorUtil
-
public final class VectorUtil extends Object
Utilities for computations with numeric arrays, especially algebraic operations like vector dot products. This class uses SIMD vectorization if the corresponding Java module is available and enabled. To enable vectorized code, pass--add-modules jdk.incubator.vector
to Java's command line.It will use CPU's FMA instructions if it is known to perform faster than separate multiply+add. This requires at least Hotspot C2 enabled, which is the default for OpenJDK based JVMs.
To explicitly disable or enable FMA usage, pass the following system properties:
-Dlucene.useScalarFMA=(auto|true|false)
for scalar operations-Dlucene.useVectorFMA=(auto|true|false)
for vectorized operations (with vector incubator module)
The default is
auto
, which enables this for known CPU types and JVM settings. If Hotspot C2 is disabled, FMA and vectorization are not used.Vectorization and FMA is only supported for Hotspot-based JVMs; it won't work on OpenJ9-based JVMs unless they provide
HotSpotDiagnosticMXBean
. Please also make sure that you have thejdk.management
module enabled in modularized applications.
-
-
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 firststatic float[]
checkFinite(float[] v)
Checks if a float vector only has finite components.static float
cosine(byte[] a, byte[] b)
Returns the cosine similarity between the two vectors.static float
cosine(float[] a, float[] b)
Returns the cosine similarity between the two vectors.static int
dotProduct(byte[] a, byte[] b)
Dot product computed over signed bytes.static float
dotProduct(float[] a, float[] b)
Returns the vector dot product of the two vectors.static float
dotProductScore(byte[] a, byte[] 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
scaleMaxInnerProductScore(float vectorDotProductSimilarity)
static int
squareDistance(byte[] a, byte[] b)
Returns the sum of squared differences of the two vectors.static float
squareDistance(float[] a, float[] b)
Returns the sum of squared differences of the two vectors.
-
-
-
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[] a, float[] b)
Returns the cosine similarity between the two vectors.- Throws:
IllegalArgumentException
- if the vectors' dimensions differ.
-
cosine
public static float cosine(byte[] a, byte[] b)
Returns the cosine similarity between the two vectors.
-
squareDistance
public static float squareDistance(float[] a, float[] b)
Returns the sum of squared differences of the two vectors.- Throws:
IllegalArgumentException
- if the vectors' dimensions differ.
-
squareDistance
public static int squareDistance(byte[] a, byte[] 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 normalizethrowOnZero
- whether to throw an exception whenv
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 destinationv
- the vector to add to the destination
-
dotProduct
public static int dotProduct(byte[] a, byte[] b)
Dot product computed over signed bytes.- Parameters:
a
- bytes containing a vectorb
- bytes containing another vector, of the same dimension- Returns:
- the value of the dot product of the two vectors
-
dotProductScore
public static float dotProductScore(byte[] a, byte[] b)
Dot product score computed over signed bytes, scaled to be in [0, 1].- Parameters:
a
- bytes containing a vectorb
- bytes containing another vector, of the same dimension- Returns:
- the value of the similarity function applied to the two vectors
-
scaleMaxInnerProductScore
public static float scaleMaxInnerProductScore(float vectorDotProductSimilarity)
- Parameters:
vectorDotProductSimilarity
- the raw similarity between two vectors- Returns:
- A scaled score preventing negative scores for maximum-inner-product
-
checkFinite
public static float[] checkFinite(float[] v)
Checks if a float vector only has finite components.- Parameters:
v
- bytes containing a vector- Returns:
- the vector for call-chaining
- Throws:
IllegalArgumentException
- if any component of vector is not finite
-
-