KMeans (Lucene 10.5.1 sandbox API)
Description: declaration: package: org.apache.lucene.sandbox.codecs.quantization, class: KMeans

Package org.apache.lucene.sandbox.codecs.quantization

# Class KMeans

java.lang.Object
org.apache.lucene.sandbox.codecs.quantization.KMeans

public class KMeans extends Object
KMeans clustering algorithm for vectors

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `KMeans.KmeansInitializationMethod`
  Kmeans initialization methods
  `static final record`
  `KMeans.Results`
  Results of KMeans clustering

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_ITRS`
  `static final int`
  `DEFAULT_RESTARTS`
  `static final int`
  `DEFAULT_SAMPLE_SIZE`
  `static final int`
  `MAX_NUM_CENTROIDS`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static KMeans.Results`
  `cluster(FloatVectorValues vectors, int numClusters, boolean assignCentroidsToVectors, long seed, KMeans.KmeansInitializationMethod initializationMethod, boolean normalizeCenters, int restarts, int iters, int sampleSize)`
  Expert: Cluster vectors into a given number of clusters
  `static KMeans.Results`
  `cluster(FloatVectorValues vectors, VectorSimilarityFunction similarityFunction, int numClusters)`
  Cluster vectors into a given number of clusters

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### MAX_NUM_CENTROIDS

    public static final int MAX_NUM_CENTROIDS
    See Also:
      - Constant Field Values

  - ### DEFAULT_RESTARTS

    public static final int DEFAULT_RESTARTS
    See Also:
      - Constant Field Values

  - ### DEFAULT_ITRS

    public static final int DEFAULT_ITRS
    See Also:
      - Constant Field Values

  - ### DEFAULT_SAMPLE_SIZE

    public static final int DEFAULT_SAMPLE_SIZE
    See Also:
      - Constant Field Values

- ## Method Details

  - ### cluster

    public static KMeans.Results cluster(FloatVectorValues vectors, VectorSimilarityFunction similarityFunction, int numClusters) throws IOException
    Cluster vectors into a given number of clusters
    Parameters:
      `vectors` - float vectors
      `similarityFunction` - vector similarity function. For COSINE similarity, vectors must be normalized.
      `numClusters` - number of cluster to cluster vector into
    Returns:
      results of clustering: produced centroids and for each vector its centroid
    Throws:
      `IOException` - when if there is an error accessing vectors

  - ### cluster

    public static KMeans.Results cluster(FloatVectorValues vectors, int numClusters, boolean assignCentroidsToVectors, long seed, KMeans.KmeansInitializationMethod initializationMethod, boolean normalizeCenters, int restarts, int iters, int sampleSize) throws IOException
    Expert: Cluster vectors into a given number of clusters
    Parameters:
      `vectors` - float vectors
      `numClusters` - number of cluster to cluster vector into
      `assignCentroidsToVectors` - if `true` assign centroids for all vectors. Centroids are computed on a sample of vectors. If this parameter is `true`, in results also return for all vectors what centroids they belong to.
      `seed` - random seed
      `initializationMethod` - Kmeans initialization method
      `normalizeCenters` - for cosine distance, set to true, to use spherical k-means where centers are normalized
      `restarts` - how many times to run Kmeans algorithm
      `iters` - how many iterations to do within a single run
      `sampleSize` - sample size to select from all vectors on which to run Kmeans algorithm
    Returns:
      results of clustering: produced centroids and if `assignCentroidsToVectors == true` also for each vector its centroid
    Throws:
      `IOException` - if there is error accessing vectors