usearch 2.8.6 → 2.8.8

package/java/cloud/unum/usearch/Index.java

@@ -1,337 +0,0 @@
-package cloud.unum.usearch;
-
-/**
- * Java bindings for Unum USearch.
- * <p>
- * Provides interface to interact with USearch library and perform various
- * operations related to indexing and searching.
- *
- * @see <a href=
- *      "https://nachtimwald.com/2017/06/06/wrapping-a-c-library-in-java/">Wrapping
- *      a C library in Java</a>
- * @see <a href=
- *      "https://www3.ntu.edu.sg/home/ehchua/programming/java/javanativeinterface.html">Java
- *      Native Interface tutorial</a>
- */
-public class Index {
-
-  private long c_ptr = 0;
-
-  /**
-   * Creates a new instance of Index with specified parameters.
-   *
-   * @param metric           the metric type for distance calculation between
-   *                         vectors
-   * @param quantization     the scalar type for quantization of vector data
-   * @param dimensions       the number of dimensions in the vectors
-   * @param capacity         the initial capacity of the index
-   * @param connectivity     the connectivity parameter that limits
-   *                         connections-per-node in graph
-   * @param expansion_add    the expansion factor used for index construction when
-   *                         adding vectors
-   * @param expansion_search the expansion factor used for index construction
-   *                         during search operations
-   */
-  public Index(
-      String metric,
-      String quantization,
-      long dimensions,
-      long capacity,
-      long connectivity,
-      long expansion_add,
-      long expansion_search) {
-    c_ptr = c_create(
-        metric,
-        quantization,
-        dimensions,
-        capacity,
-        connectivity,
-        expansion_add,
-        expansion_search);
-  }
-
-  /**
-   * Retrieves the current size of the index.
-   *
-   * @return the number of vectors currently indexed.
-   */
-  public long size() {
-    return c_size(c_ptr);
-  }
-
-  /**
-   * Retrieves the connectivity parameter of the index.
-   *
-   * @return the connectivity parameter that limits connections-per-node in graph.
-   */
-  public long connectivity() {
-    return c_connectivity(c_ptr);
-  }
-
-  /**
-   * Retrieves the number of dimensions of the vectors in the index.
-   *
-   * @return the number of dimensions in the vectors.
-   */
-  public long dimensions() {
-    return c_dimensions(c_ptr);
-  }
-
-  /**
-   * Retrieves the current capacity of the index.
-   *
-   * @return the total capacity including current size.
-   */
-  public long capacity() {
-    return c_capacity(c_ptr);
-  }
-
-  /**
-   * Reserves memory for a specified number of incoming vectors.
-   *
-   * @param capacity the desired total capacity including current size.
-   */
-  public void reserve(long capacity) {
-    c_reserve(c_ptr, capacity);
-  }
-
-  /**
-   * Adds a vector with a specified key to the index.
-   *
-   * @param key    the key associated with the vector
-   * @param vector the vector data
-   */
-  public void add(int key, float vector[]) {
-    c_add(c_ptr, key, vector);
-  }
-
-  /**
-   * Searches for closest vectors to the specified query vector.
-   *
-   * @param vector the query vector data
-   * @param count  the number of nearest neighbors to search
-   * @return an array of keys of the nearest neighbors
-   */
-  public int[] search(float vector[], long count) {
-    return c_search(c_ptr, vector, count);
-  }
-
-  /**
-   * Saves the index to a file.
-   *
-   * @param path the file path where the index will be saved.
-   */
-  public void save(String path) {
-    c_save(c_ptr, path);
-  }
-
-  /**
-   * Loads the index from a file.
-   *
-   * @param path the file path from where the index will be loaded.
-   */
-  public void load(String path) {
-    c_load(c_ptr, path);
-  }
-
-  /**
-   * Creates a view of the index from a file without copying it into memory.
-   *
-   * @param path the file path from where the view will be created.
-   */
-  public void view(String path) {
-    c_view(c_ptr, path);
-  }
-
-  /**
-   * Removes the vector associated with the given key from the index.
-   *
-   * @param key the key of the vector to be removed.
-   * @return {@code true} if the vector was successfully removed, {@code false}
-   *         otherwise.
-   */
-  public boolean remove(int key) {
-    return c_remove(c_ptr, key);
-  }
-
-  /**
-   * Renames the vector to map to a different key.
-   *
-   * @param from the key of the vector to be renamed.
-   * @param to   the new key for the vector.
-   * @return {@code true} if the vector was successfully renamed, {@code false}
-   *         otherwise.
-   */
-  public boolean rename(int from, int to) {
-    return c_rename(c_ptr, from, to);
-  }
-
-  /**
-   * Configuration class for building an Index instance.
-   * <p>
-   * This class provides a builder pattern to set various configurations for an
-   * Index. Once all configurations
-   * are set, calling {@link #build()} will produce an instance of {@link Index}.
-   */
-  public static class Config {
-
-    private String _metric = "ip";
-    private String _quantization = "f32";
-    private long _dimensions = 0;
-    private long _capacity = 0;
-    private long _connectivity = 0;
-    private long _expansion_add = 0;
-    private long _expansion_search = 0;
-
-    /**
-     * Default constructor for the Config class.
-     */
-    public Config() {
-    }
-
-    /**
-     * Constructs an Index instance based on the current configuration settings.
-     *
-     * @return a newly constructed Index instance.
-     */
-    public Index build() {
-      return new Index(
-          _metric,
-          _quantization,
-          _dimensions,
-          _capacity,
-          _connectivity,
-          _expansion_add,
-          _expansion_search);
-    }
-
-    /**
-     * Sets the metric for distance calculation between vectors.
-     *
-     * @param _metric the metric type
-     * @return this configuration instance
-     */
-    public Config metric(String _metric) {
-      this._metric = _metric;
-      return this;
-    }
-
-    /**
-     * Sets the scalar type for quantization of vector data.
-     *
-     * @param _quantization the quantization type
-     * @return this configuration instance
-     */
-    public Config quantization(String _quantization) {
-      this._quantization = _quantization;
-      return this;
-    }
-
-    /**
-     * Sets the number of dimensions in the vectors.
-     *
-     * @param _dimensions the number of dimensions
-     * @return this configuration instance
-     */
-    public Config dimensions(long _dimensions) {
-      this._dimensions = _dimensions;
-      return this;
-    }
-
-    /**
-     * Sets the initial capacity of the index.
-     *
-     * @param _capacity the index capacity
-     * @return this configuration instance
-     */
-    public Config capacity(long _capacity) {
-      this._capacity = _capacity;
-      return this;
-    }
-
-    /**
-     * Sets the connectivity parameter that limits connections-per-node in the
-     * graph.
-     *
-     * @param _connectivity the connectivity value
-     * @return this configuration instance
-     */
-    public Config connectivity(long _connectivity) {
-      this._connectivity = _connectivity;
-      return this;
-    }
-
-    /**
-     * Sets the expansion factor used for index construction when adding vectors.
-     *
-     * @param _expansion_add the expansion factor for adding vectors
-     * @return this configuration instance
-     */
-    public Config expansion_add(long _expansion_add) {
-      this._expansion_add = _expansion_add;
-      return this;
-    }
-
-    /**
-     * Sets the expansion factor used for index construction during search
-     * operations.
-     *
-     * @param _expansion_search the expansion factor for search
-     * @return this configuration instance
-     */
-    public Config expansion_search(long _expansion_search) {
-      this._expansion_search = _expansion_search;
-      return this;
-    }
-  }
-
-  static {
-    System.loadLibrary("usearch");
-  }
-
-  /**
-   * A simple main method to test the Index functionalities.
-   *
-   * @param args command line arguments (not used in this case)
-   */
-  public static void main(String[] args) {
-    Index index = new Index.Config().metric("cos").dimensions(100).build();
-    index.size();
-    System.out.println("Java tests passed!");
-  }
-
-  private static native long c_create(
-      String metric,
-      String quantization,
-      long dimensions,
-      long capacity,
-      long connectivity,
-      long expansion_add,
-      long expansion_search);
-
-  private static native void c_destroy(long ptr);
-
-  private static native long c_size(long ptr);
-
-  private static native long c_connectivity(long ptr);
-
-  private static native long c_dimensions(long ptr);
-
-  private static native long c_capacity(long ptr);
-
-  private static native void c_reserve(long ptr, long capacity);
-
-  private static native void c_add(long ptr, int key, float vector[]);
-
-  private static native int[] c_search(long ptr, float vector[], long count);
-
-  private static native void c_save(long ptr, String path);
-
-  private static native void c_load(long ptr, String path);
-
-  private static native void c_view(long ptr, String path);
-
-  private static native boolean c_remove(long ptr, int key);
-
-  private static native boolean c_rename(long ptr, int from, int to);
-}

