### Optimize Memory Usage with Chunk Size Tuning

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Provides examples of adjusting chunk sizes for data and centroids to manage memory consumption when processing massive datasets on limited hardware.

```python
import numpy as np
from fastkmeans import FastKMeans

# Large-scale clustering: 26M points into 262K clusters (~11GB memory)
large_data = np.random.randn(26_214_400, 128).astype(np.float32)

# Default chunk sizes for ~11GB memory usage
kmeans_default = FastKMeans(
    d=128,
    k=262_144,
    chunk_size_data=51_200,
    chunk_size_centroids=10_240,
    max_points_per_centroid=256,
    verbose=True
)

# Reduced memory usage (slower)
kmeans_low_memory = FastKMeans(
    d=128,
    k=262_144,
    chunk_size_data=25_600,
    chunk_size_centroids=5_120,
    verbose=True
)

# Higher memory/faster (if GPU has >16GB)
kmeans_high_memory = FastKMeans(
    d=128,
    k=262_144,
    chunk_size_data=102_400,
    chunk_size_centroids=20_480,
    verbose=True
)
```

--------------------------------

### ColBERT-Style Document Indexing

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Example demonstrating the primary use case of creating cluster centroids for ColBERT-style late-interaction retrieval systems with a large number of clusters.

```APIDOC
## ColBERT-Style Document Indexing Example

### Description
This example demonstrates the primary use case: creating cluster centroids for ColBERT-style late-interaction retrieval systems with large numbers of clusters.

### Method
`train`, `predict`

### Endpoint
N/A (This is a method within the `FastKMeans` class)

### Parameters
Parameters are set during `FastKMeans` initialization. Key parameters for this use case include `d`, `k`, `niter`, `max_points_per_centroid`, and `gpu`.

### Request Example
```python
import numpy as np
from fastkmeans import FastKMeans

# Simulate ColBERT embeddings: documents with multiple token embeddings
# 10,000 documents × 128 tokens × 128 dimensions
num_documents = 10_000
tokens_per_doc = 128
embedding_dim = 128

# Flatten all token embeddings for clustering
all_embeddings = np.random.randn(
    num_documents * tokens_per_doc, embedding_dim
).astype(np.float32)

print(f"Total embeddings: {len(all_embeddings):,}")  # 1,280,000 embeddings

# ColBERT typically uses ~100 points per centroid
num_clusters = len(all_embeddings) // 100  # ~12,800 clusters

# Train k-means with Triton acceleration
kmeans = FastKMeans(
    d=embedding_dim,
    k=num_clusters,
    niter=25,
    max_points_per_centroid=256,  # FAISS default subsampling
    gpu=True,
    verbose=True
)
kmeans.train(all_embeddings)

# Get cluster assignments for building the inverted index
cluster_ids = kmeans.predict(all_embeddings)

print(f"Centroids shape: {kmeans.centroids.shape}")
print(f"Cluster assignments: {cluster_ids.shape}")
```

### Response
#### Success Response (200)
- **centroids** (numpy.ndarray) - The computed cluster centroids.
- **cluster_ids** (numpy.ndarray) - An array containing the cluster index for each embedding.
```

--------------------------------

### Configure Device Selection and CPU Execution

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Illustrates how to force CPU execution, select specific GPU devices, or utilize alternative hardware backends like Apple Silicon (MPS) and Intel XPU.

```python
import numpy as np
from fastkmeans import FastKMeans

data = np.random.randn(20_000, 64).astype(np.float32)

# Force CPU execution
kmeans_cpu = FastKMeans(d=64, k=256, gpu=False, niter=15)
kmeans_cpu.fit(data)

# Explicit device selection for multi-GPU
kmeans_gpu1 = FastKMeans(d=64, k=256, device="cuda:1", niter=15)
kmeans_gpu1.fit(data)

# Use MPS on Apple Silicon (auto-detected when gpu=True)
kmeans_mps = FastKMeans(d=64, k=256, device="mps", niter=15)

# Use Intel XPU
kmeans_xpu = FastKMeans(d=64, k=256, device="xpu:0", niter=15)
```

--------------------------------

### Initialize FastKMeans Clustering

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Demonstrates the initialization of the FastKMeans class with various parameters for dimensionality, number of clusters, iterations, and memory tuning. It shows both basic and advanced configurations, including GPU usage and Triton backend auto-detection.

