Apache Lucene open-source search software
HNSW BP reordering (#14097)
Michael Sokolov02a09f6ab124
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txtindex 786c511b1de..2e574668a27 100644--- a/lucene/CHANGES.txt+++ b/lucene/CHANGES.txt@@ -11,7 +11,7 @@ API ChangesNew Features----------------------(No changes)+* GITHUB#14097: Binary partitioning merge policy over float-valued vector field. (Mike Sokolov)Improvements---------------------diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.javaindex 015fad7490c..698ccff49f7 100644--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.java+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.java@@ -488,6 +488,11 @@ public final class Lucene90HnswVectorsReader extends KnnVectorsReader {throw new UnsupportedOperationException();}+ @Override+ public int maxConn() {+ throw new UnsupportedOperationException();+ }+@Overridepublic NodesIterator getNodesOnLevel(int level) {throw new UnsupportedOperationException();diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90OnHeapHnswGraph.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90OnHeapHnswGraph.javaindex 845987c2957..835293946dd 100644--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90OnHeapHnswGraph.java+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90OnHeapHnswGraph.java@@ -198,6 +198,11 @@ public final class Lucene90OnHeapHnswGraph extends HnswGraph {throw new UnsupportedOperationException();}+ @Override+ public int maxConn() {+ return maxConn;+ }+@Overridepublic NodesIterator getNodesOnLevel(int level) {throw new UnsupportedOperationException();diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.javaindex e71fa66719f..80a71196c44 100644--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.java+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.java@@ -548,6 +548,11 @@ public final class Lucene91HnswVectorsReader extends KnnVectorsReader {return entryNode;}+ @Override+ public int maxConn() {+ return (int) bytesForConns / Integer.BYTES - 1;+ }+@Overridepublic NodesIterator getNodesOnLevel(int level) {if (level == 0) {diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91OnHeapHnswGraph.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91OnHeapHnswGraph.javaindex e762e016bbf..3ebbeee8d8a 100644--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91OnHeapHnswGraph.java+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91OnHeapHnswGraph.java@@ -160,6 +160,11 @@ public final class Lucene91OnHeapHnswGraph extends HnswGraph {return entryNode;}+ @Override+ public int maxConn() {+ return maxConn;+ }+@Overridepublic NodesIterator getNodesOnLevel(int level) {if (level == 0) {diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.javaindex 034967efbaa..213b3fff4f2 100644--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.java+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.java@@ -459,6 +459,11 @@ public final class Lucene92HnswVectorsReader extends KnnVectorsReader {return entryNode;}+ @Override+ public int maxConn() {+ return (int) bytesForConns / Integer.BYTES - 1;+ }+@Overridepublic NodesIterator getNodesOnLevel(int level) {if (level == 0) {diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.javaindex 1ad2e302364..e386c2126be 100644--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.java+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.java@@ -448,6 +448,7 @@ public final class Lucene94HnswVectorsReader extends KnnVectorsReader {final int size;final long bytesForConns;final long bytesForConns0;+ final int maxConn;int arcCount;int arcUpTo;@@ -463,6 +464,7 @@ public final class Lucene94HnswVectorsReader extends KnnVectorsReader {this.bytesForConns = Math.multiplyExact(Math.addExact(entry.M, 1L), Integer.BYTES);this.bytesForConns0 =Math.multiplyExact(Math.addExact(Math.multiplyExact(entry.M, 2L), 1), Integer.BYTES);+ maxConn = entry.M;}@Override@@ -501,6 +503,11 @@ public final class Lucene94HnswVectorsReader extends KnnVectorsReader {return numLevels;}+ @Override+ public int maxConn() {+ return maxConn;+ }+@Overridepublic int entryNode() {return entryNode;diff --git a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.java b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.javaindex b5859daf9f2..99fc82bfc54 100644--- a/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.java+++ b/lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.java@@ -537,6 +537,11 @@ public final class Lucene95HnswVectorsReader extends KnnVectorsReader implementsreturn entryNode;}+ @Override+ public int maxConn() {+ return currentNeighborsBuffer.length / 2;+ }+@Overridepublic NodesIterator getNodesOnLevel(int level) {if (level == 0) {diff --git a/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsWriter.java b/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsWriter.javaindex 01698da7989..ec7eb048c8f 100644--- a/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsWriter.java+++ b/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsWriter.java@@ -334,6 +334,11 @@ public final class Lucene94HnswVectorsWriter extends KnnVectorsWriter {return graph.numLevels();}+ @Override+ public int maxConn() {+ return graph.maxConn();+ }+@Overridepublic int entryNode() {throw new UnsupportedOperationException("Not supported on a mock graph");diff --git a/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsWriter.java b/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsWriter.javaindex c855d8f5e07..55fb3e8ea3e 100644--- a/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsWriter.java+++ b/lucene/backward-codecs/src/test/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsWriter.java@@ -366,6 +366,11 @@ public final class Lucene95HnswVectorsWriter extends KnnVectorsWriter {throw new UnsupportedOperationException("Not supported on a mock graph");}+ @Override+ public int maxConn() {+ throw new UnsupportedOperationException("Not supported on a mock graph");+ }+@Overridepublic NodesIterator getNodesOnLevel(int level) {if (level == 0) {diff --git a/lucene/core/src/java/org/apache/lucene/codecs/KnnVectorsReader.java b/lucene/core/src/java/org/apache/lucene/codecs/KnnVectorsReader.javaindex 54d070fa599..1a3a5319efa 100644--- a/lucene/core/src/java/org/apache/lucene/codecs/KnnVectorsReader.java+++ b/lucene/core/src/java/org/apache/lucene/codecs/KnnVectorsReader.java@@ -75,7 +75,7 @@ public abstract class KnnVectorsReader implements Closeable {* TotalHits.Relation.GREATER_THAN_OR_EQUAL_TO}.** <p>The behavior is undefined if the given field doesn't have KNN vectors enabled on its {@link- * FieldInfo}. The return value is never {@code null}.+ * FieldInfo}.** @param field the vector field to search* @param target the vector-valued query@@ -103,7 +103,7 @@ public abstract class KnnVectorsReader implements Closeable {* TotalHits.Relation.GREATER_THAN_OR_EQUAL_TO}.** <p>The behavior is undefined if the given field doesn't have KNN vectors enabled on its {@link- * FieldInfo}. The return value is never {@code null}.+ * FieldInfo}.** @param field the vector field to search* @param target the vector-valued querydiff --git a/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsReader.java b/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsReader.javaindex ed6388b53cb..b29f9da5b41 100644--- a/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsReader.java+++ b/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsReader.java@@ -491,7 +491,8 @@ public final class Lucene99HnswVectorsReader extends KnnVectorsReaderlevel == 0? targetOrd: Arrays.binarySearch(nodesByLevel[level], 0, nodesByLevel[level].length, targetOrd);- assert targetIndex >= 0;+ assert targetIndex >= 0+ : "seek level=" + level + " target=" + targetOrd + " not found: " + targetIndex;// unsafe; no bounds checkingdataIn.seek(graphLevelNodeOffsets.get(targetIndex + graphLevelNodeIndexOffsets[level]));arcCount = dataIn.readVInt();@@ -526,6 +527,11 @@ public final class Lucene99HnswVectorsReader extends KnnVectorsReaderreturn numLevels;}+ @Override+ public int maxConn() {+ return currentNeighborsBuffer.length >> 1;+ }+@Overridepublic int entryNode() throws IOException {return entryNode;diff --git a/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsWriter.java b/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsWriter.javaindex 0f4e8196d52..ce9ee1b79cc 100644--- a/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsWriter.java+++ b/lucene/core/src/java/org/apache/lucene/codecs/lucene99/Lucene99HnswVectorsWriter.java@@ -93,7 +93,6 @@ public final class Lucene99HnswVectorsWriter extends KnnVectorsWriter {this.numMergeWorkers = numMergeWorkers;this.mergeExec = mergeExec;segmentWriteState = state;-String metaFileName =IndexFileNames.segmentFileName(state.segmentInfo.name, state.segmentSuffix, Lucene99HnswVectorsFormat.META_EXTENSION);@@ -293,6 +292,11 @@ public final class Lucene99HnswVectorsWriter extends KnnVectorsWriter {return graph.numLevels();}+ @Override+ public int maxConn() {+ return graph.maxConn();+ }+@Overridepublic int entryNode() {throw new UnsupportedOperationException("Not supported on a mock graph");diff --git a/lucene/core/src/java/org/apache/lucene/codecs/perfield/PerFieldKnnVectorsFormat.java b/lucene/core/src/java/org/apache/lucene/codecs/perfield/PerFieldKnnVectorsFormat.javaindex bc18b231e74..ee9cb5cd5f5 100644--- a/lucene/core/src/java/org/apache/lucene/codecs/perfield/PerFieldKnnVectorsFormat.java+++ b/lucene/core/src/java/org/apache/lucene/codecs/perfield/PerFieldKnnVectorsFormat.java@@ -28,6 +28,7 @@ import org.apache.lucene.codecs.KnnFieldVectorsWriter;import org.apache.lucene.codecs.KnnVectorsFormat;import org.apache.lucene.codecs.KnnVectorsReader;import org.apache.lucene.codecs.KnnVectorsWriter;+import org.apache.lucene.codecs.hnsw.HnswGraphProvider;import org.apache.lucene.index.ByteVectorValues;import org.apache.lucene.index.FieldInfo;import org.apache.lucene.index.FieldInfos;@@ -41,6 +42,7 @@ import org.apache.lucene.internal.hppc.ObjectCursor;import org.apache.lucene.search.KnnCollector;import org.apache.lucene.util.Bits;import org.apache.lucene.util.IOUtils;+import org.apache.lucene.util.hnsw.HnswGraph;/*** Enables per field numeric vector support.@@ -189,7 +191,7 @@ public abstract class PerFieldKnnVectorsFormat extends KnnVectorsFormat {}/** VectorReader that can wrap multiple delegate readers, selected by field. */- public static class FieldsReader extends KnnVectorsReader {+ public static class FieldsReader extends KnnVectorsReader implements HnswGraphProvider {private final IntObjectHashMap<KnnVectorsReader> fields = new IntObjectHashMap<>();private final FieldInfos fieldInfos;@@ -322,6 +324,17 @@ public abstract class PerFieldKnnVectorsFormat extends KnnVectorsFormat {reader.search(field, target, knnCollector, acceptDocs);}+ @Override+ public HnswGraph getGraph(String field) throws IOException {+ final FieldInfo info = fieldInfos.fieldInfo(field);+ KnnVectorsReader knnVectorsReader = fields.get(info.number);+ if (knnVectorsReader instanceof HnswGraphProvider) {+ return ((HnswGraphProvider) knnVectorsReader).getGraph(field);+ } else {+ return null;+ }+ }+@Overridepublic void close() throws IOException {List<KnnVectorsReader> readers = new ArrayList<>(fields.size());diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexSorter.java b/lucene/core/src/java/org/apache/lucene/index/IndexSorter.javaindex 6db379b9b22..9fa2484af39 100644--- a/lucene/core/src/java/org/apache/lucene/index/IndexSorter.java+++ b/lucene/core/src/java/org/apache/lucene/index/IndexSorter.java@@ -32,11 +32,16 @@ import org.apache.lucene.util.packed.PackedInts;/*** Handles how documents should be sorted in an index, both within a segment and between segments.*- * <p>Implementers must provide the following methods: {@link #getDocComparator(LeafReader,int)} -- * an object that determines how documents within a segment are to be sorted {@link- * #getComparableProviders(List)} - an array of objects that return a sortable long value per- * document and segment {@link #getProviderName()} - the SPI-registered name of a {@link- * SortFieldProvider} to serialize the sort+ * <p>Implementers must provide the following methods:+ *+ * <ul>+ * <li>{@link #getDocComparator(LeafReader,int)} - an object that determines how documents within+ * a segment are to be sorted+ * <li>{@link #getComparableProviders(List)} - an array of objects that return a sortable long+ * value per document and segment+ * <li>{@link #getProviderName()} - the SPI-registered name of a {@link SortFieldProvider} to+ * serialize the sort+ * </ul>** <p>The companion {@link SortFieldProvider} should be registered with SPI via {@code* META-INF/services}diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.javaindex b4688d09730..7f44bcf96aa 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/ConcurrentHnswMerger.java@@ -60,11 +60,10 @@ public class ConcurrentHnswMerger extends IncrementalHnswGraphMerger {} else {initializedNodes = new FixedBitSet(maxOrd);int[] oldToNewOrdinalMap = getNewOrdMapping(mergedVectorValues, initializedNodes);- graph =- InitializedHnswGraphBuilder.initGraph(M, initializerGraph, oldToNewOrdinalMap, maxOrd);+ graph = InitializedHnswGraphBuilder.initGraph(initializerGraph, oldToNewOrdinalMap, maxOrd);}}return new HnswConcurrentMergeBuilder(- taskExecutor, numWorker, scorerSupplier, M, beamWidth, graph, initializedNodes);+ taskExecutor, numWorker, scorerSupplier, beamWidth, graph, initializedNodes);}}diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswConcurrentMergeBuilder.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswConcurrentMergeBuilder.javaindex c23f56bcdc6..d2e81addc5d 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswConcurrentMergeBuilder.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswConcurrentMergeBuilder.java@@ -49,7 +49,6 @@ public class HnswConcurrentMergeBuilder implements HnswBuilder {TaskExecutor taskExecutor,int numWorker,RandomVectorScorerSupplier scorerSupplier,- int M,int beamWidth,OnHeapHnswGraph hnsw,BitSet initializedNodes)@@ -62,7 +61,6 @@ public class HnswConcurrentMergeBuilder implements HnswBuilder {workers[i] =new ConcurrentMergeWorker(scorerSupplier.copy(),- M,beamWidth,HnswGraphBuilder.randSeed,hnsw,@@ -149,7 +147,6 @@ public class HnswConcurrentMergeBuilder implements HnswBuilder {private ConcurrentMergeWorker(RandomVectorScorerSupplier scorerSupplier,- int M,int beamWidth,long seed,OnHeapHnswGraph hnsw,@@ -159,7 +156,6 @@ public class HnswConcurrentMergeBuilder implements HnswBuilder {throws IOException {super(scorerSupplier,- M,beamWidth,seed,hnsw,diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraph.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraph.javaindex 0c38c4e2ff7..9326ace61f7 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraph.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraph.java@@ -84,6 +84,9 @@ public abstract class HnswGraph {/** Returns the number of levels of the graph */public abstract int numLevels() throws IOException;+ /** returns M, the maximum number of connections for a node. */+ public abstract int maxConn() throws IOException;+/** Returns graph's entry point on the top level * */public abstract int entryNode() throws IOException;@@ -118,6 +121,11 @@ public abstract class HnswGraph {return 0;}+ @Override+ public int maxConn() {+ return 0;+ }+@Overridepublic int entryNode() {return 0;diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphBuilder.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphBuilder.javaindex 57e7e43d3d7..d3cef0bc6d1 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphBuilder.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphBuilder.java@@ -100,19 +100,14 @@ public class HnswGraphBuilder implements HnswBuilder {protected HnswGraphBuilder(RandomVectorScorerSupplier scorerSupplier, int M, int beamWidth, long seed, int graphSize)throws IOException {- this(scorerSupplier, M, beamWidth, seed, new OnHeapHnswGraph(M, graphSize));+ this(scorerSupplier, beamWidth, seed, new OnHeapHnswGraph(M, graphSize));}protected HnswGraphBuilder(- RandomVectorScorerSupplier scorerSupplier,- int M,- int beamWidth,- long seed,- OnHeapHnswGraph hnsw)+ RandomVectorScorerSupplier scorerSupplier, int beamWidth, long seed, OnHeapHnswGraph hnsw)throws IOException {this(scorerSupplier,- M,beamWidth,seed,hnsw,@@ -125,8 +120,6 @@ public class HnswGraphBuilder implements HnswBuilder {* ordinals, using the given hyperparameter settings, and returns the resulting graph.** @param scorerSupplier a supplier to create vector scorer from ordinals.- * @param M – graph fanout parameter used to calculate the maximum number of connections a node- * can have – M on upper layers, and M * 2 on the lowest level.* @param beamWidth the size of the beam search to use when finding nearest neighbors.* @param seed the seed for a random number generator used during graph construction. Provide this* to ensure repeatable construction.@@ -134,20 +127,19 @@ public class HnswGraphBuilder implements HnswBuilder {*/protected HnswGraphBuilder(RandomVectorScorerSupplier scorerSupplier,- int M,int beamWidth,long seed,OnHeapHnswGraph hnsw,HnswLock hnswLock,HnswGraphSearcher graphSearcher)throws IOException {- if (M <= 0) {+ if (hnsw.maxConn() <= 0) {throw new IllegalArgumentException("M (max connections) must be positive");}if (beamWidth <= 0) {throw new IllegalArgumentException("beamWidth must be positive");}- this.M = M;+ this.M = hnsw.maxConn();this.scorerSupplier =Objects.requireNonNull(scorerSupplier, "scorer supplier must not be null");// normalization factor for level generation; currently not configurablediff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswUtil.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswUtil.javaindex 7028a81808d..d0d398be2a7 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswUtil.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswUtil.java@@ -23,6 +23,7 @@ import java.util.ArrayDeque;import java.util.ArrayList;import java.util.Deque;import java.util.List;+import org.apache.lucene.codecs.KnnVectorsReader;import org.apache.lucene.codecs.hnsw.HnswGraphProvider;import org.apache.lucene.codecs.perfield.PerFieldKnnVectorsFormat;import org.apache.lucene.index.CodecReader;@@ -233,13 +234,16 @@ public class HnswUtil {public static boolean graphIsRooted(IndexReader reader, String vectorField) throws IOException {for (LeafReaderContext ctx : reader.leaves()) {CodecReader codecReader = (CodecReader) FilterLeafReader.unwrap(ctx.reader());- HnswGraph graph =- ((HnswGraphProvider)- ((PerFieldKnnVectorsFormat.FieldsReader) codecReader.getVectorReader())- .getFieldReader(vectorField))- .getGraph(vectorField);- if (isRooted(graph) == false) {- return false;+ KnnVectorsReader vectorsReader =+ ((PerFieldKnnVectorsFormat.FieldsReader) codecReader.getVectorReader())+ .getFieldReader(vectorField);+ if (vectorsReader instanceof HnswGraphProvider) {+ HnswGraph graph = ((HnswGraphProvider) vectorsReader).getGraph(vectorField);+ if (isRooted(graph) == false) {+ return false;+ }+ } else {+ throw new IllegalArgumentException("not a graph: " + vectorsReader);}}return true;diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.javaindex c480d53360c..bcdb0cab04a 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/IncrementalHnswGraphMerger.java@@ -21,7 +21,6 @@ import static org.apache.lucene.search.DocIdSetIterator.NO_MORE_DOCS;import java.io.IOException;import org.apache.lucene.codecs.KnnVectorsReader;import org.apache.lucene.codecs.hnsw.HnswGraphProvider;-import org.apache.lucene.codecs.perfield.PerFieldKnnVectorsFormat;import org.apache.lucene.index.ByteVectorValues;import org.apache.lucene.index.FieldInfo;import org.apache.lucene.index.FloatVectorValues;@@ -63,33 +62,30 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {/*** Adds a reader to the graph merger if it meets the following criteria: 1. Does not contain any- * deleted docs 2. Is a HnswGraphProvider/PerFieldKnnVectorReader 3. Has the most docs of any- * previous reader that met the above criteria+ * deleted docs 2. Is a HnswGraphProvider 3. Has the most docs of any previous reader that met the+ * above criteria*/@Overridepublic IncrementalHnswGraphMerger addReader(KnnVectorsReader reader, MergeState.DocMap docMap, Bits liveDocs) throws IOException {- KnnVectorsReader currKnnVectorsReader = reader;- if (reader instanceof PerFieldKnnVectorsFormat.FieldsReader candidateReader) {- currKnnVectorsReader = candidateReader.getFieldReader(fieldInfo.name);+ if (hasDeletes(liveDocs) || !(reader instanceof HnswGraphProvider)) {+ return this;}-- if (!(currKnnVectorsReader instanceof HnswGraphProvider) || !noDeletes(liveDocs)) {+ HnswGraph graph = ((HnswGraphProvider) reader).getGraph(fieldInfo.name);+ if (graph == null || graph.size() == 0) {return this;}-int candidateVectorCount = 0;switch (fieldInfo.getVectorEncoding()) {case BYTE -> {- ByteVectorValues byteVectorValues =- currKnnVectorsReader.getByteVectorValues(fieldInfo.name);+ ByteVectorValues byteVectorValues = reader.getByteVectorValues(fieldInfo.name);if (byteVectorValues == null) {return this;}candidateVectorCount = byteVectorValues.size();}case FLOAT32 -> {- FloatVectorValues vectorValues = currKnnVectorsReader.getFloatVectorValues(fieldInfo.name);+ FloatVectorValues vectorValues = reader.getFloatVectorValues(fieldInfo.name);if (vectorValues == null) {return this;}@@ -97,7 +93,7 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {}}if (candidateVectorCount > initGraphSize) {- initReader = currKnnVectorsReader;+ initReader = reader;initDocMap = docMap;initGraphSize = candidateVectorCount;}@@ -130,7 +126,6 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {int[] oldToNewOrdinalMap = getNewOrdMapping(mergedVectorValues, initializedNodes);return InitializedHnswGraphBuilder.fromGraph(scorerSupplier,- M,beamWidth,HnswGraphBuilder.randSeed,initializerGraph,@@ -194,16 +189,16 @@ public class IncrementalHnswGraphMerger implements HnswGraphMerger {return oldToNewOrdinalMap;}- private static boolean noDeletes(Bits liveDocs) {+ private static boolean hasDeletes(Bits liveDocs) {if (liveDocs == null) {- return true;+ return false;}for (int i = 0; i < liveDocs.length(); i++) {if (!liveDocs.get(i)) {- return false;+ return true;}}- return true;+ return false;}}diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/InitializedHnswGraphBuilder.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/InitializedHnswGraphBuilder.javaindex 179d243233d..7dff036ddde 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/InitializedHnswGraphBuilder.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/InitializedHnswGraphBuilder.java@@ -34,7 +34,6 @@ public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {* Create a new HnswGraphBuilder that is initialized with the provided HnswGraph.** @param scorerSupplier the scorer to use for vectors- * @param M the number of connections to keep per node* @param beamWidth the number of nodes to explore in the search* @param seed the seed for the random number generator* @param initializerGraph the graph to initialize the new graph builder@@ -47,7 +46,6 @@ public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {*/public static InitializedHnswGraphBuilder fromGraph(RandomVectorScorerSupplier scorerSupplier,- int M,int beamWidth,long seed,HnswGraph initializerGraph,@@ -57,17 +55,15 @@ public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {throws IOException {return new InitializedHnswGraphBuilder(scorerSupplier,- M,beamWidth,seed,- initGraph(M, initializerGraph, newOrdMap, totalNumberOfVectors),+ initGraph(initializerGraph, newOrdMap, totalNumberOfVectors),initializedNodes);}public static OnHeapHnswGraph initGraph(- int M, HnswGraph initializerGraph, int[] newOrdMap, int totalNumberOfVectors)- throws IOException {- OnHeapHnswGraph hnsw = new OnHeapHnswGraph(M, totalNumberOfVectors);+ HnswGraph initializerGraph, int[] newOrdMap, int totalNumberOfVectors) throws IOException {+ OnHeapHnswGraph hnsw = new OnHeapHnswGraph(initializerGraph.maxConn(), totalNumberOfVectors);for (int level = initializerGraph.numLevels() - 1; level >= 0; level--) {HnswGraph.NodesIterator it = initializerGraph.getNodesOnLevel(level);while (it.hasNext()) {@@ -93,13 +89,12 @@ public final class InitializedHnswGraphBuilder extends HnswGraphBuilder {public InitializedHnswGraphBuilder(RandomVectorScorerSupplier scorerSupplier,- int M,int beamWidth,long seed,OnHeapHnswGraph initializedGraph,BitSet initializedNodes)throws IOException {- super(scorerSupplier, M, beamWidth, seed, initializedGraph);+ super(scorerSupplier, beamWidth, seed, initializedGraph);this.initializedNodes = initializedNodes;}diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/OnHeapHnswGraph.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/OnHeapHnswGraph.javaindex a79bcd17d91..61f30152787 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/OnHeapHnswGraph.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/OnHeapHnswGraph.java@@ -92,7 +92,14 @@ public final class OnHeapHnswGraph extends HnswGraph implements Accountable {public NeighborArray getNeighbors(int level, int node) {assert node < graph.length;assert level < graph[node].length- : "level=" + level + ", node has only " + graph[node].length + " levels";+ : "level="+ + level+ + ", node "+ + node+ + " has only "+ + graph[node].length+ + " levels for graph "+ + this;assert graph[node][level] != null : "node=" + node + ", level=" + level;return graph[node][level];}@@ -181,6 +188,11 @@ public final class OnHeapHnswGraph extends HnswGraph implements Accountable {return entryNode.get().level + 1;}+ @Override+ public int maxConn() {+ return nsize - 1;+ }+/*** Returns the graph's current entry node on the top level shown as ordinals of the nodes on 0th* leveldiff --git a/lucene/core/src/test/org/apache/lucene/index/TestSortingCodecReader.java b/lucene/core/src/test/org/apache/lucene/index/TestSortingCodecReader.javaindex 9663d676255..8039d8b8f6f 100644--- a/lucene/core/src/test/org/apache/lucene/index/TestSortingCodecReader.java+++ b/lucene/core/src/test/org/apache/lucene/index/TestSortingCodecReader.java@@ -26,6 +26,7 @@ import java.util.Collections;import java.util.List;import java.util.Locale;import org.apache.lucene.codecs.TermVectorsReader;+import org.apache.lucene.codecs.hnsw.HnswGraphProvider;import org.apache.lucene.document.BinaryDocValuesField;import org.apache.lucene.document.Document;import org.apache.lucene.document.Field;@@ -53,6 +54,7 @@ import org.apache.lucene.tests.index.RandomIndexWriter;import org.apache.lucene.tests.util.LuceneTestCase;import org.apache.lucene.util.BytesRef;import org.apache.lucene.util.IOUtils;+import org.apache.lucene.util.hnsw.HnswGraph;public class TestSortingCodecReader extends LuceneTestCase {@@ -151,6 +153,8 @@ public class TestSortingCodecReader extends LuceneTestCase {docIds.add(i);}Collections.shuffle(docIds, random());+ // If true, index a vector for every doc+ boolean denseVectors = random().nextBoolean();try (RandomIndexWriter iw = new RandomIndexWriter(random(), dir)) {for (int i = 0; i < numDocs; i++) {int docId = docIds.get(i);@@ -168,7 +172,9 @@ public class TestSortingCodecReader extends LuceneTestCase {doc.add(new BinaryDocValuesField("binary_dv", new BytesRef(Integer.toString(docId))));doc.add(new SortedSetDocValuesField("sorted_set_dv", new BytesRef(Integer.toString(docId))));- doc.add(new KnnFloatVectorField("vector", new float[] {(float) docId}));+ if (denseVectors || docId % 2 == 0) {+ doc.add(new KnnFloatVectorField("vector", new float[] {(float) docId}));+ }doc.add(new NumericDocValuesField("foo", random().nextInt(20)));FieldType ft = new FieldType(StringField.TYPE_NOT_STORED);@@ -239,6 +245,8 @@ public class TestSortingCodecReader extends LuceneTestCase {SortedSetDocValues sorted_set_dv = leaf.getSortedSetDocValues("sorted_set_dv");SortedDocValues binary_sorted_dv = leaf.getSortedDocValues("binary_sorted_dv");FloatVectorValues vectorValues = leaf.getFloatVectorValues("vector");+ HnswGraph graph =+ ((HnswGraphProvider) ((CodecReader) leaf).getVectorReader()).getGraph("vector");NumericDocValues ids = leaf.getNumericDocValues("id");long prevValue = -1;boolean usingAltIds = false;@@ -264,7 +272,12 @@ public class TestSortingCodecReader extends LuceneTestCase {assertTrue(sorted_numeric_dv.advanceExact(idNext));assertTrue(sorted_set_dv.advanceExact(idNext));assertTrue(binary_sorted_dv.advanceExact(idNext));- assertEquals(idNext, valuesIterator.advance(idNext));+ if (denseVectors || prevValue % 2 == 0) {+ assertEquals(idNext, valuesIterator.advance(idNext));+ graph.seek(0, valuesIterator.index());+ assertNotEquals(DocIdSetIterator.NO_MORE_DOCS, graph.nextNeighbor());+ }+assertEquals(new BytesRef(ids.longValue() + ""), binary_dv.binaryValue());assertEquals(new BytesRef(ids.longValue() + ""),@@ -276,9 +289,11 @@ public class TestSortingCodecReader extends LuceneTestCase {assertEquals(1, sorted_numeric_dv.docValueCount());assertEquals(ids.longValue(), sorted_numeric_dv.nextValue());- float[] vectorValue = vectorValues.vectorValue(valuesIterator.index());- assertEquals(1, vectorValue.length);- assertEquals((float) ids.longValue(), vectorValue[0], 0.001f);+ if (denseVectors || prevValue % 2 == 0) {+ float[] vectorValue = vectorValues.vectorValue(valuesIterator.index());+ assertEquals(1, vectorValue.length);+ assertEquals((float) ids.longValue(), vectorValue[0], 0.001f);+ }Fields termVectors = leaf.termVectors().get(idNext);assertTrue(diff --git a/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java b/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.javaindex 1da8c8169a9..c6da6d30faf 100644--- a/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java+++ b/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java@@ -550,12 +550,11 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {// another graph to do the assertionOnHeapHnswGraph graphAfterInit =InitializedHnswGraphBuilder.initGraph(- 10, initializerGraph, initializerOrdMap, initializerGraph.size());+ initializerGraph, initializerOrdMap, initializerGraph.size());HnswGraphBuilder finalBuilder =InitializedHnswGraphBuilder.fromGraph(finalscorerSupplier,- 10,30,seed,initializerGraph,@@ -593,7 +592,6 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {HnswGraphBuilder finalBuilder =InitializedHnswGraphBuilder.fromGraph(finalscorerSupplier,- 10,30,seed,initializerGraph,@@ -987,7 +985,7 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {HnswGraphBuilder.randSeed = random().nextLong();HnswConcurrentMergeBuilder builder =new HnswConcurrentMergeBuilder(- taskExecutor, 4, scorerSupplier, 10, 30, new OnHeapHnswGraph(10, size), null);+ taskExecutor, 4, scorerSupplier, 30, new OnHeapHnswGraph(10, size), null);builder.setBatchSize(100);builder.build(size);exec.shutdownNow();@@ -1337,6 +1335,11 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {return delegate.entryNode();}+ @Override+ public int maxConn() throws IOException {+ return delegate.maxConn();+ }+@Overridepublic NodesIterator getNodesOnLevel(int level) throws IOException {return delegate.getNodesOnLevel(level);diff --git a/lucene/core/src/test/org/apache/lucene/util/hnsw/TestHnswUtil.java b/lucene/core/src/test/org/apache/lucene/util/hnsw/TestHnswUtil.javaindex 316afff5ee2..7ea05150e14 100644--- a/lucene/core/src/test/org/apache/lucene/util/hnsw/TestHnswUtil.java+++ b/lucene/core/src/test/org/apache/lucene/util/hnsw/TestHnswUtil.java@@ -250,6 +250,11 @@ public class TestHnswUtil extends LuceneTestCase {return 0;}+ @Override+ public int maxConn() {+ return 0;+ }+@Overridepublic String toString() {StringBuilder buf = new StringBuilder();diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.javanew file mode 100644index 00000000000..3f7442a2526--- /dev/null+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java@@ -0,0 +1,78 @@+/*+ * Licensed to the Apache Software Foundation (ASF) under one or more+ * contributor license agreements. See the NOTICE file distributed with+ * this work for additional information regarding copyright ownership.+ * The ASF licenses this file to You under the Apache License, Version 2.0+ * (the "License"); you may not use this file except in compliance with+ * the License. You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */+package org.apache.lucene.misc.index;++/** Base class for docid-reorderers implemented using binary partitioning (BP). */+public abstract class AbstractBPReorderer implements IndexReorderer {+ /**+ * Minimum size of partitions. The algorithm will stop recursing when reaching partitions below+ * this number of documents: 32.+ */+ public static final int DEFAULT_MIN_PARTITION_SIZE = 32;++ /**+ * Default maximum number of iterations per recursion level: 20. Higher numbers of iterations+ * typically don't help significantly.+ */+ public static final int DEFAULT_MAX_ITERS = 20;++ protected int minPartitionSize = DEFAULT_MIN_PARTITION_SIZE;+ protected int maxIters = DEFAULT_MAX_ITERS;+ protected double ramBudgetMB;++ public AbstractBPReorderer() {+ // 10% of the available heap size by default+ setRAMBudgetMB(Runtime.getRuntime().totalMemory() / 1024d / 1024d / 10d);+ }++ /** Set the minimum partition size, when the algorithm stops recursing, 32 by default. */+ public void setMinPartitionSize(int minPartitionSize) {+ if (minPartitionSize < 1) {+ throw new IllegalArgumentException(+ "minPartitionSize must be at least 1, got " + minPartitionSize);+ }+ this.minPartitionSize = minPartitionSize;+ }++ /**+ * Set the maximum number of iterations on each recursion level, 20 by default. Experiments+ * suggests that values above 20 do not help much. However, values below 20 can be used to trade+ * effectiveness for faster reordering.+ */+ public void setMaxIters(int maxIters) {+ if (maxIters < 1) {+ throw new IllegalArgumentException("maxIters must be at least 1, got " + maxIters);+ }+ this.maxIters = maxIters;+ }++ /**+ * Set the amount of RAM that graph partitioning is allowed to use. More RAM allows running+ * faster. If not enough RAM is provided, a {@link NotEnoughRAMException} will be thrown. This is+ * 10% of the total heap size by default.+ */+ public void setRAMBudgetMB(double ramBudgetMB) {+ this.ramBudgetMB = ramBudgetMB;+ }++ /** Exception that is thrown when not enough RAM is available. */+ public static class NotEnoughRAMException extends RuntimeException {+ NotEnoughRAMException(String message) {+ super(message);+ }+ }+}diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.javaindex f51321fe842..6507ff02500 100644--- a/lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.java+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.java@@ -90,14 +90,7 @@ import org.apache.lucene.util.packed.PackedInts;** <p>Note: This is a slow operation that consumes O(maxDoc + numTerms * numThreads) memory.*/-public final class BPIndexReorderer {-- /** Exception that is thrown when not enough RAM is available. */- public static class NotEnoughRAMException extends RuntimeException {- private NotEnoughRAMException(String message) {- super(message);- }- }+public final class BPIndexReorderer extends AbstractBPReorderer {/** Block size for terms in the forward index */private static final int TERM_IDS_BLOCK_SIZE = 17;@@ -108,33 +101,14 @@ public final class BPIndexReorderer {/** Minimum required document frequency for terms to be considered: 4,096. */public static final int DEFAULT_MIN_DOC_FREQ = 4096;- /**- * Minimum size of partitions. The algorithm will stop recursing when reaching partitions below- * this number of documents: 32.- */- public static final int DEFAULT_MIN_PARTITION_SIZE = 32;-- /**- * Default maximum number of iterations per recursion level: 20. Higher numbers of iterations- * typically don't help significantly.- */- public static final int DEFAULT_MAX_ITERS = 20;-private int minDocFreq;private float maxDocFreq;- private int minPartitionSize;- private int maxIters;- private double ramBudgetMB;private Set<String> fields;/** Constructor. */public BPIndexReorderer() {setMinDocFreq(DEFAULT_MIN_DOC_FREQ);setMaxDocFreq(1f);- setMinPartitionSize(DEFAULT_MIN_PARTITION_SIZE);- setMaxIters(DEFAULT_MAX_ITERS);- // 10% of the available heap size by default- setRAMBudgetMB(Runtime.getRuntime().totalMemory() / 1024d / 1024d / 10d);setFields(null);}@@ -159,36 +133,6 @@ public final class BPIndexReorderer {this.maxDocFreq = maxDocFreq;}- /** Set the minimum partition size, when the algorithm stops recursing, 32 by default. */- public void setMinPartitionSize(int minPartitionSize) {- if (minPartitionSize < 1) {- throw new IllegalArgumentException(- "minPartitionSize must be at least 1, got " + minPartitionSize);- }- this.minPartitionSize = minPartitionSize;- }-- /**- * Set the maximum number of iterations on each recursion level, 20 by default. Experiments- * suggests that values above 20 do not help much. However, values below 20 can be used to trade- * effectiveness for faster reordering.- */- public void setMaxIters(int maxIters) {- if (maxIters < 1) {- throw new IllegalArgumentException("maxIters must be at least 1, got " + maxIters);- }- this.maxIters = maxIters;- }-- /**- * Set the amount of RAM that graph partitioning is allowed to use. More RAM allows running- * faster. If not enough RAM is provided, a {@link NotEnoughRAMException} will be thrown. This is- * 10% of the total heap size by default.- */- public void setRAMBudgetMB(double ramBudgetMB) {- this.ramBudgetMB = ramBudgetMB;- }-/*** Sets the fields to use to perform partitioning. A {@code null} value indicates that all indexed* fields should be used.@@ -830,6 +774,7 @@ public final class BPIndexReorderer {* enable integration into {@link BPReorderingMergePolicy}, {@link #reorder(CodecReader,* Directory, Executor)} should be preferred in general.*/+ @Overridepublic Sorter.DocMap computeDocMap(CodecReader reader, Directory tempDir, Executor executor)throws IOException {if (docRAMRequirements(reader.maxDoc()) >= ramBudgetMB * 1024 * 1024) {diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/BPReorderingMergePolicy.java b/lucene/misc/src/java/org/apache/lucene/misc/index/BPReorderingMergePolicy.javaindex 5cd363192fa..70fcea733eb 100644--- a/lucene/misc/src/java/org/apache/lucene/misc/index/BPReorderingMergePolicy.java+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/BPReorderingMergePolicy.java@@ -27,7 +27,7 @@ import org.apache.lucene.index.MergeTrigger;import org.apache.lucene.index.SegmentCommitInfo;import org.apache.lucene.index.SegmentInfos;import org.apache.lucene.index.Sorter;-import org.apache.lucene.misc.index.BPIndexReorderer.NotEnoughRAMException;+import org.apache.lucene.misc.index.AbstractBPReorderer.NotEnoughRAMException;import org.apache.lucene.store.Directory;import org.apache.lucene.util.SetOnce;@@ -42,7 +42,7 @@ public final class BPReorderingMergePolicy extends FilterMergePolicy {/** Whether a segment has been reordered. */static final String REORDERED = "bp.reordered";- private final BPIndexReorderer reorderer;+ private final IndexReorderer reorderer;private int minNaturalMergeNumDocs = 1;private float minNaturalMergeRatioFromBiggestSegment = 0f;@@ -59,7 +59,7 @@ public final class BPReorderingMergePolicy extends FilterMergePolicy {* @param in the merge policy to use to compute merges* @param reorderer the {@link BPIndexReorderer} to use to renumber doc IDs*/- public BPReorderingMergePolicy(MergePolicy in, BPIndexReorderer reorderer) {+ public BPReorderingMergePolicy(MergePolicy in, IndexReorderer reorderer) {super(in);this.reorderer = reorderer;}diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/BpVectorReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/BpVectorReorderer.javanew file mode 100644index 00000000000..7facf48580c--- /dev/null+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/BpVectorReorderer.java@@ -0,0 +1,792 @@+/*+ * Licensed to the Apache Software Foundation (ASF) under one or more+ * contributor license agreements. See the NOTICE file distributed with+ * this work for additional information regarding copyright ownership.+ * The ASF licenses this file to You under the Apache License, Version 2.0+ * (the "License"); you may not use this file except in compliance with+ * the License. You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */+package org.apache.lucene.misc.index;++import static org.apache.lucene.search.DocIdSetIterator.NO_MORE_DOCS;++import java.io.IOException;+import java.io.UncheckedIOException;+import java.nio.file.Path;+import java.util.Arrays;+import java.util.concurrent.Executor;+import java.util.concurrent.ForkJoinPool;+import java.util.concurrent.ForkJoinWorkerThread;+import java.util.concurrent.RecursiveAction;+import org.apache.lucene.index.CodecReader;+import org.apache.lucene.index.DirectoryReader;+import org.apache.lucene.index.FieldInfo;+import org.apache.lucene.index.FloatVectorValues;+import org.apache.lucene.index.IndexReader;+import org.apache.lucene.index.IndexWriter;+import org.apache.lucene.index.IndexWriterConfig;+import org.apache.lucene.index.LeafReaderContext;+import org.apache.lucene.index.Sorter;+import org.apache.lucene.index.SortingCodecReader;+import org.apache.lucene.index.VectorEncoding;+import org.apache.lucene.index.VectorSimilarityFunction;+import org.apache.lucene.search.DocIdSetIterator;+import org.apache.lucene.search.TaskExecutor;+import org.apache.lucene.store.Directory;+import org.apache.lucene.store.FSDirectory;+import org.apache.lucene.util.CloseableThreadLocal;+import org.apache.lucene.util.IntroSelector;+import org.apache.lucene.util.IntsRef;+import org.apache.lucene.util.VectorUtil;++/**+ * Implementation of "recursive graph bisection", also called "bipartite graph partitioning" and+ * often abbreviated BP, an approach to doc ID assignment that aims at reducing the sum of the log+ * gap between consecutive neighbor node ids. See {@link BPIndexReorderer}.+ */+public class BpVectorReorderer extends AbstractBPReorderer {++ /*+ * Note on using centroids (mean of vectors in a partition) to maximize scores of pairs of vectors within each partition:+ * The function used to compare the vectors must have higher values for vectors+ * that are more similar to each other, and must preserve inequalities over sums of vectors.+ *+ * <p>This property enables us to use the centroid of a collection of vectors to represent the+ * collection. For Euclidean and inner product score functions, the centroid is the point that+ * minimizes the sum of distances from all the points (thus maximizing the score).+ *+ * <p>sum((c0 - v)^2) = n * c0^2 - 2 * c0 * sum(v) + sum(v^2) taking derivative w.r.t. c0 and+ * setting to 0 we get sum(v) = n * c0; i.e. c0 (the centroid) is the place that minimizes the sum+ * of (l2) distances from the vectors (thus maximizing the euclidean score function).+ *+ * <p>to maximize dot-product over unit vectors, note that: sum(dot(c0, v)) = dot(c0, sum(v))+ * which is maximized, again, when c0 = sum(v) / n. For max inner product score, vectors may not+ * be unit vectors. In this case there is no maximum, but since all colinear vectors of whatever+ * scale will generate the same partition for these angular scores, we are free to choose any+ * scale and ignore the normalization factor.+ */++ /** Minimum problem size that will result in tasks being split. */+ private static final int FORK_THRESHOLD = 8192;++ /**+ * Limits how many incremental updates we do before initiating a full recalculation. Some wasted+ * work is done when this is exceeded, but more is saved when it is not. Setting this to zero+ * prevents any incremental updates from being done, instead the centroids are fully recalculated+ * for each iteration. We're not able to make it very big since too much numerical error+ * accumulates, which seems to be around 50, thus resulting in suboptimal reordering. It's not+ * clear how helpful this is though; measurements vary, so it is currently disabled (= 0).+ */+ private static final int MAX_CENTROID_UPDATES = 0;++ private final String partitionField;++ /** Constructor. */+ public BpVectorReorderer(String partitionField) {+ setMinPartitionSize(DEFAULT_MIN_PARTITION_SIZE);+ setMaxIters(DEFAULT_MAX_ITERS);+ // 10% of the available heap size by default+ setRAMBudgetMB(Runtime.getRuntime().totalMemory() / 1024d / 1024d / 10d);+ this.partitionField = partitionField;+ }++ private static class PerThreadState {++ final FloatVectorValues vectors;+ final float[] leftCentroid;+ final float[] rightCentroid;+ final float[] scratch;++ PerThreadState(FloatVectorValues vectors) {+ try {+ this.vectors = vectors.copy();+ } catch (IOException e) {+ throw new UncheckedIOException(e);+ }+ leftCentroid = new float[vectors.dimension()];+ rightCentroid = new float[leftCentroid.length];+ scratch = new float[leftCentroid.length];+ }+ }++ private static class DocMap extends Sorter.DocMap {++ private final int[] newToOld;+ private final int[] oldToNew;++ public DocMap(int[] newToOld) {+ this.newToOld = newToOld;+ oldToNew = new int[newToOld.length];+ for (int i = 0; i < newToOld.length; ++i) {+ oldToNew[newToOld[i]] = i;+ }+ }++ @Override+ public int size() {+ return newToOld.length;+ }++ @Override+ public int oldToNew(int docID) {+ return oldToNew[docID];+ }++ @Override+ public int newToOld(int docID) {+ return newToOld[docID];+ }+ }++ private abstract class BaseRecursiveAction extends RecursiveAction {++ protected final TaskExecutor executor;+ protected final int depth;++ BaseRecursiveAction(TaskExecutor executor, int depth) {+ this.executor = executor;+ this.depth = depth;+ }++ protected final boolean shouldFork(int problemSize, int totalProblemSize) {+ if (executor == null) {+ return false;+ }+ if (getSurplusQueuedTaskCount() > 3) {+ // Fork tasks if this worker doesn't have more queued work than other workers+ // See javadocs of #getSurplusQueuedTaskCount for more details+ return false;+ }+ if (problemSize == totalProblemSize) {+ // Sometimes fork regardless of the problem size to make sure that unit tests also exercise+ // forking+ return true;+ }+ return problemSize > FORK_THRESHOLD;+ }+ }++ private class ReorderTask extends BaseRecursiveAction {++ private final VectorSimilarityFunction vectorScore;+ // the ids assigned to this task, a sub-range of all the ids+ private final IntsRef ids;+ // the biases for the ids - a number < 0 when the doc goes left and > 0 for right+ private final float[] biases;+ private final CloseableThreadLocal<PerThreadState> threadLocal;++ ReorderTask(+ IntsRef ids,+ float[] biases,+ CloseableThreadLocal<PerThreadState> threadLocal,+ TaskExecutor executor,+ int depth,+ VectorSimilarityFunction vectorScore) {+ super(executor, depth);+ this.ids = ids;+ this.biases = biases;+ this.threadLocal = threadLocal;+ this.vectorScore = vectorScore;+ }++ @Override+ protected void compute() {+ if (depth > 0) {+ Arrays.sort(ids.ints, ids.offset, ids.offset + ids.length);+ } else {+ assert sorted(ids);+ }++ int halfLength = ids.length >>> 1;+ if (halfLength < minPartitionSize) {+ return;+ }++ // split the ids in half+ IntsRef left = new IntsRef(ids.ints, ids.offset, halfLength);+ IntsRef right = new IntsRef(ids.ints, ids.offset + halfLength, ids.length - halfLength);++ PerThreadState state = threadLocal.get();+ FloatVectorValues vectors = state.vectors;+ float[] leftCentroid = state.leftCentroid;+ float[] rightCentroid = state.rightCentroid;+ float[] scratch = state.scratch;++ try {+ computeCentroid(left, vectors, leftCentroid, vectorScore);+ computeCentroid(right, vectors, rightCentroid, vectorScore);+ } catch (IOException e) {+ throw new UncheckedIOException(e);+ }++ for (int iter = 0; iter < maxIters; ++iter) {+ int moved;+ try {+ moved = shuffle(vectors, ids, right.offset, leftCentroid, rightCentroid, scratch, biases);+ } catch (IOException e) {+ throw new UncheckedIOException(e);+ }+ if (moved == 0) {+ break;+ }+ if (moved > MAX_CENTROID_UPDATES) {+ // if we swapped too many times we don't use the relative calculation because it+ // introduces too much error+ try {+ computeCentroid(left, vectors, leftCentroid, vectorScore);+ computeCentroid(right, vectors, rightCentroid, vectorScore);+ } catch (IOException e) {+ throw new UncheckedIOException(e);+ }+ }+ }++ // It is fine for all tasks to share the same docs / biases array since they all work on+ // different slices of the array at a given point in time.+ ReorderTask leftTask =+ new ReorderTask(left, biases, threadLocal, executor, depth + 1, vectorScore);+ ReorderTask rightTask =+ new ReorderTask(right, biases, threadLocal, executor, depth + 1, vectorScore);++ if (shouldFork(ids.length, ids.ints.length)) {+ invokeAll(leftTask, rightTask);+ } else {+ leftTask.compute();+ rightTask.compute();+ }+ }++ static void computeCentroid(+ IntsRef ids,+ FloatVectorValues vectors,+ float[] centroid,+ VectorSimilarityFunction vectorSimilarity)+ throws IOException {+ Arrays.fill(centroid, 0);+ for (int i = ids.offset; i < ids.offset + ids.length; i++) {+ VectorUtil.add(centroid, vectors.vectorValue(ids.ints[i]));+ }+ switch (vectorSimilarity) {+ case EUCLIDEAN, MAXIMUM_INNER_PRODUCT -> vectorScalarMul(1 / (float) ids.length, centroid);+ case DOT_PRODUCT, COSINE ->+ vectorScalarMul(+ 1 / (float) Math.sqrt(VectorUtil.dotProduct(centroid, centroid)), centroid);+ }+ }++ /** Shuffle IDs across both partitions so that each partition is closer to its centroid. */+ private int shuffle(+ FloatVectorValues vectors,+ IntsRef ids,+ int midPoint,+ float[] leftCentroid,+ float[] rightCentroid,+ float[] scratch,+ float[] biases)+ throws IOException {++ /* Computing biases requires a distance calculation for each vector (document) which can be+ * costly, especially as the vector dimension increases, so we try to parallelize it. We also+ * have the option of performing incremental updates based on the difference of the previous and+ * the new centroid, which can be less costly, but introduces incremental numeric error, and+ * needs tuning to be usable. It is disabled by default (see MAX_CENTROID_UPDATES).+ */+ new ComputeBiasTask(+ ids.ints,+ biases,+ ids.offset,+ ids.offset + ids.length,+ leftCentroid,+ rightCentroid,+ threadLocal,+ executor,+ depth,+ vectorScore)+ .compute();++ float scale =+ VectorUtil.dotProduct(leftCentroid, leftCentroid)+ + VectorUtil.dotProduct(rightCentroid, rightCentroid);+ float maxLeftBias = Float.NEGATIVE_INFINITY;+ for (int i = ids.offset; i < midPoint; ++i) {+ maxLeftBias = Math.max(maxLeftBias, biases[i]);+ }+ float minRightBias = Float.POSITIVE_INFINITY;+ for (int i = midPoint, end = ids.offset + ids.length; i < end; ++i) {+ minRightBias = Math.min(minRightBias, biases[i]);+ }+ float gain = maxLeftBias - minRightBias;+ /* This compares the gain of swapping the doc from the left side that is most attracted to the+ * right and the doc from the right side that is most attracted to the left against the+ * average vector length (/500) rather than zero. 500 is an arbitrary heuristic value+ * determined empirically - basically we stop iterating once the centroids move less than+ * 1/500 the sum of their lengths.+ *+ * TODO We could try incorporating simulated annealing by including the iteration number in the+ * formula? eg { 1000 * gain <= scale * iter }.+ */++ // System.out.printf("at depth=%d, midPoint=%d, gain=%f\n", depth, midPoint, gain);+ if (500 * gain <= scale) {+ return 0;+ }++ class Selector extends IntroSelector {+ int count = 0;+ int pivotDoc;+ float pivotBias;++ @Override+ public void setPivot(int i) {+ pivotDoc = ids.ints[i];+ pivotBias = biases[i];+ }++ @Override+ public int comparePivot(int j) {+ int cmp = Float.compare(pivotBias, biases[j]);+ if (cmp == 0) {+ // Tie break on the ID to preserve ID ordering as much as possible+ cmp = pivotDoc - ids.ints[j];+ }+ return cmp;+ }++ @Override+ public void swap(int i, int j) {+ float tmpBias = biases[i];+ biases[i] = biases[j];+ biases[j] = tmpBias;++ if (i < midPoint == j < midPoint) {+ int tmpDoc = ids.ints[i];+ ids.ints[i] = ids.ints[j];+ ids.ints[j] = tmpDoc;+ } else {+ // If we're swapping across the left and right sides, we need to keep centroids+ // up-to-date.+ count++;+ int from = Math.min(i, j);+ int to = Math.max(i, j);+ try {+ swapIdsAndCentroids(+ ids,+ from,+ to,+ midPoint,+ vectors,+ leftCentroid,+ rightCentroid,+ scratch,+ count,+ vectorScore);+ } catch (IOException e) {+ throw new UncheckedIOException(e);+ }+ }+ }+ }++ Selector selector = new Selector();+ selector.select(ids.offset, ids.offset + ids.length, midPoint);+ // System.out.printf("swapped %d / %d\n", selector.count, ids.length);+ return selector.count;+ }++ private static boolean centroidValid(+ float[] centroid, FloatVectorValues vectors, IntsRef ids, int count) throws IOException {+ // recompute centroid to check the incremental calculation+ float[] check = new float[centroid.length];+ computeCentroid(ids, vectors, check, VectorSimilarityFunction.EUCLIDEAN);+ for (int i = 0; i < check.length; ++i) {+ float diff = Math.abs(check[i] - centroid[i]);+ if (diff > 1e-4) {+ return false;+ }+ }+ return true;+ }++ private static void swapIdsAndCentroids(+ IntsRef ids,+ int from,+ int to,+ int midPoint,+ FloatVectorValues vectors,+ float[] leftCentroid,+ float[] rightCentroid,+ float[] scratch,+ int count,+ VectorSimilarityFunction vectorScore)+ throws IOException {+ assert from < to;++ int[] idArr = ids.ints;+ int fromId = idArr[from];+ int toId = idArr[to];++ // Now update the centroids, this makes things much faster than invalidating it and having to+ // recompute on the next iteration. Should be faster than full recalculation if the number of+ // swaps is reasonable.++ // We want the net effect to be moving "from" left->right and "to" right->left++ // (1) scratch = to - from+ if (count <= MAX_CENTROID_UPDATES && vectorScore == VectorSimilarityFunction.EUCLIDEAN) {+ int relativeMidpoint = midPoint - ids.offset;+ vectorSubtract(vectors.vectorValue(toId), vectors.vectorValue(fromId), scratch);+ // we must normalize to the proper scale by accounting for the number of points contributing+ // to each centroid+ // left += scratch / size(left)+ vectorScalarMul(1 / (float) relativeMidpoint, scratch);+ VectorUtil.add(leftCentroid, scratch);+ // right -= scratch / size(right)+ vectorScalarMul(-relativeMidpoint / (float) (ids.length - relativeMidpoint), scratch);+ VectorUtil.add(rightCentroid, scratch);+ }++ idArr[from] = toId;+ idArr[to] = fromId;++ if (count <= MAX_CENTROID_UPDATES) {+ assert centroidValid(+ leftCentroid, vectors, new IntsRef(idArr, ids.offset, midPoint - ids.offset), count);+ assert centroidValid(+ rightCentroid,+ vectors,+ new IntsRef(ids.ints, midPoint, ids.length - midPoint + ids.offset),+ count);+ }+ }+ }++ /**+ * Adds the second argument to the first+ *+ * @param u the destination+ * @param v the vector to add to the destination+ */+ static void vectorSubtract(float[] u, float[] v, float[] result) {+ for (int i = 0; i < u.length; i++) {+ result[i] = u[i] - v[i];+ }+ }++ static void vectorScalarMul(float x, float[] v) {+ for (int i = 0; i < v.length; i++) {+ v[i] *= x;+ }+ }++ private class ComputeBiasTask extends BaseRecursiveAction {++ private final int[] ids;+ private final float[] biases;+ private final int start;+ private final int end;+ private final float[] leftCentroid;+ private final float[] rightCentroid;+ private final CloseableThreadLocal<PerThreadState> threadLocal;+ private final VectorSimilarityFunction vectorScore;++ ComputeBiasTask(+ int[] ids,+ float[] biases,+ int start,+ int end,+ float[] leftCentroid,+ float[] rightCentroid,+ CloseableThreadLocal<PerThreadState> threadLocal,+ TaskExecutor executor,+ int depth,+ VectorSimilarityFunction vectorScore) {+ super(executor, depth);+ this.ids = ids;+ this.biases = biases;+ this.start = start;+ this.end = end;+ this.leftCentroid = leftCentroid;+ this.rightCentroid = rightCentroid;+ this.threadLocal = threadLocal;+ this.vectorScore = vectorScore;+ }++ @Override+ protected void compute() {+ final int problemSize = end - start;+ if (problemSize > 1 && shouldFork(problemSize, ids.length)) {+ final int mid = (start + end) >>> 1;+ invokeAll(+ new ComputeBiasTask(+ ids,+ biases,+ start,+ mid,+ leftCentroid,+ rightCentroid,+ threadLocal,+ executor,+ depth,+ vectorScore),+ new ComputeBiasTask(+ ids,+ biases,+ mid,+ end,+ leftCentroid,+ rightCentroid,+ threadLocal,+ executor,+ depth,+ vectorScore));+ } else {+ FloatVectorValues vectors = threadLocal.get().vectors;+ try {+ for (int i = start; i < end; ++i) {+ biases[i] = computeBias(vectors.vectorValue(ids[i]), leftCentroid, rightCentroid);+ }+ } catch (IOException e) {+ throw new UncheckedIOException(e);+ }+ }+ }++ /**+ * Compute a float that is negative when a vector is attracted to the left and positive+ * otherwise.+ */+ private float computeBias(float[] vector, float[] leftCentroid, float[] rightCentroid) {+ return switch (vectorScore) {+ case EUCLIDEAN ->+ VectorUtil.squareDistance(vector, leftCentroid)+ - VectorUtil.squareDistance(vector, rightCentroid);+ case MAXIMUM_INNER_PRODUCT, COSINE, DOT_PRODUCT ->+ VectorUtil.dotProduct(vector, rightCentroid)+ - VectorUtil.dotProduct(vector, leftCentroid);+ default -> throw new IllegalStateException("unsupported vector score: " + vectorScore);+ };+ }+ }++ @Override+ public Sorter.DocMap computeDocMap(CodecReader reader, Directory tempDir, Executor executor)+ throws IOException {+ TaskExecutor taskExecutor;+ if (executor == null) {+ taskExecutor = null;+ } else {+ taskExecutor = new TaskExecutor(executor);+ }+ VectorSimilarityFunction vectorScore = checkField(reader, partitionField);+ if (vectorScore == null) {+ return null;+ }+ FloatVectorValues floats = reader.getFloatVectorValues(partitionField);+ Sorter.DocMap valueMap = computeValueMap(floats, vectorScore, taskExecutor);+ return valueMapToDocMap(valueMap, floats, reader.maxDoc());+ }++ /** Expert: Compute the {@link DocMap} that holds the new vector ordinal numbering. */+ Sorter.DocMap computeValueMap(+ FloatVectorValues vectors, VectorSimilarityFunction vectorScore, TaskExecutor executor) {+ if (docRAMRequirements(vectors.size()) >= ramBudgetMB * 1024 * 1024) {+ throw new NotEnoughRAMException(+ "At least "+ + Math.ceil(docRAMRequirements(vectors.size()) / 1024. / 1024.)+ + "MB of RAM are required to hold metadata about documents in RAM, but current RAM budget is "+ + ramBudgetMB+ + "MB");+ }+ return new DocMap(computePermutation(vectors, vectorScore, executor));+ }++ /**+ * Compute a permutation of the ID space that maximizes vector score between consecutive postings.+ */+ private int[] computePermutation(+ FloatVectorValues vectors, VectorSimilarityFunction vectorScore, TaskExecutor executor) {+ final int size = vectors.size();+ int[] sortedIds = new int[size];+ for (int i = 0; i < size; ++i) {+ sortedIds[i] = i;+ }+ try (CloseableThreadLocal<PerThreadState> threadLocal =+ new CloseableThreadLocal<>() {+ @Override+ protected PerThreadState initialValue() {+ return new PerThreadState(vectors);+ }+ }) {+ IntsRef ids = new IntsRef(sortedIds, 0, sortedIds.length);+ new ReorderTask(ids, new float[size], threadLocal, executor, 0, vectorScore).compute();+ }+ return sortedIds;+ }++ /** Returns true if, and only if, the given {@link IntsRef} is sorted. */+ private static boolean sorted(IntsRef intsRef) {+ for (int i = 1; i < intsRef.length; ++i) {+ if (intsRef.ints[intsRef.offset + i - 1] > intsRef.ints[intsRef.offset + i]) {+ return false;+ }+ }+ return true;+ }++ private static long docRAMRequirements(int maxDoc) {+ // We need one int per vector for the doc map, plus one float to store the bias associated with+ // this vector.+ return 2L * Integer.BYTES * maxDoc;+ }++ /**+ * @param args two args: a path containing an index to reorder. the name of the field the contents+ * of which to use for reordering+ */+ @SuppressWarnings("unused")+ public static void main(String... args) throws IOException {+ if (args.length < 2 || args.length > 8) {+ usage();+ }+ String directory = args[0];+ String field = args[1];+ BpVectorReorderer reorderer = new BpVectorReorderer(field);+ int threadCount = Runtime.getRuntime().availableProcessors();+ try {+ for (int i = 2; i < args.length; i++) {+ switch (args[i]) {+ case "--max-iters" -> reorderer.setMaxIters(Integer.parseInt(args[++i]));+ case "--min-partition-size" -> reorderer.setMinPartitionSize(Integer.parseInt(args[++i]));+ case "--thread-count" -> threadCount = Integer.parseInt(args[++i]);+ default -> throw new IllegalArgumentException("unknown argument: " + args[i]);+ }+ }+ } catch (NumberFormatException | ArrayIndexOutOfBoundsException e) {+ usage();+ }+ Executor executor;+ if (threadCount != 1) {+ executor = new ForkJoinPool(threadCount, p -> new ForkJoinWorkerThread(p) {}, null, false);+ } else {+ executor = null;+ }+ try (Directory dir = FSDirectory.open(Path.of(directory))) {+ reorderer.reorderIndexDirectory(dir, executor);+ }+ }++ void reorderIndexDirectory(Directory directory, Executor executor) throws IOException {+ try (IndexReader reader = DirectoryReader.open(directory)) {+ IndexWriterConfig iwc = new IndexWriterConfig();+ iwc.setOpenMode(IndexWriterConfig.OpenMode.CREATE);+ try (IndexWriter writer = new IndexWriter(directory, iwc)) {+ for (LeafReaderContext ctx : reader.leaves()) {+ CodecReader codecReader = (CodecReader) ctx.reader();+ writer.addIndexes(+ SortingCodecReader.wrap(+ codecReader, computeDocMap(codecReader, null, executor), null));+ }+ }+ }+ }++ private static VectorSimilarityFunction checkField(CodecReader reader, String field)+ throws IOException {+ FieldInfo finfo = reader.getFieldInfos().fieldInfo(field);+ if (finfo == null) {+ return null;+ /*+ throw new IllegalStateException(+ "field not found: " + field + " in leaf " + reader.getContext().ord);+ */+ }+ if (finfo.hasVectorValues() == false) {+ return null;+ /*+ throw new IllegalStateException(+ "field not a vector field: " + field + " in leaf " + reader.getContext().ord);+ */+ }+ if (finfo.getVectorEncoding() != VectorEncoding.FLOAT32) {+ return null;+ /*+ throw new IllegalStateException(+ "vector field not encoded as float32: " + field + " in leaf " + reader.getContext().ord);+ */+ }+ return finfo.getVectorSimilarityFunction();+ }++ private static void usage() {+ throw new IllegalArgumentException(+ """+ usage: reorder <directory> <field>+ [--max-iters N]+ [--min-partition-size P]+ [--thread-count T]""");+ }++ private static Sorter.DocMap valueMapToDocMap(+ Sorter.DocMap valueMap, FloatVectorValues values, int maxDoc) throws IOException {+ if (maxDoc == values.size()) {+ return valueMap;+ }+ // valueMap maps old/new ords+ // values maps old docs/old ords+ // we want old docs/new docs map+ // sort docs with no value at the end+ int[] newToOld = new int[maxDoc];+ int[] oldToNew = new int[newToOld.length];+ int docid = 0;+ int ord = 0;+ int nextNullDoc = values.size();+ DocIdSetIterator it = values.iterator();+ for (int nextDoc = it.nextDoc(); nextDoc != NO_MORE_DOCS; nextDoc = it.nextDoc()) {+ while (docid < nextDoc) {+ oldToNew[docid] = nextNullDoc;+ newToOld[nextNullDoc] = docid;+ ++docid;+ ++nextNullDoc;+ }+ // check me+ assert docid == nextDoc;+ int newOrd = valueMap.oldToNew(ord);+ oldToNew[docid] = newOrd;+ newToOld[newOrd] = docid;+ ++ord;+ ++docid;+ }+ while (docid < maxDoc) {+ oldToNew[docid] = nextNullDoc;+ newToOld[nextNullDoc] = docid;+ ++docid;+ ++nextNullDoc;+ }++ return new Sorter.DocMap() {++ @Override+ public int size() {+ return newToOld.length;+ }++ @Override+ public int oldToNew(int docID) {+ return oldToNew[docID];+ }++ @Override+ public int newToOld(int docID) {+ return newToOld[docID];+ }+ };+ }+}diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.javanew file mode 100644index 00000000000..1fdba7a4eb0--- /dev/null+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java@@ -0,0 +1,36 @@+/*+ * Licensed to the Apache Software Foundation (ASF) under one or more+ * contributor license agreements. See the NOTICE file distributed with+ * this work for additional information regarding copyright ownership.+ * The ASF licenses this file to You under the Apache License, Version 2.0+ * (the "License"); you may not use this file except in compliance with+ * the License. You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */+package org.apache.lucene.misc.index;++import java.io.IOException;+import java.util.concurrent.Executor;+import org.apache.lucene.index.CodecReader;+import org.apache.lucene.index.Sorter;+import org.apache.lucene.store.Directory;++/** Interface for docid-reordering expected by {@link BPReorderingMergePolicy}. */+public interface IndexReorderer {+ /**+ * Returns a mapping from old to new docids.+ *+ * @param reader the reader whose docs are to be reordered+ * @param tempDir temporary files may be stored here while reordering.+ * @param executor may be used to parallelize reordering work.+ */+ Sorter.DocMap computeDocMap(CodecReader reader, Directory tempDir, Executor executor)+ throws IOException;+}diff --git a/lucene/misc/src/test/org/apache/lucene/misc/index/TestBPReorderingMergePolicy.java b/lucene/misc/src/test/org/apache/lucene/misc/index/TestBPReorderingMergePolicy.javaindex b4c68b30c85..9d5b193632d 100644--- a/lucene/misc/src/test/org/apache/lucene/misc/index/TestBPReorderingMergePolicy.java+++ b/lucene/misc/src/test/org/apache/lucene/misc/index/TestBPReorderingMergePolicy.java@@ -20,6 +20,7 @@ import java.io.IOException;import java.io.UncheckedIOException;import org.apache.lucene.document.Document;import org.apache.lucene.document.Field.Store;+import org.apache.lucene.document.KnnFloatVectorField;import org.apache.lucene.document.StringField;import org.apache.lucene.index.CodecReader;import org.apache.lucene.index.DirectoryReader;@@ -35,17 +36,32 @@ import org.apache.lucene.search.DocIdSetIterator;import org.apache.lucene.store.Directory;import org.apache.lucene.tests.util.LuceneTestCase;import org.apache.lucene.util.IOUtils;+import org.junit.Before;public class TestBPReorderingMergePolicy extends LuceneTestCase {+ AbstractBPReorderer reorderer;++ @Override+ @Before+ public void setUp() throws Exception {+ super.setUp();+ if (random().nextBoolean()) {+ BPIndexReorderer bpIndexReorderer = new BPIndexReorderer();+ bpIndexReorderer.setMinDocFreq(2);+ reorderer = bpIndexReorderer;+ } else {+ BpVectorReorderer bpVectorReorderer = new BpVectorReorderer("vector");+ reorderer = bpVectorReorderer;+ }+ reorderer.setMinPartitionSize(2);+ }+public void testReorderOnMerge() throws IOException {Directory dir1 = newDirectory();Directory dir2 = newDirectory();IndexWriter w1 =new IndexWriter(dir1, newIndexWriterConfig().setMergePolicy(newLogMergePolicy()));- BPIndexReorderer reorderer = new BPIndexReorderer();- reorderer.setMinDocFreq(2);- reorderer.setMinPartitionSize(2);BPReorderingMergePolicy mp = new BPReorderingMergePolicy(newLogMergePolicy(), reorderer);mp.setMinNaturalMergeNumDocs(2);IndexWriter w2 = new IndexWriter(dir2, newIndexWriterConfig().setMergePolicy(mp));@@ -54,10 +70,14 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {doc.add(idField);StringField bodyField = new StringField("body", "", Store.YES);doc.add(bodyField);+ KnnFloatVectorField vectorField = new KnnFloatVectorField("vector", new float[] {0});+ doc.add(vectorField);for (int i = 0; i < 10000; ++i) {idField.setStringValue(Integer.toString(i));- bodyField.setStringValue(Integer.toString(i % 2 == 0 ? 0 : i % 10));+ int intValue = i % 2 == 0 ? 0 : i % 10;+ bodyField.setStringValue(Integer.toString(intValue));+ vectorField.setVectorValue(new float[] {intValue});w1.addDocument(doc);w2.addDocument(doc);@@ -131,10 +151,15 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {doc.add(idField);StringField bodyField = new StringField("body", "", Store.YES);doc.add(bodyField);+ KnnFloatVectorField vectorField = new KnnFloatVectorField("vector", new float[] {0});+ doc.add(vectorField);for (int i = 0; i < 10000; ++i) {idField.setStringValue(Integer.toString(i));- bodyField.setStringValue(Integer.toString(i % 2 == 0 ? 0 : i % 10));+ int intValue = i % 2 == 0 ? 0 : i % 10;+ bodyField.setStringValue(Integer.toString(intValue));+ vectorField.setVectorValue(new float[] {intValue});+w1.addDocument(doc);if (i % 3 == 0) {@@ -147,9 +172,6 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {}Directory dir2 = newDirectory();- BPIndexReorderer reorderer = new BPIndexReorderer();- reorderer.setMinDocFreq(2);- reorderer.setMinPartitionSize(2);BPReorderingMergePolicy mp = new BPReorderingMergePolicy(newLogMergePolicy(), reorderer);mp.setMinNaturalMergeNumDocs(2);IndexWriter w2 = new IndexWriter(dir2, newIndexWriterConfig().setMergePolicy(mp));@@ -222,9 +244,6 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {public void testReorderDoesntHaveEnoughRAM() throws IOException {// This just makes sure that reordering the index on merge does not corrupt its contentDirectory dir = newDirectory();- BPIndexReorderer reorderer = new BPIndexReorderer();- reorderer.setMinDocFreq(2);- reorderer.setMinPartitionSize(2);reorderer.setRAMBudgetMB(Double.MIN_VALUE);BPReorderingMergePolicy mp = new BPReorderingMergePolicy(newLogMergePolicy(), reorderer);mp.setMinNaturalMergeNumDocs(2);@@ -234,10 +253,14 @@ public class TestBPReorderingMergePolicy extends LuceneTestCase {doc.add(idField);StringField bodyField = new StringField("body", "", Store.YES);doc.add(bodyField);+ KnnFloatVectorField vectorField = new KnnFloatVectorField("vector", new float[] {0});+ doc.add(vectorField);for (int i = 0; i < 10; ++i) {idField.setStringValue(Integer.toString(i));- bodyField.setStringValue(Integer.toString(i % 2 == 0 ? 0 : i % 10));+ int intValue = i % 2 == 0 ? 0 : i % 10;+ bodyField.setStringValue(Integer.toString(intValue));+ vectorField.setVectorValue(new float[] {intValue});w.addDocument(doc);DirectoryReader.open(w).close();}diff --git a/lucene/misc/src/test/org/apache/lucene/misc/index/TestBpVectorReorderer.java b/lucene/misc/src/test/org/apache/lucene/misc/index/TestBpVectorReorderer.javanew file mode 100644index 00000000000..7441e68f7d4--- /dev/null+++ b/lucene/misc/src/test/org/apache/lucene/misc/index/TestBpVectorReorderer.java@@ -0,0 +1,434 @@+/*+ * Licensed to the Apache Software Foundation (ASF) under one or more+ * contributor license agreements. See the NOTICE file distributed with+ * this work for additional information regarding copyright ownership.+ * The ASF licenses this file to You under the Apache License, Version 2.0+ * (the "License"); you may not use this file except in compliance with+ * the License. You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */++package org.apache.lucene.misc.index;++import java.io.IOException;+import java.nio.file.Path;+import java.util.ArrayList;+import java.util.Collections;+import java.util.List;+import java.util.concurrent.Executor;+import java.util.concurrent.ForkJoinPool;+import java.util.concurrent.ForkJoinWorkerThread;+import org.apache.lucene.codecs.KnnVectorsFormat;+import org.apache.lucene.codecs.lucene101.Lucene101Codec;+import org.apache.lucene.codecs.lucene99.Lucene99HnswScalarQuantizedVectorsFormat;+import org.apache.lucene.document.Document;+import org.apache.lucene.document.KnnFloatVectorField;+import org.apache.lucene.document.StoredField;+import org.apache.lucene.index.DirectoryReader;+import org.apache.lucene.index.FloatVectorValues;+import org.apache.lucene.index.IndexReader;+import org.apache.lucene.index.IndexWriter;+import org.apache.lucene.index.IndexWriterConfig;+import org.apache.lucene.index.KnnVectorValues;+import org.apache.lucene.index.LeafReader;+import org.apache.lucene.index.Sorter;+import org.apache.lucene.index.StoredFields;+import org.apache.lucene.index.VectorSimilarityFunction;+import org.apache.lucene.search.DocIdSetIterator;+import org.apache.lucene.search.TaskExecutor;+import org.apache.lucene.store.Directory;+import org.apache.lucene.tests.util.LuceneTestCase;+import org.apache.lucene.util.VectorUtil;++/** Tests reordering vector values using Binary Partitioning */+public class TestBpVectorReorderer extends LuceneTestCase {++ public static final String FIELD_NAME = "knn";+ BpVectorReorderer reorderer;++ @Override+ public void setUp() throws Exception {+ super.setUp();+ reorderer = new BpVectorReorderer(FIELD_NAME);+ reorderer.setMinPartitionSize(1);+ reorderer.setMaxIters(10);+ }++ private void createQuantizedIndex(Directory dir, List<float[]> vectors) throws IOException {+ IndexWriterConfig cfg = newIndexWriterConfig();+ cfg.setCodec(+ new Lucene101Codec() {+ @Override+ public KnnVectorsFormat getKnnVectorsFormatForField(String field) {+ return new Lucene99HnswScalarQuantizedVectorsFormat(8, 32);+ }+ });+ try (IndexWriter writer = new IndexWriter(dir, cfg)) {+ int i = 0;+ for (float[] vector : vectors) {+ Document doc = new Document();+ doc.add(new KnnFloatVectorField(FIELD_NAME, vector));+ doc.add(new StoredField("id", i++));+ writer.addDocument(doc);+ }+ }+ }++ public void testRandom() {+ List<float[]> points = new ArrayList<>();+ // This test may fail for small N; 100 seems big enough for the law of large numbers to make it+ // work w/very high probability+ for (int i = 0; i < 100; i++) {+ points.add(new float[] {random().nextFloat(), random().nextFloat(), random().nextFloat()});+ }+ double closestDistanceSum = sumClosestDistances(points);+ // run one iter so we can see what it did+ reorderer.setMaxIters(1);+ Sorter.DocMap map =+ reorderer.computeValueMap(+ FloatVectorValues.fromFloats(points, 3), VectorSimilarityFunction.EUCLIDEAN, null);+ List<float[]> reordered = new ArrayList<>();+ for (int i = 0; i < points.size(); i++) {+ reordered.add(points.get(map.newToOld(i)));+ }+ double reorderedClosestDistanceSum = sumClosestDistances(reordered);+ assertTrue(+ reorderedClosestDistanceSum + ">" + closestDistanceSum,+ reorderedClosestDistanceSum <= closestDistanceSum);+ }++ // Compute the sum of (for each point, the absolute difference between its ordinal and the ordinal+ // of its closest neighbor in Euclidean space) as a measure of whether the reordering successfully+ // brought vector-space neighbors closer together in ordinal space.+ private static double sumClosestDistances(List<float[]> points) {+ int sum = 0;+ for (int i = 0; i < points.size(); i++) {+ int closest = -1;+ double closeness = Double.MAX_VALUE;+ for (int j = 0; j < points.size(); j++) {+ if (j == i) {+ continue;+ }+ double distance = VectorUtil.squareDistance(points.get(i), points.get(j));+ if (distance < closeness) {+ closest = j;+ closeness = distance;+ }+ }+ sum += Math.abs(closest - i);+ }+ return sum;+ }++ public void testEuclideanLinear() {+ doTestEuclideanLinear(null);+ }++ public void testQuantizedIndex() throws Exception {+ doTestQuantizedIndex(null);+ }++ public void testEuclideanLinearConcurrent() {+ int concurrency = random().nextInt(7) + 1;+ // The default ForkJoinPool implementation uses a thread factory that removes all permissions on+ // threads, so we need to create our own to avoid tests failing with FS-based directories.+ ForkJoinPool pool =+ new ForkJoinPool(+ concurrency, p -> new ForkJoinWorkerThread(p) {}, null, random().nextBoolean());+ try {+ doTestEuclideanLinear(pool);+ } finally {+ pool.shutdown();+ }+ }++ private void doTestEuclideanLinear(Executor executor) {+ // a set of 2d points on a line+ List<float[]> vectors = randomLinearVectors();+ List<float[]> shuffled = shuffleVectors(vectors);+ TaskExecutor taskExecutor = getTaskExecutor(executor);+ Sorter.DocMap map =+ reorderer.computeValueMap(+ FloatVectorValues.fromFloats(shuffled, 2),+ VectorSimilarityFunction.EUCLIDEAN,+ taskExecutor);+ verifyEuclideanLinear(map, vectors, shuffled);+ }++ private static TaskExecutor getTaskExecutor(Executor executor) {+ TaskExecutor taskExecutor;+ if (executor != null) {+ taskExecutor = new TaskExecutor(executor);+ } else {+ taskExecutor = null;+ }+ return taskExecutor;+ }++ private void doTestQuantizedIndex(Executor executor) throws IOException {+ // a set of 2d points on a line+ List<float[]> vectors = randomLinearVectors();+ List<float[]> shuffled = shuffleVectors(vectors);+ try (Directory dir = newDirectory()) {+ createQuantizedIndex(dir, shuffled);+ reorderer.reorderIndexDirectory(dir, executor);+ int[] newToOld = new int[vectors.size()];+ int[] oldToNew = new int[vectors.size()];+ try (IndexReader reader = DirectoryReader.open(dir)) {+ LeafReader leafReader = getOnlyLeafReader(reader);+ for (int docid = 0; docid < reader.maxDoc(); docid++) {+ if (leafReader.getLiveDocs() == null || leafReader.getLiveDocs().get(docid)) {+ int oldid = Integer.parseInt(leafReader.storedFields().document(docid).get("id"));+ newToOld[docid] = oldid;+ oldToNew[oldid] = docid;+ } else {+ newToOld[docid] = -1;+ }+ }+ }+ verifyEuclideanLinear(+ new Sorter.DocMap() {+ @Override+ public int oldToNew(int docID) {+ return oldToNew[docID];+ }++ @Override+ public int newToOld(int docID) {+ return newToOld[docID];+ }++ @Override+ public int size() {+ return newToOld.length;+ }+ },+ vectors,+ shuffled);+ }+ }++ private static List<float[]> shuffleVectors(List<float[]> vectors) {+ List<float[]> shuffled = new ArrayList<>(vectors);+ Collections.shuffle(shuffled, random());+ return shuffled;+ }++ private static List<float[]> randomLinearVectors() {+ int n = random().nextInt(100) + 10;+ List<float[]> vectors = new ArrayList<>();+ float b = random().nextFloat();+ float m = random().nextFloat();+ float x = random().nextFloat();+ for (int i = 0; i < n; i++) {+ vectors.add(new float[] {x, m * x + b});+ x += random().nextFloat();+ }+ return vectors;+ }++ private static void verifyEuclideanLinear(+ Sorter.DocMap map, List<float[]> vectors, List<float[]> shuffled) {+ int count = shuffled.size();+ assertEquals(count, map.size());+ float[] midPoint = vectors.get(count / 2);+ float[] first = shuffled.get(map.newToOld(0));+ boolean lowFirst = first[0] < midPoint[0];+ for (int i = 0; i < count; i++) {+ int oldIndex = map.newToOld(i);+ assertEquals(i, map.oldToNew(oldIndex));+ // check the "new" order+ float[] v = shuffled.get(oldIndex);+ // first the low vectors, then the high ones, or the other way. Within any given block the+ // partitioning is kind of arbitrary -+ // we don't get a global ordering+ if (i < count / 2 == lowFirst) {+ assertTrue("out of order at " + i, v[0] <= midPoint[0] && v[1] <= midPoint[1]);+ } else {+ assertTrue("out of order at " + i, v[0] >= midPoint[0] && v[1] >= midPoint[1]);+ }+ }+ }++ public void testDotProductCircular() {+ doTestDotProductCircular(null);+ }++ public void testDotProductConcurrent() {+ int concurrency = random().nextInt(7) + 1;+ // The default ForkJoinPool implementation uses a thread factory that removes all permissions on+ // threads, so we need to create our own to avoid tests failing with FS-based directories.+ ForkJoinPool pool =+ new ForkJoinPool(+ concurrency, p -> new ForkJoinWorkerThread(p) {}, null, random().nextBoolean());+ try {+ doTestDotProductCircular(new TaskExecutor(pool));+ } finally {+ pool.shutdown();+ }+ }++ public void doTestDotProductCircular(TaskExecutor executor) {+ // a set of 2d points on a line+ int n = random().nextInt(100) + 10;+ List<float[]> vectors = new ArrayList<>();+ double t = random().nextDouble();+ for (int i = 0; i < n; i++) {+ vectors.add(new float[] {(float) Math.cos(t), (float) Math.sin(t)});+ t += random().nextDouble();+ }+ Sorter.DocMap map =+ reorderer.computeValueMap(+ FloatVectorValues.fromFloats(vectors, 2),+ VectorSimilarityFunction.DOT_PRODUCT,+ executor);+ assertEquals(n, map.size());+ double t0min = 2 * Math.PI, t0max = 0;+ double t1min = 2 * Math.PI, t1max = 0;+ // find the range of the lower half and the range of the upper half+ // they should be non-overlapping+ for (int i = 0; i < n; i++) {+ int oldIndex = map.newToOld(i);+ assertEquals(i, map.oldToNew(oldIndex));+ // check the "new" order+ float[] v = vectors.get(oldIndex);+ t = angle2pi(Math.atan2(v[1], v[0]));+ if (i < n / 2) {+ t0min = Math.min(t0min, t);+ t0max = Math.max(t0max, t);+ } else {+ t1min = Math.min(t1min, t);+ t1max = Math.max(t1max, t);+ }+ }+ assertTrue(+ "ranges overlap",+ (angularDifference(t0min, t0max) < angularDifference(t0min, t1min)+ && angularDifference(t0min, t0max) < angularDifference(t0min, t1max))+ || (angularDifference(t1min, t1max) < angularDifference(t1min, t0min)+ && angularDifference(t1min, t1max) < angularDifference(t1min, t0max)));+ }++ public void testIndexReorderDense() throws Exception {+ List<float[]> vectors = shuffleVectors(randomLinearVectors());+ // compute the expected ordering+ Sorter.DocMap expected =+ reorderer.computeValueMap(+ FloatVectorValues.fromFloats(vectors, 2), VectorSimilarityFunction.EUCLIDEAN, null);+ Path tmpdir = createTempDir();+ try (Directory dir = newFSDirectory(tmpdir)) {+ // create an index with a single leaf+ try (IndexWriter writer = new IndexWriter(dir, newIndexWriterConfig())) {+ int id = 0;+ for (float[] vector : vectors) {+ Document doc = new Document();+ doc.add(new KnnFloatVectorField("f", vector, VectorSimilarityFunction.EUCLIDEAN));+ doc.add(new StoredField("id", id++));+ writer.addDocument(doc);+ }+ writer.forceMerge(1);+ }+ int threadCount = random().nextInt(4) + 1;+ threadCount = 1;+ // reorder using the index reordering tool+ BpVectorReorderer.main(+ tmpdir.toString(),+ "f",+ "--min-partition-size",+ "1",+ "--max-iters",+ "10",+ "--thread-count",+ Integer.toString(threadCount));+ // verify the ordering is the same+ try (IndexReader reader = DirectoryReader.open(dir)) {+ LeafReader leafReader = getOnlyLeafReader(reader);+ FloatVectorValues values = leafReader.getFloatVectorValues("f");+ int newId = 0;+ StoredFields storedFields = reader.storedFields();+ KnnVectorValues.DocIndexIterator it = values.iterator();+ while (it.nextDoc() != DocIdSetIterator.NO_MORE_DOCS) {+ int storedId = Integer.parseInt(storedFields.document(it.docID()).get("id"));+ assertEquals(expected.oldToNew(storedId), newId);+ float[] expectedVector = vectors.get(expected.newToOld(it.docID()));+ float[] actualVector = values.vectorValue(it.index());+ assertArrayEquals(+ "values differ at index " + storedId + "->" + newId + " docid=" + it.docID(),+ expectedVector,+ actualVector,+ 0);+ newId++;+ }+ }+ }+ }++ public void testIndexReorderSparse() throws Exception {+ List<float[]> vectors = shuffleVectors(randomLinearVectors());+ // compute the expected ordering+ Sorter.DocMap expected =+ reorderer.computeValueMap(+ FloatVectorValues.fromFloats(vectors, 2), VectorSimilarityFunction.EUCLIDEAN, null);+ Path tmpdir = createTempDir();+ int maxDoc = 0;+ try (Directory dir = newFSDirectory(tmpdir)) {+ // create an index with a single leaf+ try (IndexWriter writer = new IndexWriter(dir, newIndexWriterConfig())) {+ for (float[] vector : vectors) {+ Document doc = new Document();+ if (random().nextBoolean()) {+ for (int i = 0; i < random().nextInt(3); i++) {+ // insert some gaps -- docs with no vectors+ writer.addDocument(doc);+ maxDoc++;+ }+ }+ doc.add(new KnnFloatVectorField("f", vector, VectorSimilarityFunction.EUCLIDEAN));+ writer.addDocument(doc);+ maxDoc++;+ }+ writer.forceMerge(1);+ }+ // reorder using the index reordering tool+ BpVectorReorderer.main(+ tmpdir.toString(), "f", "--min-partition-size", "1", "--max-iters", "10");+ // verify the ordering is the same+ try (IndexReader reader = DirectoryReader.open(dir)) {+ LeafReader leafReader = getOnlyLeafReader(reader);+ assertEquals(maxDoc, leafReader.maxDoc());+ FloatVectorValues values = leafReader.getFloatVectorValues("f");+ int lastDocID = 0;+ KnnVectorValues.DocIndexIterator it = values.iterator();+ while (it.nextDoc() != DocIdSetIterator.NO_MORE_DOCS) {+ lastDocID = it.docID();+ float[] expectedVector = vectors.get(expected.newToOld(lastDocID));+ float[] actualVector = values.vectorValue(it.index());+ assertArrayEquals(expectedVector, actualVector, 0);+ }+ // docs with no vectors sort at the end+ assertEquals(vectors.size() - 1, lastDocID);+ }+ }+ }++ static double angularDifference(double a, double b) {+ return angle2pi(b - a);+ }++ static double angle2pi(double a) {+ while (a > 2 * Math.PI) {+ a -= 2 * Math.PI;+ }+ while (a < 0) {+ a += 2 * Math.PI;+ }+ return a;+ }+}diff --git a/lucene/test-framework/src/java/org/apache/lucene/tests/codecs/asserting/AssertingKnnVectorsFormat.java b/lucene/test-framework/src/java/org/apache/lucene/tests/codecs/asserting/AssertingKnnVectorsFormat.javaindex bd2911fc50a..22fa438b04b 100644--- a/lucene/test-framework/src/java/org/apache/lucene/tests/codecs/asserting/AssertingKnnVectorsFormat.java+++ b/lucene/test-framework/src/java/org/apache/lucene/tests/codecs/asserting/AssertingKnnVectorsFormat.java@@ -223,7 +223,11 @@ public class AssertingKnnVectorsFormat extends KnnVectorsFormat {@Overridepublic HnswGraph getGraph(String field) throws IOException {- return ((HnswGraphProvider) delegate).getGraph(field);+ if (delegate instanceof HnswGraphProvider) {+ return ((HnswGraphProvider) delegate).getGraph(field);+ } else {+ return null;+ }}}}