package/java/cloud/unum/usearch/cloud_unum_usearch_Index.cpp

@@ -1,197 +0,0 @@
-#include <jni.h>
-
-#include "cloud_unum_usearch_Index.h"
-
-#include <thread>
-
-#include <usearch/index_dense.hpp>
-
-using namespace unum::usearch;
-using namespace unum;
-
-using float_span_t = unum::usearch::span_gt<float>;
-
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1create( //
-    JNIEnv* env, jclass,                                         //
-    jstring metric, jstring quantization,                        //
-    jlong dimensions, jlong capacity, jlong connectivity,        //
-    jlong expansion_add, jlong expansion_search) {
-
-    jlong result{};
-    char const* metric_cstr{};
-    char const* quantization_cstr{};
-    try {
-
-        std::size_t connectivity = static_cast<std::size_t>(connectivity);
-        std::size_t expansion_add = static_cast<std::size_t>(expansion_add);
-        std::size_t expansion_search = static_cast<std::size_t>(expansion_search);
-
-        metric_cstr = (*env).GetStringUTFChars(metric, 0);
-        std::size_t metric_length = (*env).GetStringUTFLength(metric);
-        quantization_cstr = (*env).GetStringUTFChars(quantization, 0);
-        std::size_t quantization_length = (*env).GetStringUTFLength(quantization);
-
-        metric_kind_t metric_kind = metric_from_name(metric_cstr, metric_length);
-        scalar_kind_t quantization = scalar_kind_from_name(quantization_cstr, quantization_length);
-        index_dense_config_t config(connectivity, expansion_add, expansion_search);
-        metric_punned_t metric(static_cast<std::size_t>(dimensions), metric_kind, quantization);
-        index_dense_t index = index_dense_t::make(metric, config);
-        if (!index.reserve(static_cast<std::size_t>(capacity))) {
-            jclass jc = (*env).FindClass("java/lang/Error");
-            if (jc)
-                (*env).ThrowNew(jc, "Failed to reserve desired capacity!");
-        } else {
-            index_dense_t* result_ptr = new index_dense_t(std::move(index));
-            std::memcpy(&result, &result_ptr, sizeof(jlong));
-        }
-
-    } catch (...) {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, "Failed to initialize the vector index!");
-    }
-
-    (*env).ReleaseStringUTFChars(metric, metric_cstr);
-    (*env).ReleaseStringUTFChars(quantization, quantization_cstr);
-    return result;
-}
-
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1save(JNIEnv* env, jclass, jlong c_ptr, jstring path) {
-    char const* path_cstr = (*env).GetStringUTFChars(path, 0);
-    serialization_result_t result = reinterpret_cast<index_dense_t*>(c_ptr)->save(path_cstr);
-    if (!result) {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, result.error.release());
-    }
-    (*env).ReleaseStringUTFChars(path, path_cstr);
-}
-
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1load(JNIEnv* env, jclass, jlong c_ptr, jstring path) {
-    char const* path_cstr = (*env).GetStringUTFChars(path, 0);
-    serialization_result_t result = reinterpret_cast<index_dense_t*>(c_ptr)->load(path_cstr);
-    if (!result) {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, result.error.release());
-    }
-    (*env).ReleaseStringUTFChars(path, path_cstr);
-}
-
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1view(JNIEnv* env, jclass, jlong c_ptr, jstring path) {
-    char const* path_cstr = (*env).GetStringUTFChars(path, 0);
-    serialization_result_t result = reinterpret_cast<index_dense_t*>(c_ptr)->view(path_cstr);
-    if (!result) {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, result.error.release());
-    }
-    (*env).ReleaseStringUTFChars(path, path_cstr);
-}
-
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1destroy(JNIEnv*, jclass, jlong c_ptr) {
-    delete reinterpret_cast<index_dense_t*>(c_ptr);
-}
-
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1size(JNIEnv*, jclass, jlong c_ptr) {
-    return reinterpret_cast<index_dense_t*>(c_ptr)->size();
-}
-
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1connectivity(JNIEnv*, jclass, jlong c_ptr) {
-    return reinterpret_cast<index_dense_t*>(c_ptr)->connectivity();
-}
-
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1dimensions(JNIEnv*, jclass, jlong c_ptr) {
-    return reinterpret_cast<index_dense_t*>(c_ptr)->dimensions();
-}
-
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1capacity(JNIEnv*, jclass, jlong c_ptr) {
-    return reinterpret_cast<index_dense_t*>(c_ptr)->capacity();
-}
-
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1reserve(JNIEnv* env, jclass, jlong c_ptr, jlong capacity) {
-    if (!reinterpret_cast<index_dense_t*>(c_ptr)->reserve(static_cast<std::size_t>(capacity))) {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, "Failed to grow vector index!");
-    }
-}
-
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1add( //
-    JNIEnv* env, jclass, jlong c_ptr, jint key, jfloatArray vector) {
-
-    jfloat* vector_data = (*env).GetFloatArrayElements(vector, 0);
-    jsize vector_dims = (*env).GetArrayLength(vector);
-    float_span_t vector_span = float_span_t{vector_data, static_cast<std::size_t>(vector_dims)};
-
-    using vector_key_t = typename index_dense_t::vector_key_t;
-    using add_result_t = typename index_dense_t::add_result_t;
-
-    add_result_t result = reinterpret_cast<index_dense_t*>(c_ptr)->add(static_cast<vector_key_t>(key), vector_span);
-    if (!result) {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, result.error.release());
-    }
-    (*env).ReleaseFloatArrayElements(vector, vector_data, 0);
-}
-
-JNIEXPORT jintArray JNICALL Java_cloud_unum_usearch_Index_c_1search( //
-    JNIEnv* env, jclass, jlong c_ptr, jfloatArray vector, jlong wanted) {
-
-    jintArray matches;
-    matches = (*env).NewIntArray(wanted);
-    if (matches == NULL)
-        return NULL;
-
-    jint* matches_data = (jint*)std::malloc(sizeof(jint) * wanted);
-    if (matches_data == NULL)
-        return NULL;
-
-    jfloat* vector_data = (*env).GetFloatArrayElements(vector, 0);
-    jsize vector_dims = (*env).GetArrayLength(vector);
-    float_span_t vector_span = float_span_t{vector_data, static_cast<std::size_t>(vector_dims)};
-
-    using vector_key_t = typename index_dense_t::vector_key_t;
-    using search_result_t = typename index_dense_t::search_result_t;
-
-    search_result_t result =
-        reinterpret_cast<index_dense_t*>(c_ptr)->search(vector_span, static_cast<std::size_t>(wanted));
-    if (result) {
-        std::size_t found = result.dump_to(reinterpret_cast<vector_key_t*>(matches_data), NULL);
-        (*env).SetIntArrayRegion(matches, 0, found, matches_data);
-    } else {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, result.error.release());
-    }
-
-    (*env).ReleaseFloatArrayElements(vector, vector_data, 0);
-    std::free(matches_data);
-    return matches;
-}
-
-JNIEXPORT bool JNICALL Java_cloud_unum_usearch_Index_c_1remove(JNIEnv* env, jclass, jlong c_ptr, jlong key) {
-    using vector_key_t = typename index_dense_t::vector_key_t;
-    using labeling_result_t = typename index_dense_t::labeling_result_t;
-    labeling_result_t result = reinterpret_cast<index_dense_t*>(c_ptr)->remove(static_cast<vector_key_t>(key));
-    if (!result) {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, result.error.release());
-    }
-    return result.completed;
-}
-
-JNIEXPORT bool JNICALL Java_cloud_unum_usearch_Index_c_1rename(JNIEnv* env, jclass, jlong c_ptr, jlong from, jlong to) {
-    using vector_key_t = typename index_dense_t::vector_key_t;
-    using labeling_result_t = typename index_dense_t::labeling_result_t;
-    labeling_result_t result =
-        reinterpret_cast<index_dense_t*>(c_ptr)->rename(static_cast<vector_key_t>(from), static_cast<vector_key_t>(to));
-    if (!result) {
-        jclass jc = (*env).FindClass("java/lang/Error");
-        if (jc)
-            (*env).ThrowNew(jc, result.error.release());
-    }
-    return result.completed;
-}