```python
import numpy as np
from fastkmeans import FastKMeans

# Basic initialization with 128-dimensional data and 1024 clusters
kmeans = FastKMeans(
    d=128,           # Dimensionality of input features
    k=1024,          # Number of clusters
    niter=25,        # Maximum iterations (default: 25)
    tol=1e-8,        # Early stopping tolerance (default: 1e-8)
    gpu=True,        # Use GPU if available (default: True)
    seed=42,         # Random seed for reproducibility
    verbose=True     # Print iteration progress
)

# Advanced initialization with memory tuning
kmeans_advanced = FastKMeans(
    d=128,
    k=65536,                        # Large number of clusters
    niter=30,
    tol=1e-6,
    max_points_per_centroid=256,    # Subsample data if exceeds k * 256 points
    chunk_size_data=51_200,         # Chunk size for data (increase for speed, decrease for memory)
    chunk_size_centroids=10_240,    # Chunk size for centroids
    device="cuda:0",                # Explicit device selection
    dtype=None,                     # Auto-select dtype (fp16 on GPU, fp32 on CPU)
    pin_gpu_memory=True,            # Pin memory for faster GPU transfers
    use_triton=None                 # Auto-enable Triton on supported GPUs
)
```

--------------------------------

### CPU-Only and Device Selection

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Demonstrates how to force CPU execution, explicitly select GPUs for multi-GPU systems, and utilize MPS on Apple Silicon or Intel XPU.

```APIDOC
## CPU-Only and Device Selection

### Description
For systems without GPU or when GPU memory is constrained, fastkmeans works efficiently on CPU. You can also explicitly select devices for multi-GPU systems.

### Method
`fit` (or `train`)

### Endpoint
N/A (This is a method within the `FastKMeans` class)

### Parameters
- **gpu** (bool) - Set to `False` to force CPU execution.
- **device** (str) - Explicitly specify the device to use (e.g., "cuda:1", "mps", "xpu:0"). If `gpu=True` and `device` is not specified, it will attempt to use the default GPU.

### Request Example
```python
import numpy as np
from fastkmeans import FastKMeans

data = np.random.randn(20_000, 64).astype(np.float32)

# Force CPU execution
kmeans_cpu = FastKMeans(d=64, k=256, gpu=False, niter=15)
kmeans_cpu.fit(data)

# Explicit device selection for multi-GPU
kmeans_gpu1 = FastKMeans(d=64, k=256, device="cuda:1", niter=15)
kmeans_gpu1.fit(data)

# Use MPS on Apple Silicon (auto-detected when gpu=True)
kmeans_mps = FastKMeans(d=64, k=256, device="mps", niter=15)

# Use Intel XPU
kmeans_xpu = FastKMeans(d=64, k=256, device="xpu:0", niter=15)
```

### Response
#### Success Response (200)
- The `fit` method modifies the `FastKMeans` object in-place, training the model.
```

--------------------------------

### Control Convergence and Iteration Limits

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Shows how to configure early stopping using the tolerance parameter or force a fixed number of iterations for deterministic training behavior.

```python
import numpy as np
from fastkmeans import FastKMeans

data = np.random.randn(50_000, 128).astype(np.float32)

# Default: early stopping when centroids move less than tol
kmeans_early_stop = FastKMeans(
    d=128, k=1000,
    niter=50,
    tol=1e-8,
    verbose=True
)
kmeans_early_stop.fit(data)

# FAISS-style: run exactly niter iterations, no early stopping
kmeans_fixed_iter = FastKMeans(
    d=128, k=1000,
    niter=25,
    tol=-1,
    verbose=True
)
kmeans_fixed_iter.fit(data)

# Loose tolerance for faster convergence
kmeans_fast = FastKMeans(
    d=128, k=1000,
    niter=100,
    tol=1e-4,
    verbose=True
)
kmeans_fast.fit(data)
```

--------------------------------

### Fit FastKMeans Model (Scikit-Learn API)

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Demonstrates the `fit()` method, which is an alias for `train()` and returns `self`, ensuring compatibility with scikit-learn's API and enabling method chaining within scikit-learn pipelines.

```python
import numpy as np
from fastkmeans import FastKMeans

# Generate sample data
data = np.random.randn(50_000, 64).astype(np.float32)

# Scikit-learn style: fit returns self for method chaining
kmeans = FastKMeans(d=64, k=512, niter=20, gpu=True)
kmeans.fit(data)

# Centroids are available after fitting
print(f"Number of clusters: {len(kmeans.centroids)}")  # Output: 512
```

--------------------------------

### Train FastKMeans Model (FAISS API)

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Shows how to train the k-means model using the `train()` method, which is compatible with the FAISS API. The method takes a numpy array as input and stores the computed centroids in `self.centroids`.

```python
import numpy as np
from fastkmeans import FastKMeans

# Generate sample data: 100,000 points with 128 dimensions
np.random.seed(42)
data = np.random.randn(100_000, 128).astype(np.float32)

# Initialize and train (FAISS-style API)
kmeans = FastKMeans(d=128, k=1024, niter=25, seed=0, verbose=True)
kmeans.train(data)

# Access the trained centroids
print(f"Centroids shape: {kmeans.centroids.shape}")  # Output: (1024, 128)
print(f"Centroid dtype: {kmeans.centroids.dtype}")   # Output: float32
```

