nmatrix 0.1.0.rc5 → 0.1.0

data/lib/nmatrix/nmatrix.rb

@@ -30,31 +30,39 @@
 
 require_relative './lapack.rb'
 require_relative './yale_functions.rb'
+require_relative './monkeys'
 
+# NMatrix is a matrix class that supports both multidimensional arrays
+# (`:dense` stype) and sparse storage (`:list` or `:yale` stypes) and 13 data
+# types, including complex and rational numbers, various integer and
+# floating-point sizes and ruby objects.
 class NMatrix
-
-  # Read and write extensions for NMatrix. These are only loaded when needed.
-  #
+  # Read and write extensions for NMatrix.
   module IO
+    extend AutoloadPatch
+
+    # Reader (and eventually writer) of Matlab .mat files.
+    #
+    # The .mat file format is documented in the following link:
+    # * http://www.mathworks.com/help/pdf_doc/matlab/matfile_format.pdf
     module Matlab
+      extend AutoloadPatch
+
       class << self
-        def load_mat file_path
+        # call-seq:
+        #     load(mat_file_path) -> NMatrix
+        #     load_mat(mat_file_path) -> NMatrix
+        #
+        # Load a .mat file and return a NMatrix corresponding to it.
+        def load_mat(file_path)
           NMatrix::IO::Matlab::Mat5Reader.new(File.open(file_path, "rb+")).to_ruby
         end
         alias :load :load_mat
       end
-
-      # FIXME: Remove autoloads
-      autoload :MatReader, 'nmatrix/io/mat_reader'
-      autoload :Mat5Reader, 'nmatrix/io/mat5_reader'
     end
-
-    autoload :Market, 'nmatrix/io/market.rb'
-    autoload :PointCloud, 'nmatrix/io/point_cloud.rb'
   end
 
   class << self
-    #
     # call-seq:
     #     load_matlab_file(path) -> Mat5Reader
     #
@@ -62,12 +70,10 @@ class NMatrix
     #   - +file_path+ -> The path to a version 5 .mat file.
     # * *Returns* :
     #   - A Mat5Reader object.
-    #
     def load_matlab_file(file_path)
       NMatrix::IO::Mat5Reader.new(File.open(file_path, 'rb')).to_ruby
     end
 
-    #
     # call-seq:
     #     load_pcd_file(path) -> PointCloudReader::MetaReader
     #
@@ -75,12 +81,10 @@ class NMatrix
     #   - +file_path+ -> The path to a PCL PCD file.
     # * *Returns* :
     #   - A PointCloudReader::MetaReader object with the matrix stored in its +matrix+ property
-    #
     def load_pcd_file(file_path)
       NMatrix::IO::PointCloudReader::MetaReader.new(file_path)
     end
 
-    #
     # Calculate the size of an NMatrix of a given shape.
     def size(shape)
       shape = [shape,shape] unless shape.is_a?(Array)
@@ -128,8 +132,6 @@ class NMatrix
       end
     end
   end
-  #alias :pp :pretty_print
-
 
   #
   # call-seq:
@@ -238,7 +240,6 @@ class NMatrix
   end
 
 
-  ##
   # call-seq:
   #   integer_dtype?() -> Boolean
   #
@@ -248,6 +249,26 @@ class NMatrix
     [:byte, :int8, :int16, :int32, :int64].include?(self.dtype)
   end
 
+  ##
+  # call-seq:
+  #   complex_dtype?() -> Boolean
+  #
+  # Checks if dtype is a complex type
+  #
+  def complex_dtype?
+    [:complex64, :complex128].include?(self.dtype)
+  end
+
+  ##
+  # call-seq:
+  #   complex_dtype?() -> Boolean
+  #
+  # Checks if dtype is a rational type
+  #
+  def rational_dtype?
+    [:rational32, :rational64, :rational128].include?(self.dtype)
+  end
+
 
   #
   # call-seq:
@@ -352,7 +373,7 @@ class NMatrix
   #
   # See @row (dimension = 0), @column (dimension = 1)
   def rank(shape_idx, rank_idx, meth = :copy)
-    
+
     if shape_idx > (self.dim-1)
       raise(RangeError, "#rank call was out of bounds")
     end
