code complete

Author: normen662

fdb-extensions/src/main/java/com/apple/foundationdb/async/rabitq/RaBitQuantizer.java

@@ -74,6 +74,10 @@ public final class RaBitQuantizer implements Quantizer {
      */
     public RaBitQuantizer(@Nonnull final Metric metric, final int numExBits) {
         Preconditions.checkArgument(numExBits > 0 && numExBits < TIGHT_START.length);
+        Preconditions.checkArgument(
+                metric == Metric.EUCLIDEAN_METRIC ||
+                        metric == Metric.EUCLIDEAN_SQUARE_METRIC ||
+                        metric == Metric.DOT_PRODUCT_METRIC);
 
         this.numExBits = numExBits;
         this.metric = metric;
@@ -102,7 +106,8 @@ public RaBitEstimator estimator() {
      * core encoding logic to an internal helper method and returns the final
      * {@link EncodedRealVector}.
      *
-     * @param data the {@link RealVector} to be encoded; must not be null.
+     * @param data the {@link RealVector} to be encoded; must not be null. The vector must be pre-rotated and
+     *        translated.
      *
      * @return the resulting {@link EncodedRealVector}, guaranteed to be non-null.
      */

fdb-extensions/src/main/java/com/apple/foundationdb/linear/Estimator.java

@@ -22,7 +22,25 @@
 
 import javax.annotation.Nonnull;
 
+/**
+ * Interface of an estimator used for calculating the distance between vectors.
+ * <p>
+ * Implementations of this interface are expected to provide a specific distance
+ * metric calculation, often used in search or similarity contexts where one
+ * vector (the query) is compared against many stored vectors.
+ */
 public interface Estimator {
+    /**
+     * Calculates the distance between a pre-rotated and translated query vector and a stored vector.
+     * <p>
+     * This method is designed to compute the distance metric between two vectors in a high-dimensional space. It is
+     * crucial that the {@code query} vector has already been appropriately transformed (e.g., rotated and translated)
+     * to align with the coordinate system of the {@code storedVector} before calling this method.
+     *
+     * @param query the pre-rotated and translated query vector, cannot be null.
+     * @param storedVector the stored vector to which the distance is calculated, cannot be null.
+     * @return a non-negative {@code double} representing the distance between the two vectors.
+     */
     double distance(@Nonnull RealVector query, // pre-rotated query q
                     @Nonnull RealVector storedVector);
 }

fdb-extensions/src/main/java/com/apple/foundationdb/linear/Quantizer.java

@@ -22,13 +22,52 @@
 
 import javax.annotation.Nonnull;
 
+/**
+ * Defines the contract for a quantizer, a component responsible for encoding data vectors into a different, ideally
+ * a more compact, representation.
+ * <p>
+ * Quantizers are typically used in machine learning and information retrieval to transform raw data into a format that
+ * is more suitable for processing, such as a compressed representation.
+ */
 public interface Quantizer {
+    /**
+     * Returns the {@code Estimator} instance associated with this object.
+     * <p>
+     * The estimator is responsible for performing the primary distance estimation or calculation logic. This method
+     * provides access to that underlying component.
+     *
+     * @return the {@link Estimator} instance, which is guaranteed to be non-null.
+     */
     @Nonnull
     Estimator estimator();
 
+    /**
+     * Encodes the given data vector into another vector representation.
+     * <p>
+     * This method transforms the raw input data into a different, quantized format, which is often a vector more
+     * suitable for processing/storing the data. The specifics of the encoding depend on the implementation of the class.
+     *
+     * @param data the input {@link RealVector} to be encoded. Must not be {@code null} and is assumed to have been
+     *        preprocessed, such as by rotation and/or translation. The preprocessing has to align with the requirements
+     *        of the specific quantizer.
+     * @return the encoded vector representation of the input data, guaranteed to be non-null.
+     */
     @Nonnull
     RealVector encode(@Nonnull RealVector data);
 
+    /**
+     * Creates a no-op {@code Quantizer} that does not perform any data transformation.
+     * <p>
+     * The returned quantizer's {@link Quantizer#encode(RealVector)} method acts as an
+     * identity function, returning the input vector without modification. The
+     * {@link Quantizer#estimator()} is created directly from the distance function
+     * of the provided {@link Metric}. This can be useful for baseline comparisons
+     * or for algorithms that require a {@code Quantizer} but where no quantization
+     * is desired.
+     *
+     * @param metric the {@link Metric} used to build the distance estimator for the quantizer.
+     * @return a new {@link Quantizer} instance that performs no operation.
+     */
     @Nonnull
     static Quantizer noOpQuantizer(@Nonnull final Metric metric) {
         return new Quantizer() {