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