@@ -428,7 +449,6 @@ class NMatrix
     end
     t = reshape_clone_structure(newer_shape)
     left_params  = [:*]*newer_shape.size
-    puts(left_params)
     right_params = [:*]*self.shape.size
     t[*left_params] = self[*right_params]
     t
@@ -512,7 +532,6 @@ class NMatrix
   end
 
 
-  #
   # call-seq:
   #     matrix1.concat(*m2) -> NMatrix
   #     matrix1.concat(*m2, rank) -> NMatrix
@@ -520,20 +539,21 @@ class NMatrix
   #     matrix1.vconcat(*m2) -> NMatrix
   #     matrix1.dconcat(*m3) -> NMatrix
   #
-  # Joins two matrices together into a new larger matrix. Attempts to determine which direction to concatenate
-  # on by looking for the first common element of the matrix +shape+ in reverse. In other words, concatenating two
-  # columns together without supplying +rank+ will glue them into an n x 2 matrix.
+  # Joins two matrices together into a new larger matrix. Attempts to determine
+  # which direction to concatenate on by looking for the first common element
+  # of the matrix +shape+ in reverse. In other words, concatenating two columns
+  # together without supplying +rank+ will glue them into an n x 2 matrix.
   #
-  # You can also use hconcat, vconcat, and dconcat for the first three ranks. concat performs an hconcat when no
-  # rank argument is provided.
+  # You can also use hconcat, vconcat, and dconcat for the first three ranks.
+  # concat performs an hconcat when no rank argument is provided.
   #
   # The two matrices must have the same +dim+.
   #
   # * *Arguments* :
   #   - +matrices+ -> one or more matrices
-  #   - +rank+ -> Fixnum (for rank); alternatively, may use :row, :column, or :layer for 0, 1, 2, respectively
-  #
-  def concat *matrices
+  #   - +rank+ -> Fixnum (for rank); alternatively, may use :row, :column, or
+  #   :layer for 0, 1, 2, respectively
+  def concat(*matrices)
     rank = nil
     rank = matrices.pop unless matrices.last.is_a?(NMatrix)
 
@@ -587,15 +607,18 @@ class NMatrix
     n
   end
 
-  def hconcat *matrices
+  # Horizontal concatenation with +matrices+.
+  def hconcat(*matrices)
     concat(*matrices, :column)
   end
 
-  def vconcat *matrices
+  # Vertical concatenation with +matrices+.
+  def vconcat(*matrices)
     concat(*matrices, :row)
   end
 
-  def dconcat *matrices
+  # Depth concatenation with +matrices+.
+  def dconcat(*matrices)
     concat(*matrices, :layer)
   end
 

data/lib/nmatrix/rspec.rb

@@ -29,7 +29,7 @@
 require 'rspec'
 
 # Amend RSpec to allow #be_within for matrices.
-module RSpec::Matchers::BuiltIn #:nodoc:
+module RSpec::Matchers::BuiltIn
   class BeWithin
 
     def of(expected)
@@ -72,4 +72,4 @@ module RSpec::Matchers::BuiltIn #:nodoc:
     end
 
   end
-end
+end

data/lib/nmatrix/shortcuts.rb

@@ -34,29 +34,40 @@
 
 class NMatrix
 
-
-
-  #
   # call-seq:
-  #     dense? -> true or false
-  #     list? -> true or false
-  #     yale? -> true or false
-  #
-  # Shortcut functions for quickly determining a matrix's stype.
+  #     m.dense? -> true or false
   #
+  # Determine if +m+ is a dense matrix.
   def dense?; return stype == :dense; end
-  def yale?;  return stype == :yale;  end
-  def list?;  return stype == :list;  end
 
+  # call-seq:
+  #     m.yale? -> true or false
+  #
+  # Determine if +m+ is a Yale matrix.
+  def yale?;  return stype == :yale; end
+
+  # call-seq:
+  #     m.list? -> true or false
+  #
+  # Determine if +m+ is a list-of-lists matrix.
+  def list?;  return stype == :list; end
 
   class << self
-    #
     # call-seq:
