annoy-rb 0.1.0

data/ext/annoy/src/kissrandom.h

@@ -0,0 +1,106 @@
+#ifndef KISSRANDOM_H
+#define KISSRANDOM_H
+
+#if defined(_MSC_VER) && _MSC_VER == 1500
+typedef unsigned __int32    uint32_t;
+typedef unsigned __int64    uint64_t;
+#else
+#include <stdint.h>
+#endif
+
+// KISS = "keep it simple, stupid", but high quality random number generator
+// http://www0.cs.ucl.ac.uk/staff/d.jones/GoodPracticeRNG.pdf -> "Use a good RNG and build it into your code"
+// http://mathforum.org/kb/message.jspa?messageID=6627731
+// https://de.wikipedia.org/wiki/KISS_(Zufallszahlengenerator)
+
+// 32 bit KISS
+struct Kiss32Random {
+  uint32_t x;
+  uint32_t y;
+  uint32_t z;
+  uint32_t c;
+
+  // seed must be != 0
+  Kiss32Random(uint32_t seed = 123456789) {
+    x = seed;
+    y = 362436000;
+    z = 521288629;
+    c = 7654321;
+  }
+
+  uint32_t kiss() {
+    // Linear congruence generator
+    x = 69069 * x + 12345;
+
+    // Xor shift
+    y ^= y << 13;
+    y ^= y >> 17;
+    y ^= y << 5;
+
+    // Multiply-with-carry
+    uint64_t t = 698769069ULL * z + c;
+    c = t >> 32;
+    z = (uint32_t) t;
+
+    return x + y + z;
+  }
+  inline int flip() {
+    // Draw random 0 or 1
+    return kiss() & 1;
+  }
+  inline size_t index(size_t n) {
+    // Draw random integer between 0 and n-1 where n is at most the number of data points you have
+    return kiss() % n;
+  }
+  inline void set_seed(uint32_t seed) {
+    x = seed;
+  }
+};
+
+// 64 bit KISS. Use this if you have more than about 2^24 data points ("big data" ;) )
+struct Kiss64Random {
+  uint64_t x;
+  uint64_t y;
+  uint64_t z;
+  uint64_t c;
+
+  // seed must be != 0
+  Kiss64Random(uint64_t seed = 1234567890987654321ULL) {
+    x = seed;
+    y = 362436362436362436ULL;
+    z = 1066149217761810ULL;
+    c = 123456123456123456ULL;
+  }
+
+  uint64_t kiss() {
+    // Linear congruence generator
+    z = 6906969069LL*z+1234567;
+
+    // Xor shift
+    y ^= (y<<13);
+    y ^= (y>>17);
+    y ^= (y<<43);
+
+    // Multiply-with-carry (uint128_t t = (2^58 + 1) * x + c; c = t >> 64; x = (uint64_t) t)
+    uint64_t t = (x<<58)+c;
+    c = (x>>6);
+    x += t;
+    c += (x<t);
+
+    return x + y + z;
+  }
+  inline int flip() {
+    // Draw random 0 or 1
+    return kiss() & 1;
+  }
+  inline size_t index(size_t n) {
+    // Draw random integer between 0 and n-1 where n is at most the number of data points you have
+    return kiss() % n;
+  }
+  inline void set_seed(uint32_t seed) {
+    x = seed;
+  }
+};
+
+#endif
+// vim: tabstop=2 shiftwidth=2