--------------------------------

### Controlling Convergence and Iterations

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Configure early stopping using the `tol` parameter or run for a fixed number of iterations by setting `tol=-1`, similar to FAISS.

```APIDOC
## Controlling Convergence and Iterations

### Description
Configure early stopping with the `tol` parameter or run for a fixed number of iterations like FAISS by setting `tol=-1`.

### Method
`fit` (or `train`)

### Endpoint
N/A (This is a method within the `FastKMeans` class)

### Parameters
- **niter** (int) - The maximum number of iterations to perform.
- **tol** (float) - The tolerance for early stopping. If the centroids move less than this value between iterations, the algorithm stops. Set to `-1` to disable early stopping and run for exactly `niter` iterations.

### Request Example
```python
import numpy as np
from fastkmeans import FastKMeans

data = np.random.randn(50_000, 128).astype(np.float32)

# Default: early stopping when centroids move less than tol
kmeans_early_stop = FastKMeans(
    d=128, k=1000,
    niter=50,          # Max iterations
    tol=1e-8,          # Stop when centroid shift < 1e-8
    verbose=True
)
kmeans_early_stop.fit(data)

# FAISS-style: run exactly niter iterations, no early stopping
kmeans_fixed_iter = FastKMeans(
    d=128, k=1000,
    niter=25,
    tol=-1,            # Disable early stopping
    verbose=True
)
kmeans_fixed_iter.fit(data)

# Loose tolerance for faster convergence
kmeans_fast = FastKMeans(
    d=128, k=1000,
    niter=100,
    tol=1e-4,          # Stop earlier with loose tolerance
    verbose=True
)
kmeans_fast.fit(data)
```

### Response
#### Success Response (200)
- The `fit` or `train` methods modify the `FastKMeans` object in-place, training the model according to the specified convergence criteria.
```

--------------------------------

### Perform Combined Training and Assignment with fit_predict

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Demonstrates the fit_predict method which combines model training and cluster assignment in a single operation. This is ideal for scenarios where labels are required immediately after training.

```python
import numpy as np
from fastkmeans import FastKMeans

# Generate data for clustering
data = np.random.randn(50_000, 256).astype(np.float32)

# Single call to fit and predict
kmeans = FastKMeans(d=256, k=1000, niter=30, tol=1e-6, seed=123)
labels = kmeans.fit_predict(data)

# Analyze cluster distribution
unique, counts = np.unique(labels, return_counts=True)
print(f"Total clusters: {len(unique)}")
print(f"Min cluster size: {counts.min()}")
print(f"Max cluster size: {counts.max()}")
print(f"Mean cluster size: {counts.mean():.1f}")
```

--------------------------------

### Implement ColBERT-Style Document Indexing

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Shows how to cluster large volumes of token embeddings for late-interaction retrieval systems. It utilizes GPU acceleration and subsampling to handle millions of embeddings efficiently.

```python
import numpy as np
from fastkmeans import FastKMeans

# Simulate ColBERT embeddings: documents with multiple token embeddings
# 10,000 documents × 128 tokens × 128 dimensions
num_documents = 10_000
tokens_per_doc = 128
embedding_dim = 128

# Flatten all token embeddings for clustering
all_embeddings = np.random.randn(
    num_documents * tokens_per_doc, embedding_dim
).astype(np.float32)

print(f"Total embeddings: {len(all_embeddings):,}")

# ColBERT typically uses ~100 points per centroid
num_clusters = len(all_embeddings) // 100

# Train k-means with Triton acceleration
kmeans = FastKMeans(
    d=embedding_dim,
    k=num_clusters,
    niter=25,
    max_points_per_centroid=256,
    gpu=True,
    verbose=True
)
kmeans.train(all_embeddings)

# Get cluster assignments for building the inverted index
cluster_ids = kmeans.predict(all_embeddings)

print(f"Centroids shape: {kmeans.centroids.shape}")
print(f"Cluster assignments: {cluster_ids.shape}")
```

--------------------------------

### Disable Data Subsampling in FastKMeans

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

This snippet demonstrates how to initialize FastKMeans with default subsampling versus disabling it entirely. By setting max_points_per_centroid to None, the model uses the entire input dataset for training.