-    #     NMatrix[array-of-arrays, dtype = nil]
+    #     NMatrix[Numeric, ..., Numeric, dtype: Symbol] -> NMatrix
+    #     NMatrix[Array, dtype: Symbol] -> NMatrix
+    #
+    # The default value for +dtype+ is guessed from the first parameter. For example:
+    #   NMatrix[1.0, 2.0].dtype # => :float64
+    #   NMatrix[1r, 2r].dtype   # => :rational64
     #
-    # You can use the old +N+ constant in this way:
+    # But this is just a *guess*. If the other values can't be converted to
+    # this dtype, a +TypeError+ will be raised.
+    #
+    # You can use the +N+ constant in this way:
     #   N = NMatrix
     #   N[1, 2, 3]
+    #
     # NMatrix needs to have a succinct way to create a matrix by specifying the
     # components directly. This is very useful for using it as an advanced
     # calculator, it is useful for learning how to use, for testing language
@@ -68,12 +79,16 @@ class NMatrix
     #
     # Examples:
     #
-    #   a = NMatrix[ 1,2,3,4 ]          =>  1.0  2.0  3.0  4.0
+    #   a = N[ 1,2,3,4 ]          =>  1  2  3  4
     #
-    #   a = NMatrix[ 1,2,3,4, dtype: :int32 ]  =>  1  2  3  4
+    #   a = N[ 1,2,3,4, :int32 ]  =>  1  2  3  4
     #
-    #   a = NMatrix[ [1,2,3], [3,4,5] ] =>  1.0  2.0  3.0
-    #                                       3.0  4.0  5.0
+    #   a = N[ [1,2,3], [3,4,5] ] =>  1.0  2.0  3.0
+    #                                 3.0  4.0  5.0
+    #
+    #   a = N[ 3,6,9 ].transpose => 3
+    #                               6
+    #                               9
     #
     # SYNTAX COMPARISON:
     #
@@ -83,7 +98,6 @@ class NMatrix
     #
     #   SciRuby:      a = NMatrix[ [1,2,3], [4,5,6] ]
     #   Ruby array:   a =  [ [1,2,3], [4,5,6] ]
-    #
     def [](*params)
       options = params.last.is_a?(Hash) ? params.pop : {}
 
@@ -159,7 +173,6 @@ class NMatrix
       NMatrix.new(shape, 1, {:dtype => :float64, :default => 1}.merge(opts))
     end
 
-    ##
     # call-seq:
     #   ones_like(nm) -> NMatrix
     #
@@ -173,7 +186,6 @@ class NMatrix
       NMatrix.ones(nm.shape, dtype: nm.dtype, stype: nm.stype, capacity: nm.capacity, default: 1)
     end
 
-    ##
     # call-seq:
     #   zeros_like(nm) -> NMatrix
     #
@@ -355,7 +367,7 @@ class NMatrix
   end
 end
 
-module NVector
+module NVector #:nodoc:
 
   class << self
     #
@@ -648,14 +660,19 @@ module NVector
 end
 
 
-# Use this constant as you would use NMatrix[].
+# This constant is intended as a simple constructor for NMatrix meant for
+# experimenting.
+#
 # Examples:
 #
-#   a = N[ 1,2,3,4 ]          =>  1.0  2.0  3.0  4.0
+#   a = N[ 1,2,3,4 ]          =>  1  2  3  4
 #
 #   a = N[ 1,2,3,4, :int32 ]  =>  1  2  3  4
 #
-#   a = N[ [1,2,3], [3,4,5] ] =>  1.0  2.0  3.0
-#                                 3.0  4.0  5.0
+#   a = N[ [1,2,3], [3,4,5] ] =>  1  2  3
+#                                 3  4  5
 #
+#   a = N[ 3,6,9 ].transpose => 3
+#                               6
+#                               9
 N = NMatrix

data/lib/nmatrix/version.rb

@@ -26,14 +26,14 @@ class NMatrix
   # Note that the format of the VERSION string is needed for NMatrix
   # native IO. If you change the format, please make sure that native
   # IO can still understand NMatrix::VERSION.
-  #VERSION = "0.1.0"
-  module VERSION
+  module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 1
     TINY = 0
-    PRE = "rc5"
+    # PRE = "rc5"
 
-    STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
+    STRING = [MAJOR, MINOR, TINY].compact.join(".")
+    #STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
   end
 end
 

data/nmatrix.gemspec

