libmf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85fc60af42649286b87cf23130c0efafd0d8951423d31b187d13097b2418e7d1
+  data.tar.gz: ab568af8e036b6d38fcc604746eeda4fa29e2e6e7541e6af53b77f9979e9fe82
+SHA512:
+  metadata.gz: efcbffd9ed9e6f66911a63e74d694da77d798d0fde04cb1490c1ee4eaf8d9e1e93b1af13ab8e23a4a858b74503d28a616ad6499a590f4a1568df2a9dcb65d85f
+  data.tar.gz: 671b306cad36c2ea5da6633de6703892e19fbb5774cf22a0d458ba3d967ab50dc5ae56ed271771e4ed1a0483346d8d9f34ec5db9c8424d16f369e81c5f467857

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- First release

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2019 Andrew Kane
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# LIBMF
+
+[LIBMF](https://github.com/cjlin1/libmf) - large-scale sparse matrix factorization - for Ruby
+
+:fire: Uses the C API for blazing performance
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem 'libmf'
+```
+
+## Getting Started
+
+Prep your data in the format `[row_index, column_index, value]`
+
+```ruby
+data = [
+  [0, 0, 5.0],
+  [0, 2, 3.5],
+  [1, 1, 4.0]
+]
+```
+
+Create a model
+
+```ruby
+model = Libmf::Model.new
+model.fit(data)
+```
+
+Make predictions
+
+```ruby
+model.predict(row_index, column_index)
+```
+
+Get the bias and latent factors
+
+```ruby
+model.bias
+model.p_factors
+model.q_factors
+```
+
+Save the model to a file
+
+```ruby
+model.save_model("model.txt")
+```
+
+Load the model from a file
+
+```ruby
+model.load_model("model.txt")
+```
+
+Pass a validation set
+
+```ruby
+model.fit(data, eval_set: eval_set)
+```
+
+## Parameters
+
+Pass parameters
+
+```ruby
+model = Libmf::Model.new(k: 20, nr_iters: 50)
+```
+
+Supports the same parameters as LIBMF
+
+```text
+variable      meaning                                    default
+================================================================
+fun           loss function                                    0
+k             number of latent factors                         8
+nr_threads    number of threads used                          12
+nr_bins       number of bins                                  25
+nr_iters      number of iterations                            20
+lambda_p1     coefficient of L1-norm regularization on P       0
+lambda_p2     coefficient of L2-norm regularization on P     0.1
+lambda_q1     coefficient of L1-norm regularization on Q       0
+lambda_q2     coefficient of L2-norm regularization on Q     0.1
+eta           learning rate                                  0.1
+alpha         importance of negative entries                 0.1
+c             desired value of negative entries           0.0001
+do_nmf        perform non-negative MF (NMF)                false
+quiet         no outputs to stdout                         false
+copy_data     copy data in training procedure               true
+```
+
+## Cross-Validation
+
+Perform cross-validation
+
+```ruby
+model.cv(data)
+```
+
+Specify the number of folds
+
+```ruby
+model.cv(data, folds: 5)
+```
+
+## Resources
+
+- [LIBMF: A Library for Parallel Matrix Factorization in Shared-memory Systems](https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/libmf_open_source.pdf)
+
+## History
+
+View the [changelog](https://github.com/ankane/libmf/blob/master/CHANGELOG.md)
+
+## Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/ankane/libmf/issues)
+- Fix bugs and [submit pull requests](https://github.com/ankane/libmf/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features

data/ext/libmf/extconf.rb

@@ -0,0 +1,18 @@
+require "mkmf"
+
+arch = RbConfig::CONFIG["arch"]
+case arch
+when /mingw/
+  File.write("Makefile", dummy_makefile("libmf").join)
+else
+  abort "Missing stdc++" unless have_library("stdc++")
+  $CXXFLAGS << " -std=c++11"
+
+  # TODO
+  # if have_library("libomp")
+  # end
+
+  $objs = ["mf.o"]
+  vendor_path = File.expand_path("../../vendor/libmf", __dir__)
+  create_makefile("libmf", vendor_path)
+end

data/lib/libmf.rb

@@ -0,0 +1,26 @@
+# dependencies
+require "ffi"
+
+# modules
+require "libmf/model"
+require "libmf/version"
+
+module Libmf
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :ffi_lib
+  end
+  self.ffi_lib = ["mf"]
+
+  lib_path =
+    if ::FFI::Platform.windows?
+      "../vendor/windows/mf.dll"
+    else
+      "libmf.bundle"
+    end
+  self.ffi_lib << File.expand_path(lib_path, __dir__)
+
+  # friendlier error message
+  autoload :FFI, "libmf/ffi"
+end

data/lib/libmf/ffi.rb

@@ -0,0 +1,62 @@
+module Libmf
+  module FFI
+    extend ::FFI::Library
+
+    begin
+      ffi_lib Libmf.ffi_lib
+    rescue LoadError => e
+      raise e if ENV["LIBMF_DEBUG"]
+      raise LoadError, "Could not find LIBMF"
+    end
+
+    class Node < ::FFI::Struct
+      layout :u, :int,
+        :v, :int,
+        :r, :float
+    end
+
+    class Problem < ::FFI::Struct
+      layout :m, :int,
+        :n, :int,
+        :nnz, :long_long,
+        :r, :pointer
+    end
+
+    class Parameter < ::FFI::Struct
+      layout :fun, :int,
+        :k, :int,
+        :nr_threads, :int,
+        :nr_bins, :int,
+        :nr_iters, :int,
+        :lambda_p1, :float,
+        :lambda_p2, :float,
+        :lambda_q1, :float,
+        :lambda_q2, :float,
+        :eta, :float,
+        :alpha, :float,
+        :c, :float,
+        :do_nmf, :bool,
+        :quiet, :bool,
+        :copy_data, :bool
+    end
+
+    class Model < ::FFI::Struct
+      layout :fun, :int,
+        :m, :int,
+        :n, :int,
+        :k, :int,
+        :b, :float,
+        :p, :pointer,
+        :q, :pointer
+    end
+
+    attach_function :mf_get_default_param, [], Parameter.by_value
+    attach_function :mf_save_model, [Model.by_ref, :string], :int
+    attach_function :mf_load_model, [:string], Model.by_ref
+    attach_function :mf_destroy_model, [Model.by_ref], :void
+    attach_function :mf_train, [Problem.by_ref, Parameter.by_value], Model.by_ref
+    attach_function :mf_train_with_validation, [Problem.by_ref, Problem.by_ref, Parameter.by_value], Model.by_ref
+    attach_function :mf_predict, [Model.by_ref, :int, :int], :float
+    attach_function :mf_cross_validation, [Problem.by_ref, :int, Parameter.by_value], :double
+  end
+end

data/lib/libmf/model.rb

@@ -0,0 +1,112 @@
+module Libmf
+  class Model
+    def initialize(**options)
+      @options = options
+    end
+
+    def fit(data, eval_set: nil)
+      train_set = create_problem(data)
+
+      @model =
+        if eval_set
+          eval_set = create_problem(eval_set)
+          FFI.mf_train_with_validation(train_set, eval_set, param)
+        else
+          FFI.mf_train(train_set, param)
+        end
+
+      nil
+    end
+
+    def predict(row, column)
+      FFI.mf_predict(model, row, column)
+    end
+
+    def cv(data, folds: 5)
+      problem = create_problem(data)
+      FFI.mf_cross_validation(problem, folds, param)
+    end
+
+    def save_model(path)
+      FFI.mf_save_model(model, path)
+    end
+
+    def load_model(path)
+      @model = FFI.mf_load_model(path)
+    end
+
+    def rows
+      model[:m]
+    end
+
+    def columns
+      model[:n]
+    end
+
+    def factors
+      model[:k]
+    end
+
+    def bias
+      model[:b]
+    end
+
+    def p_factors
+      reshape(model[:p].read_array_of_float(factors * rows), [rows, factors])
+    end
+
+    def q_factors
+      reshape(model[:q].read_array_of_float(factors * columns), [columns, factors])
+    end
+
+    private
+
+    def model
+      raise Error, "Not fit" unless @model
+      @model
+    end
+
+    def param
+      param = FFI.mf_get_default_param
+      # silence insufficient blocks warning with default params
+      options = {nr_bins: 25}.merge(@options)
+      options.each do |k, v|
+        param[k] = v
+      end
+      param
+    end
+
+    def create_problem(data)
+      raise Error, "No data" if data.empty?
+
+      nodes = []
+      r = ::FFI::MemoryPointer.new(FFI::Node, data.size)
+      data.each_with_index do |row, i|
+        n = FFI::Node.new(r[i])
+        n[:u] = row[0]
+        n[:v] = row[1]
+        n[:r] = row[2]
+        nodes << n
+      end
+
+      m = nodes.map { |n| n[:u] }.max + 1
+      n = nodes.map { |n| n[:v] }.max + 1
+
+      prob = FFI::Problem.new
+      prob[:m] = m
+      prob[:n] = n
+      prob[:nnz] = nodes.size
+      prob[:r] = r
+      prob
+    end
+
+    def reshape(arr, dims)
+      rows = dims.first
+      new_arr = rows.times.map { [] }
+      arr.each_with_index do |v, i|
+        new_arr[i % rows] << v
+      end
+      new_arr
+    end
+  end
+end

data/lib/libmf/version.rb

@@ -0,0 +1,3 @@
+module Libmf
+  VERSION = "0.1.0"
+end

data/vendor/libmf/COPYRIGHT

@@ -0,0 +1,31 @@
+
+Copyright (c) 2014-2015 The LIBMF Project.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Neither name of copyright holders nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/vendor/libmf/Makefile

@@ -0,0 +1,34 @@
+CXX = g++
+CXXFLAGS = -Wall -O3 -pthread -std=c++0x -march=native
+OMPFLAG = -fopenmp
+SHVER = 2
+
+# run `make clean all' if you change the following flags.
+
+# comment the following flag if you want to disable SSE or enable AVX
+DFLAG = -DUSESSE
+
+# uncomment the following flags if you want to use AVX
+#DFLAG = -DUSEAVX
+#CXXFLAGS += -mavx
+
+# uncomment the following flags if you do not want to use OpenMP
+DFLAG += -DUSEOMP
+CXXFLAGS += $(OMPFLAG)
+
+all: mf-train mf-predict
+
+lib: 
+	$(CXX) -shared -Wl,-soname,libmf.so.$(SHVER) -o libmf.so.$(SHVER) mf.o 
+
+mf-train: mf-train.cpp mf.o
+	$(CXX) $(CXXFLAGS) $(DFLAG) -o $@ $^
+
+mf-predict: mf-predict.cpp mf.o
+	$(CXX) $(CXXFLAGS) $(DFLAG) -o $@ $^
+
+mf.o: mf.cpp mf.h
+	$(CXX) $(CXXFLAGS) $(DFLAG) -c -fPIC -o $@ $<
+
+clean:
+	rm -f mf-train mf-predict mf.o libmf.so.$(SHVER)