package/java/cloud/unum/usearch/cloud_unum_usearch_Index.h

@@ -1,125 +0,0 @@
-/* DO NOT EDIT THIS FILE - it is machine generated */
-#include <jni.h>
-/* Header for class cloud_unum_usearch_Index */
-
-#ifndef _Included_cloud_unum_usearch_Index
-#define _Included_cloud_unum_usearch_Index
-#ifdef __cplusplus
-extern "C" {
-#endif
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_create
- * Signature: (Ljava/lang/String;Ljava/lang/String;JJJJJ)J
- */
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1create
-  (JNIEnv *, jclass, jstring, jstring, jlong, jlong, jlong, jlong, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_destroy
- * Signature: (J)V
- */
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1destroy
-  (JNIEnv *, jclass, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_size
- * Signature: (J)J
- */
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1size
-  (JNIEnv *, jclass, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_connectivity
- * Signature: (J)J
- */
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1connectivity
-  (JNIEnv *, jclass, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_dimensions
- * Signature: (J)J
- */
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1dimensions
-  (JNIEnv *, jclass, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_capacity
- * Signature: (J)J
- */
-JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1capacity
-  (JNIEnv *, jclass, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_reserve
- * Signature: (JJ)V
- */
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1reserve
-  (JNIEnv *, jclass, jlong, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_add
- * Signature: (JI[F)V
- */
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1add
-  (JNIEnv *, jclass, jlong, jint, jfloatArray);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_search
- * Signature: (J[FJ)[I
- */
-JNIEXPORT jintArray JNICALL Java_cloud_unum_usearch_Index_c_1search
-  (JNIEnv *, jclass, jlong, jfloatArray, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_save
- * Signature: (JLjava/lang/String;)V
- */
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1save
-  (JNIEnv *, jclass, jlong, jstring);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_load
- * Signature: (JLjava/lang/String;)V
- */
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1load
-  (JNIEnv *, jclass, jlong, jstring);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_view
- * Signature: (JLjava/lang/String;)V
- */
-JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1view
-  (JNIEnv *, jclass, jlong, jstring);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_remove
- * Signature: (JLjava/lang/String;)V
- */
-JNIEXPORT bool JNICALL Java_cloud_unum_usearch_Index_c_1remove
-  (JNIEnv *, jclass, jlong);
-
-/*
- * Class:     cloud_unum_usearch_Index
- * Method:    c_rename
- * Signature: (JLjava/lang/String;)V
- */
-JNIEXPORT bool JNICALL Java_cloud_unum_usearch_Index_c_1rename
-  (JNIEnv *, jclass, jlong, jlong);
-  
-#ifdef __cplusplus
-}
-#endif
-#endif

package/java/test/IndexTest.java

@@ -1,30 +0,0 @@
-import java.io.File;
-import java.util.Arrays;
-
-import org.junit.Test;
-
-import cloud.unum.usearch.Index;
-
-public class IndexTest {
-    public static void deleteDirectoryFiles(String path) {
-        File directory = new File(path);
-        if (!directory.isDirectory())
-            return;
-
-        for (File f : directory.listFiles())
-            f.delete();
-    }
-
-    @Test
-    public void test() {
-        String path = "./tmp/";
-        deleteDirectoryFiles(path);
-
-        // Index index = new Index.Config().metric("cos").dimensions(2).build();
-        // float vec[] = {10, 20};
-        // index.add(42, vec);
-        // int[] keys = index.search(vec, 5);
-
-        System.out.println("Java Tests Passed!");
-    }
-}