@@ -6,12 +6,12 @@ require 'nmatrix/version'
 Gem::Specification.new do |gem|
   gem.name = "nmatrix"
   gem.version = NMatrix::VERSION::STRING
-  gem.summary = "NMatrix is an experimental linear algebra library for Ruby, written mostly in C."
-  gem.description = "NMatrix is an experimental linear algebra library for Ruby, written mostly in C."
+  gem.summary = "NMatrix is a linear algebra library for Ruby"
+  gem.description = "NMatrix is a linear algebra library for Ruby, written mostly in C and C++."
   gem.homepage = 'http://sciruby.com'
   gem.authors = ['John Woods', 'Chris Wailes', 'Aleksey Timin']
   gem.email =  ['john.o.woods@gmail.com']
-  gem.license = 'BSD 2-clause'
+  gem.license = 'BSD 3-clause'
   gem.post_install_message = <<-EOF
 ***********************************************************
 Welcome to SciRuby: Tools for Scientific Computing in Ruby!
@@ -44,6 +44,7 @@ EOF
   gem.required_ruby_version = '>= 1.9'
 
   gem.add_dependency 'rdoc', '~>4.0', '>=4.0.1'
+  gem.add_dependency 'packable', '~> 1.3', '>= 1.3.5'
   gem.add_development_dependency 'rake', '~>10.3'
   gem.add_development_dependency 'bundler', '~>1.6'
   gem.add_development_dependency 'rspec', '~>2.14'

data/spec/03_nmatrix_monkeys_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe NMatrix do
+  describe "#to_a" do
+    it "creates an Array with the same dimensions" do
+      n = NMatrix.seq([3,2])
+      expect(n.to_a).to eq([[0, 1], [2, 3], [4, 5]])
+    end
+
+    it "creates an Array with the proper element type" do
+      n = NMatrix.seq([3,2], dtype: :float64)
+      expect(n.to_a).to eq([[0.0, 1.0], [2.0, 3.0], [4.0, 5.0]])
+    end
+
+    it "properly interprets list matrices" do
+      n = NMatrix.seq([3,2], stype: :list)
+      expect(n.to_a).to eq([[0, 1], [2, 3], [4, 5]])
+    end
+
+    it "properly interprets yale matrices" do
+      n = NMatrix.seq([3,2], stype: :yale)
+      expect(n.to_a).to eq([[0, 1], [2, 3], [4, 5]])
+    end
+  end
+end
+
+describe Array do
+  describe "#to_nm" do
+    # [0, 1, 2, 3, 4, 5]
+    let(:a) {(0..5).to_a}
+
+    it "uses a given shape and type" do
+      expect(a.to_nm([3,2]).dtype).to eq :int64
+      expect(a.to_nm([3,2])).to eq(NMatrix.seq([3,2]))
+    end
+
+    it "guesses dtype based on first element" do
+      a[0] = 0.0
+      expect(a.to_nm([3,2]).dtype).to eq :float64
+    end
+
+    it "defaults to dtype :object if necessary" do
+      a = %w(this is an array of strings)
+      expect(a.to_nm([3,2]).dtype).to eq :object
+      expect(a.to_nm([3,2])).to eq(NMatrix.new([3,2], a, dtype: :object))
+    end
+
+    it "attempts to intuit the shape of the Array" do
+      a = [[0, 1], [2, 3], [4, 5]]
+      expect(a.to_nm).to eq(NMatrix.new([3,2], a.flatten))
+      expect(a.to_nm.dtype).to eq :int64
+    end
+
+    it "creates an object Array for inconsistent dimensions" do
+      a = [[0, 1, 2], [3], [4, 5]]
+      expect(a.to_nm).to eq(NMatrix.new([3], a, dtype: :object))
+      expect(a.to_nm.dtype).to eq :object
+    end
+
+    it "intuits shape of Array into multiple dimensions" do
+      a = [[[0], [1]], [[2], [3]], [[4], [5]]]
+      expect(a.to_nm).to eq(NMatrix.new([3,1,2], a.flatten))
+      expect(a).to eq(a.to_nm.to_a)
+    end
+
+    it "is reflective with NMatrix#to_a" do
+      a = [[0, 1, 2], [3], [4, 5]]
+      expect(a).to eq(a.to_nm.to_a)
+    end
+  end
+end
+