```python
import numpy as np
from fastkmeans import FastKMeans

data = np.random.randn(100_000, 128).astype(np.float32)

# Default: subsamples to k * 256 points
kmeans_subsampled = FastKMeans(
    d=128, k=100,
    max_points_per_centroid=256,  # Will use 25,600 points
    verbose=True
)
kmeans_subsampled.fit(data)

# Disable subsampling: use all data points
kmeans_full = FastKMeans(
    d=128, k=100,
    max_points_per_centroid=None,  # Use all 100,000 points
    verbose=True
)
kmeans_full.fit(data)
```

--------------------------------

### Memory Optimization with Chunk Size Tuning

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Adjust chunk sizes for `chunk_size_data` and `chunk_size_centroids` to balance speed and memory usage, especially for large datasets or limited GPU memory.

```APIDOC
## Memory Optimization with Chunk Size Tuning

### Description
For very large datasets or limited GPU memory, adjust chunk sizes to balance speed and memory usage. Smaller chunks use less memory but run slower.

### Method
`fit` (or `train`)

### Endpoint
N/A (This is a method within the `FastKMeans` class)

### Parameters
- **chunk_size_data** (int) - The number of data points to process in each chunk during training. Smaller values reduce memory usage.
- **chunk_size_centroids** (int) - The number of centroids to process in each chunk. Smaller values reduce memory usage.

### Request Example
```python
import numpy as np
from fastkmeans import FastKMeans

# Large-scale clustering: 26M points into 262K clusters (~11GB memory)
large_data = np.random.randn(26_214_400, 128).astype(np.float32)

# Default chunk sizes for ~11GB memory usage
kmeans_default = FastKMeans(
    d=128,
    k=262_144,
    chunk_size_data=51_200,       # Process 51K data points at a time
    chunk_size_centroids=10_240,  # Process 10K centroids at a time
    max_points_per_centroid=256,  # Subsample to 67M points max
    verbose=True
)

# Reduced memory usage (slower)
kmeans_low_memory = FastKMeans(
    d=128,
    k=262_144,
    chunk_size_data=25_600,       # Halve data chunk size
    chunk_size_centroids=5_120,   # Halve centroid chunk size
    verbose=True
)

# Higher memory/faster (if GPU has >16GB)
kmeans_high_memory = FastKMeans(
    d=128,
    k=262_144,
    chunk_size_data=102_400,      # Double data chunk size
    chunk_size_centroids=20_480,  # Double centroid chunk size
    verbose=True
)
```

### Response
#### Success Response (200)
- The `fit` or `train` methods modify the `FastKMeans` object in-place, training the model with the specified chunk sizes.
```

--------------------------------

### fit_predict() Method

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Combines model training and cluster assignment for the same dataset in a single operation. Useful for obtaining labels for the training data.

```APIDOC
## fit_predict() Method - Combined Training and Assignment

### Description
The `fit_predict()` method chains `fit()` and `predict()` in a single call, training the model and returning cluster assignments for the same data. This is useful when you need labels for your training data.

### Method
`fit_predict`

### Endpoint
N/A (This is a method within the `FastKMeans` class)

### Parameters
None directly for `fit_predict`, parameters are set during `FastKMeans` initialization.

### Request Example
```python
import numpy as np
from fastkmeans import FastKMeans

# Generate data for clustering
data = np.random.randn(50_000, 256).astype(np.float32)

# Single call to fit and predict
kmeans = FastKMeans(d=256, k=1000, niter=30, tol=1e-6, seed=123)
labels = kmeans.fit_predict(data)

# Analyze cluster distribution
unique, counts = np.unique(labels, return_counts=True)
print(f"Total clusters: {len(unique)}")
print(f"Min cluster size: {counts.min()}")
print(f"Max cluster size: {counts.max()}")
print(f"Mean cluster size: {counts.mean():.1f}")
```

### Response
#### Success Response (200)
- **labels** (numpy.ndarray) - An array containing the cluster index for each data point.
```

--------------------------------

### Predict Cluster Assignments

Source: https://context7.com/answerdotai/fastkmeans/llms.txt

Illustrates the `predict()` method for assigning data points to the nearest centroid after the model has been trained. It returns cluster labels as a numpy array of int64 indices and utilizes chunked processing for memory efficiency.

```python
import numpy as np
from fastkmeans import FastKMeans

# Training data
train_data = np.random.randn(100_000, 128).astype(np.float32)

# Initialize and train
kmeans = FastKMeans(d=128, k=2048, niter=25, seed=42)
kmeans.fit(train_data)

# Predict on new data
new_data = np.random.randn(10_000, 128).astype(np.float32)
labels = kmeans.predict(new_data)

print(f"Labels shape: {labels.shape}")        # Output: (10000,)
print(f"Labels dtype: {labels.dtype}")        # Output: int64
print(f"Unique clusters used: {len(np.unique(labels))}")
print(f"Sample labels: {labels[:10]}")        # Cluster indices 0 to 2047
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.