Alusus language bindings for the FAISS library - A library for efficient similarity search and clustering of dense vectors.
This library provides Alusus bindings to FAISS, enabling high-performance vector similarity search and clustering operations in the Alusus programming language.
import "Apm";
Apm.importPackage("Alusus/Faiss@0.1");
use Faiss;
import "Srl/Console";
import "Srl/Array";
import "Apm";
Apm.importPackage("Alusus/Faiss@0.1");
use Srl;
use Faiss;
// Create a flat index with 4-dimensional vectors
def index: ref[Index];
Index.new(index, 4, "Flat", MetricType.METRIC_INNER_PRODUCT);
// Add vectors to the index
def xb: Array[Float]({1.0, 2.0, 3.0, 4.0, 2.0, 3.0, 4.0, 5.0});
index.add(2, xb.buf); // 2 vectors
// Search for nearest neighbors
def xq: Array[Float]({1.5, 2.5, 3.5, 4.5});
def labels: array[Int[64], 3];
def distances: array[Float, 3];
index.search(1, xq.buf, 3, distances, labels); // Find 3 nearest neighbors
// Clean up
Index.free(index);
See complete examples in the Examples/ directory.
This library wraps the FAISS C API. For detailed documentation of concepts, algorithms, and best practices, please refer to the official FAISS documentation:
- Main Documentation: https://github.com/facebookresearch/faiss/wiki
- C API Reference: https://github.com/facebookresearch/faiss/blob/main/c_api/
- Getting Started Tutorial: https://github.com/facebookresearch/faiss/wiki/Getting-started
- Index Selection Guide: https://github.com/facebookresearch/faiss/wiki/Guidelines-to-choose-an-index
Main index class for similarity search. C API docs
Static methods:
func new(obj: ref[ref[Index]], d: Int, description: CharsPtr, metric: Int): Int
Create index using factory string.
func load(fname: CharsPtr, flags: Int, obj: ref[ref[Index]]): Int
Load index from a file.
func save(obj: ref[Index], fname: CharsPtr): Int
Save index to a file.
func free(obj: ref[Index])
Free index memory.
Key methods:
handler this.train(n: Int[64], x: ref[array[Float]]): Int
Train the index on data.
handler this.add(n: Int[64], x: ref[array[Float]]): Int
Add vectors to index.
handler this.search(n: Int[64], x: ref[array[Float]], k: Int[64], distances: ref[array[Float]], labels: ref[array[Int[64]]]): Int
Search for k nearest neighbors.
handler this.rangeSearch(n: Int[64], x: ref[array[Float]], radius: Float, result: ref[RangeSearchResult]): Int
Range search.
handler this.reset(): Int
Remove all vectors from index.
handler this.removeIds(sel: ref[IdSelector], nRemoved: ref[ArchWord]): Int
Remove specific vectors.
Properties:
d: Int[64];
Vector dimension.
nTotal: Int[64]
Total number of indexed vectors.
isTrained: Int
Whether index is trained (0 or 1).
metricType: MetricType
Distance metric being used.
verbose: Int
Verbosity level.
Brute-force index performing exact search. Guide
Creation:
func new(obj: ref[ref[IndexFlat]]): Int
func new(obj: ref[ref[IndexFlat]], d: Int[64], metric: MetricType): Int
Additional methods:
handler this.getXb(outXb: ref[ref[array[Float]]], outSize: ref[ArchWord])
Get stored vectors.
handler this.computeDistanceSubset(n: Int[64], x: ref[array[Float]], k: Int[64], outDistances: ref[array[Float]], labels: ref[array[Int[64]]]): Int
Compute distances to subset.
Inherits all Index methods.
Flat index specialized for inner product metric. Docs
Creation:
func new(obj: ref[ref[IndexFlatIp]]): Int
func new(obj: ref[ref[IndexFlatIp]], d: Int[64]): Int
Flat index specialized for L2 (Euclidean) distance. Docs
Creation:
func IndexFlatL2.new(obj: ref[ref[IndexFlatL2]]): Int
func IndexFlatL2.new(obj: ref[ref[IndexFlatL2]], d: Int[64]): Int
Inverted file index for faster approximate search. Guide
Additional properties:
nList: ArchWord
Number of inverted lists (clusters).
nProbe: ArchWord
Number of clusters to visit during search (tunable).
quantizer: ref[Index]
Quantizer index.
ownFields: Int
Whether index owns its fields.
Additional methods:
handler this.mergeFrom(other: ref[IndexIvf], addId: Int[64]): Int
Merge another IVF index.
handler this.copySubsetTo(other: ref[IndexIvf], subsetType: Int, a1: Int[64], a2: Int[64]): Int
Copy subset of vectors.
handler this.getListSize(listNo: ArchWord): ArchWord
Get size of inverted list.
handler this.makeDirectMap(newMaintainDirectMap: Int): Int
Create direct map for reconstruction.
handler this.imbalanceFactor: Float[64]
Get cluster imbalance factor.
handler this.printStats()
Print index statistics.
Index for binary (hamming) vectors. Guide
Similar to Index but operates on binary vectors (Word[8] arrays instead of Float arrays).
Support Classes
Manages index parameters for grid search and tuning. C API
Methods:
func new(parameterSpace: ref[ref[ParameterSpace]]): Int
handler this.setIndexParameter(index: ref[Index], paramName: CharsPtr, val: Float[64]): Int
Set single parameter.
handler this.setIndexParameters(index: ref[Index], params: CharsPtr): Int
Set multiple parameters.
handler this.addRange(name: CharsPtr, outRange: ref[ref[ParameterRange]]): Int
Add parameter range.
Runtime search parameters. C API
Methods:
func new(obj: ref[ref[SearchParameters]], sel: ref[IdSelector]): Int
Properties
nProbe: Int
Number of clusters to probe (for IVF indexes).
Extended search parameters for IVF indexes.
Methods:
func new(obj: ref[ref[SearchParametersIvf]]): Int
func new(obj: ref[ref[SearchParametersIvf]], sel: ref[IdSelector], nprobe: ArchWord, maxCodes: ArchWord): Int
Properties:
sel: ref[IdSelector]
ID selector.
nProbe: ArchWord
Number of clusters to probe.
maxCodes: ArchWord
Maximum codes to scan.
K-means clustering implementation. C API
Creation:
func new(out: ref[ref[Clustering]], d: Int, k: Int): Int
func new(out: ref[ref[Clustering]], d: Int, k: Int, params: ptr[ClusteringParameters]): Int
First form create with dimension and k clusters.
Second form create with parameters.
Methods
handler this.train(n: Int[64], x: ref[Float], index: ref[Index]): Int
Run k-means.
handler this.getCentroids(centroids: ref[ref[array[Float]]], size: ref[ArchWord])
Get cluster centroids.
handler this.getIterationStats(stats_out: ref[ref[ClusteringIterationStats]], size: ref[ArchWord])
Get iteration statistics.
Properties:
niter: Int
Number of iterations.
nredo: Int
Number of k-means restarts.
k: ArchWord
Number of clusters.
d: ArchWord
Vector dimension.
Select subsets of vectors by ID. C API
Variants:
IdSelectorBatch: Select specific IDs from a listIdSelectorRange: Select IDs in a rangeIdSelectorBitmap: Select using a bitmapIdSelectorNot: Invert a selectorIdSelectorAnd: Combine selectors with ANDIdSelectorOr: Combine selectors with ORIdSelectorXor: Combine selectors with XOR
Results from range search queries. C API
Methods:
func new(obj: ref[ref[RangeSearchResult]], nq: Int[64]): Int
handler this.doAllocation(): Int
Allocate result buffers.
handler this.bufferSize(): ArchWord
Get buffer size.
handler this.getLims(outLims: ref[ref[array[ArchWord]]])
Get result limits array.
handler this.getLabels(outLabels: ref[ref[array[Int[64]]]], outDistances: ref[ref[ref[Float]]])
Get labels and distances.
Compute distances to vectors. C API
handler this.setQuery(x: ref[array[Float]]): Int
Set query vector.
handler this.vectorToQueryDis(i: Int[64], qd: ref[array[Float]]): Int
Distance to query.
handler this.symmetricDis(i: Int[64], j: Int[64], vd: ref[array[Float]]): Int
Symmetric distance.
Distance metrics. Docs
METRIC_INNER_PRODUCT(0): Inner product (maximum similarity)METRIC_L2(1): Euclidean distance (L2 norm)METRIC_L1(2): Manhattan distance (L1 norm)METRIC_LINF(3): Infinity norm (Chebyshev distance)METRIC_LP(4): Lp normMETRIC_CANBERRA(20): Canberra distanceMETRIC_BRAY_CURTIS(21): Bray-Curtis dissimilarityMETRIC_JENSEN_SHANNON(22): Jensen-Shannon divergence
Return codes from C API functions.
OK(0): SuccessUNKNOWN_EXCEPT(-1): Unknown exceptionFAISS_EXCEPT(-2): FAISS exceptionSTD_EXCEPT(-4): Standard library exception
func getBuildDependencies(): Array[String];
A function that return an array of libraries and packages required to build a binary version of the application.
func getLastError(): CharsPtr
Get last error message.
func kmeansClustering(d: ArchWord, n: ArchWord, k: ArchWord, x: ref[array[Float]], centroids: ref[array[Float]], q_error: ref[Float]) Int
Standalone k-means.
To enable Vulkan backend, pass the ggml_use_vulkan option to Alusus compiler when running/compiling
your app:
alusus --opt faiss_use_gpu my_app.alusus
This option will make the library load the GPU-enabled binaries instead of the CPU binaries. See FAISS GPU documentation for details.
The Index.new factory method accepts strings to create different index types:
"Flat": Exact search (brute force)"IVFn,Flat": IVF with n centroids, flat encoding"IVFn,PQm": IVF with n centroids, PQ with m subquantizers"HNSW32": Hierarchical navigable small world with 32 neighbors"IVFn,HNSW32": Combined IVF and HNSW
See the index factory documentation for all available options and combinations.
Complete working examples are in the Examples/ directory:
- example.alusus: Basic flat index with inner product search
- example2.alusus: IVF index with parameter tuning
-
Index Selection:
- Use
IndexFlatfor exact search on datasets <1M vectors - Use
IndexIVFfor approximate search on larger datasets - See the index selection guide
- Use
-
Training: IVF and other approximate indexes require training before adding vectors
-
nprobe Parameter: For IVF indexes, higher nprobe = better accuracy but slower search
-
GPU Acceleration: Enable GPU for operations on >10M vectors
-
Memory: Flat indexes store all vectors in memory; use compression for large datasets
See FAISS performance guidelines for detailed recommendations.
- FAISS GitHub: https://github.com/facebookresearch/faiss
- FAISS Wiki: https://github.com/facebookresearch/faiss/wiki
- Research Paper: Billion-scale similarity search with GPUs
- Alusus Language: https://alusus.org
Copyright (c) Facebook, Inc. and its affiliates. Copyright (c) Alusus Software Ltd. for the Alusus language bindings.
This binding follows the FAISS license (MIT). See the LICENSE file for details.