data/lib/annoy.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'annoy/version'
+require 'annoy/annoy'
+
+module Annoy
+  # AnnoyIndex is a class that provides functions for k-nearest neighbors search.
+  # The methods in this class are implemented similarly to Annoy's Python API (https://github.com/spotify/annoy#full-python-api).
+  #
+  # @example
+  #   require 'annoy'
+  #
+  #   index = AnnoyIndex.new(n_features: 100, metric: 'euclidean')
+  #
+  #   5000.times do |item_id|
+  #     item_vec = Array.new(100) { rand - 0.5 }
+  #     index.add_item(item_id, item_vec)
+  #   end
+  #
+  #   index.build(10)
+  #
+  #   index.get_nns_by_item(0, 100)
+  #
+  class AnnoyIndex
+    # Returns the number of features of indexed item.
+    # @return [Integer]
+    attr_reader :n_features
+
+    # Returns the metric of index.
+    # @return [String]
+    attr_reader :metric
+
+    # Create a new search index.
+    #
+    # @param n_features [Integer] The number of features (dimensions) of stored vector.
+    # @param metric [String] The distance metric between vectors ('angular', 'dot', 'hamming', 'euclidean', or 'manhattan').
+    def initialize(n_features:, metric: 'angular')
+      raise ArgumentError, 'Expect n_features to be Integer.' unless n_features.is_a?(Numeric)
+
+      @n_features = n_features.to_i
+      @metric = metric
+
+      @index = case @metric
+               when 'angular'
+                 AnnoyIndexAngular.new(@n_features)
+               when 'dot'
+                 AnnoyIndexDotProduct.new(@n_features)
+               when 'hamming'
+                 AnnoyIndexHamming.new(@n_features)
+               when 'euclidean'
+                 AnnoyIndexEuclidean.new(@n_features)
+               when 'manhattan'
+                 AnnoyIndexManhattan.new(@n_features)
+               else
+                 raise ArgumentError, "No such metric: #{@metric}."
+               end
+    end
+
+    # Add item to be indexed.
+    #
+    # @param i [Integer] The ID of item.
+    # @param v [Array] The vector of item.
+    # @return [Boolean]
+    def add_item(i, v)
+      @index.add_item(i, v)
+    end
+
+    # Build a forest of index trees. After building, no more items can be added.
+    #
+    # @param n_trees [Integer] The number of trees. More trees gives higher search precision.
+    # @return [Boolean]
+    def build(n_trees)
+      @index.build(n_trees)
+    end
+
+    # Save the search index to disk. After saving, no more items can be added.
+    #
+    # @param filename [String] The filename of search index.
+    # @return [Boolean]
+    def save(filename, prefault: false)
+      @index.save(filename, prefault)
+    end
+
+    # Load a search index from disk.
+    #
+    # @param filename [String] The filename of search index.
+    # @param prefault [Boolean] The flag indicating whether to pre-read the entire file into memory.
+    # @return [Boolean]
+    def load(filename, prefault: false)
+      @index.load(filename, prefault)
+    end
+
+    # Unload the search index.
+    #
+    # @return [Boolean]
+    def unload
+      @index.unload
+    end
+
+    # Search the n closest items.
+    #
+    # @param i [Integer] The ID of query item.
+    # @param n [Integer] The number of nearest neighbors.
+    # @param search_k [Integer] The maximum number of nodes inspected during the search. If -1 is given, it sets to n * n_trees.
+    # @param include_distances [Boolean] The flag indicating whether to returns all corresponding distances.
+    # @return [Array<Integer> or Array<Array<Integer>, Array<Float>>]
+    def get_nns_by_item(i, n, search_k: -1, include_distances: false)
+      @index.get_nns_by_item(i, n, search_k, include_distances)
+    end
+
+    # Search the n closest items.
+    #
+    # @param v [Array] The vector of query item.
+    # @param n [Integer] The number of nearest neighbors.
+    # @param search_k [Integer] The maximum number of nodes inspected during the search. If -1 is given, it sets to n * n_trees.
+    # @param include_distances [Boolean] The flag indicating whether to returns all corresponding distances.
+    # @return [Array<Integer> or Array<Array<Integer>, Array<Float>>]
+    def get_nns_by_vector(v, n, search_k: -1, include_distances: false)
+      @index.get_nns_by_vector(v, n, search_k, include_distances)
+    end
+
+    # Return the item vector.
+    #
+    # @param i [Integer] The ID of item.
+    # @return [Array]
+    def get_item(i)
+      @index.get_item(i)
+    end
+
+    # Calculate the distances between items.
+    #
+    # @param i [Integer] The ID of item.
+    # @param j [Integer] The ID of item.
+    # @return [Float or Integer]
+    def get_distance(i, j)
+      @index.get_distance(i, j)
+    end
+
+    # Return the number of items in the search index.
+    # @return [Integer]
+    def n_items
+      @index.get_n_items
+    end
+
+    # Return the number of trees in the search index.
+    # @return [Integer]
+    def n_trees
+      @index.get_n_trees
+    end
+
+    # Prepare annoy to build the index in the specified file instead of RAM.
+    # (call this method before adding items, no need to save after building).
+    #
+    # @param filename [String] The filename of search index.
+    # @return [Boolean]
+    def on_disk_build(filename)
+      @index.on_disk_build(filename)
+    end
+
+    # Set to verbose mode.
+    #
+    # @param flag [Boolean]
+    def verbose(flag)
+      @index.verbose(flag)
+    end
+
+    # Set seed for the random number generator.
+    #
+    # @param s [Integer]
+    def seed(s)
+      @index.set_seed(s)
+    end
+  end
+end

data/lib/annoy/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Annoy.rb is a Ruby wrapper for Annoy (Approximate Nearest Neighbors Oh Yeah).
+module Annoy
+  # The version of Annoy.rb you are using.
+  VERSION = '0.1.0'.freeze
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: annoy-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- yoshoku
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2020-08-08 00:00:00.000000000 Z
+dependencies: []
+description: Annoy.rb is a Ruby binding for the Annoy (Approximate Nearest Neighbors
+  Oh Yeah).
+email:
+- yoshoku@outlook.com
+executables: []
+extensions:
+- ext/annoy/extconf.rb
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- annoy-rb.gemspec
+- ext/annoy/annoy.cpp
+- ext/annoy/annoy.hpp
+- ext/annoy/extconf.rb
+- ext/annoy/src/annoylib.h
+- ext/annoy/src/kissrandom.h
+- lib/annoy.rb
+- lib/annoy/version.rb
+homepage: https://github.com/yoshoku/annoy.rb
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/yoshoku/annoy.rb
+  source_code_uri: https://github.com/yoshoku/annoy.rb
+  changelog_uri: https://github.com/yoshoku/annoy.rb/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: Ruby binding for the Annoy (Approximate Nearest Neighbors Oh Yeah).
+test_files: []