From 1c655823dd85664b93a01c7ef3bd65fe094745fd Mon Sep 17 00:00:00 2001
From: Pulkit Gupta <36265543+Pulkitg64@users.noreply.github.com>
Date: Tue, 11 Jun 2024 23:19:21 +0530
Subject: [PATCH] Mark COSINE VectorSimilarity function as deprecated (#13473)

---
 lucene/CHANGES.txt                                       | 3 ++-
 .../apache/lucene/index/VectorSimilarityFunction.java    | 3 +++
 .../core/src/java/org/apache/lucene/util/VectorUtil.java | 9 ++++++++-
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
index ea880f2e6c4..8dd40060450 100644
--- a/lucene/CHANGES.txt
+++ b/lucene/CHANGES.txt
@@ -243,7 +243,8 @@ Other
 
 API Changes
 ---------------------
-(No changes)
+
+* GITHUB#13281: Mark COSINE VectorSimilarityFunction as deprecated. (Pulkit Gupta)
 
 New Features
 ---------------------
diff --git a/lucene/core/src/java/org/apache/lucene/index/VectorSimilarityFunction.java b/lucene/core/src/java/org/apache/lucene/index/VectorSimilarityFunction.java
index 23bd0fd0ec6..b625f0740a5 100644
--- a/lucene/core/src/java/org/apache/lucene/index/VectorSimilarityFunction.java
+++ b/lucene/core/src/java/org/apache/lucene/index/VectorSimilarityFunction.java
@@ -66,7 +66,10 @@ public enum VectorSimilarityFunction {
    * vectors to unit length, and instead use {@link VectorSimilarityFunction#DOT_PRODUCT}. You
    * should only use this function if you need to preserve the original vectors and cannot normalize
    * them in advance. The similarity score is normalised to assure it is positive.
+   *
+   * @deprecated Use MAXIMUM_INNER_PRODUCT or DOT_PRODUCT instead
    */
+  @Deprecated
   COSINE {
     @Override
     public float compare(float[] v1, float[] v2) {
diff --git a/lucene/core/src/java/org/apache/lucene/util/VectorUtil.java b/lucene/core/src/java/org/apache/lucene/util/VectorUtil.java
index a9acca64d69..43e5077695c 100644
--- a/lucene/core/src/java/org/apache/lucene/util/VectorUtil.java
+++ b/lucene/core/src/java/org/apache/lucene/util/VectorUtil.java
@@ -70,7 +70,9 @@ public final class VectorUtil {
    * Returns the cosine similarity between the two vectors.
    *
    * @throws IllegalArgumentException if the vectors' dimensions differ.
+   * @deprecated use dot-product instead using normalized vectors
    */
+  @Deprecated
   public static float cosine(float[] a, float[] b) {
     if (a.length != b.length) {
       throw new IllegalArgumentException("vector dimensions differ: " + a.length + "!=" + b.length);
@@ -80,7 +82,12 @@ public final class VectorUtil {
     return r;
   }
 
-  /** Returns the cosine similarity between the two vectors. */
+  /**
+   * Returns the cosine similarity between the two vectors.
+   *
+   * @deprecated use dot-product instead using normalized vectors
+   */
+  @Deprecated
   public static float cosine(byte[] a, byte[] b) {
     if (a.length != b.length) {
       throw new IllegalArgumentException("vector dimensions differ: " + a.length + "!=" + b.length);