java.lang.Object
org.apache.lucene.util.VectorUtil
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 the jdk.management
module enabled in modularized applications.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final float
private static final VectorUtilSupport
(package private) static final boolean
For xorBitCount we stride over the values as either 64-bits (long) or 32-bits (int) at a time. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic 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 int
findNextGEQ
(int[] buffer, int target, int from, int to) Given an arraybuffer
that is sorted between indexes0
inclusive andto
exclusive, find the first array index whose value is greater than or equal totarget
.static int
int4DotProduct
(byte[] a, byte[] b) static int
int4DotProductPacked
(byte[] unpacked, byte[] packed) Dot product computed over int4 (values between [0,15]) bytes.static boolean
isUnitVector
(float[] v) 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.static int
xorBitCount
(byte[] a, byte[] b) XOR bit count computed over signed bytes.(package private) static int
xorBitCountInt
(byte[] a, byte[] b) XOR bit count striding over 4 bytes at a time.(package private) static int
xorBitCountLong
(byte[] a, byte[] b) XOR bit count striding over 8 bytes at a time.
-
Field Details
-
EPSILON
private static final float EPSILON- See Also:
-
IMPL
-
XOR_BIT_COUNT_STRIDE_AS_INT
static final boolean XOR_BIT_COUNT_STRIDE_AS_INTFor xorBitCount we stride over the values as either 64-bits (long) or 32-bits (int) at a time. On ARM Long::bitCount is not vectorized, and therefore produces less than optimal code, when compared to Integer::bitCount. While Long::bitCount is optimal on x64. See https://bugs.openjdk.org/browse/JDK-8336000
-
-
Constructor Details
-
VectorUtil
private VectorUtil()
-
-
Method Details
-
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
-
isUnitVector
public static boolean isUnitVector(float[] v) -
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
-
int4DotProduct
public static int int4DotProduct(byte[] a, byte[] b) -
int4DotProductPacked
public static int int4DotProductPacked(byte[] unpacked, byte[] packed) Dot product computed over int4 (values between [0,15]) bytes. The second vector is considered "packed" (i.e. every byte representing two values). The following packing is assumed:packed[0] = (raw[0] * 16) | raw[packed.length]; packed[1] = (raw[1] * 16) | raw[packed.length + 1]; ... packed[packed.length - 1] = (raw[packed.length - 1] * 16) | raw[2 * packed.length - 1];
- Parameters:
unpacked
- the unpacked vector, of even lengthpacked
- the packed vector, of length(unpacked.length + 1) / 2
- Returns:
- the value of the dot product of the two vectors
-
xorBitCount
public static int xorBitCount(byte[] a, byte[] b) XOR bit count computed over signed bytes.- Parameters:
a
- bytes containing a vectorb
- bytes containing another vector, of the same dimension- Returns:
- the value of the XOR bit count of the two vectors
-
xorBitCountInt
static int xorBitCountInt(byte[] a, byte[] b) XOR bit count striding over 4 bytes at a time. -
xorBitCountLong
static int xorBitCountLong(byte[] a, byte[] b) XOR bit count striding over 8 bytes at a time. -
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
-
findNextGEQ
public static int findNextGEQ(int[] buffer, int target, int from, int to) Given an arraybuffer
that is sorted between indexes0
inclusive andto
exclusive, find the first array index whose value is greater than or equal totarget
. This index is guaranteed to be at leastfrom
. If there is no such array index,to
is returned.
-