csrmatrix 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5239814e3bf4d761150bacbe7d8fa44ca321446d
-  data.tar.gz: 6f72c0b95e218e513b7372e1264054ea33c36ad2
+  metadata.gz: 842f69d5be23f5b6a2ea2057504f416eff0648f8
+  data.tar.gz: f05e25a4c9f740e9691e94bc3aeb6b4a476be910
 SHA512:
-  metadata.gz: 0f1313cec202a6ca9d303229629615d0422342847e1b1f1e446c704f806b1aecf574c2945ae51e93158387dba3a020e992f9e3983b4aafa7d23b911060b9a566
-  data.tar.gz: 1734545e1f6a6f2387466768bd62896757935deb648f002077e84bce4b972928f67c5a7af678cd8ad503fbe0d1300bc33b820b83fcd35296305dbdb04bfc16e4
+  metadata.gz: 767ba6ea5d5bdad6e30e986c052f93b6bd9b3822f28ee98326b132bc9010c01e3a17241ed7fe7ba558395e8853aca3fe9fd782ff36efa77fd43b0fbab825fd7c
+  data.tar.gz: 73afd742117835704942a8cf5202a1cbbd9e3c8eecf013709957191707ca38b9a5574e56082477d7ab6491b95cea71049718a4145699bfc1636c21029a83acfa

data/Gemfile

@@ -2,5 +2,6 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in matrix.gemspec
 gem "minitest"
+gem "contracts"
 
 gemspec

data/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: .
   specs:
-    csrmatrix (1.0.0)
+    csrmatrix (1.0.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    contracts (0.13.0)
     diff-lcs (1.2.5)
     minitest (5.8.3)
     rake (10.5.0)
@@ -28,6 +29,7 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.11)
+  contracts
   csrmatrix!
   minitest
   rake (~> 10.0)

data/README.md

@@ -22,7 +22,112 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+## Usage
+#### Construction
+
+Start by building the matrix object. This will be a simple shell, on which we can perform our operations on:
+
+```ruby 
+@matrix = TwoDMatrix.new
+ => #<TwoDMatrix:0x007fa5b2083ba8 @nonzero_count=nil, @row_ptr=nil, @col_ind=nil, @val=nil, @rows=0, @columns=0, @ndim=2> 
+```
+
+Then, we can fill it out using a variety of manners - either building the functions from arrays:
+
+```ruby 
+@matrix.build_from_array([[1, 2, 3], [1, 2, 3], [1, 2, 3]]) 
+@matrix.build_from_rows([[1, 2, 3], [1, 2, 3], [1, 2, 3]])
+@matrix.build_from_columns([[1, 2, 3], [1, 2, 3], [1, 2, 3]]) 
+@matrix.build_from_csr([0, 3, 6, 9],[0, 1, 2, 0, 1, 2, 0, 1, 2],[1, 2, 3, 1, 2, 3, 1, 2, 3],3,3)
+```
+
+Or from an existing matrix using Ruby's matrix library:
+```ruby
+@MatrixBuild = Matrix.rows([[1, 2, 3], [1, 2, 3], [1, 2, 3]])
+@matrix.build_from_matrix(@MatrixBuild)
+```
+
+Or by generating a zero or identity matrix:
+```ruby
+@matrix.build_zero_matrix(3, 2)
+@matrix.build_identity_matrix(3)
+```
+
+For more experienced users, build calls can be generated using keywords:
+```ruby
+@matrix.build("rows", [[1, 2, 3], [1, 2, 3], [1, 2, 3]])
+@matrix.build("columns", [[1, 2, 3], [1, 2, 3], [1, 2, 3]])
+@matrix.build("identity", 3) #rows, columns are same
+@matrix.build("zero", 2) #rows, columns
+@matrix.build("csr", [[0, 3, 6, 9],[0, 1, 2, 0, 1, 2, 0, 1, 2],[1, 2, 3, 1, 2, 3, 1, 2, 3],3,3])
+@matrix.build("array", [[1, 2, 3], [1, 2, 3], [1, 2, 3]])
+@matrix.build("matrix", @MatrixBuild)
+```
+
+#### Properties 
+CsrMatrix offers many property checks for matrices. Test the system by using the following code:
+```ruby
+@matrixTrigonal3x3.diagonal?
+```
+
+The list of usable properties, as of this point, are as follows:
+```ruby
+.diagonal? .empty? .lower_triangular? .normal? .orthogonal? .permutation? .real? .nonsingular? .singular? .square? .symmetric? .unitary? .upper_ .triangular? .zero?
+```
+
+#### Arithmetic
+CsrMatrix offers the full suite of standard arithmetic processes for matrices. With regards to scalar operations:
+```ruby
+@matrixConst.scalar_multiply(2)
+@matrixConst.scalar_add(2)
+@matrixConst.scalar_subtract(1)
+@matrixConst.scalar_division(2)
+@matrixConst.scalar_exp(2)
+```
+
+As for matrix-to-matrix processes:
+```ruby 
+@matrixa.multiply_csr(@matrixb)
+@matrixa.matrix_add(@matrixb)
+@matrixa.is_same_dim(@matrixb)
+@matrixa.matrix_add(@matrixb)
+@matrixa.matrix_subtract(@matrixb)
+@matrixa.matrix_inverse_multiply(@matrixd)
+@matrixa.matrix_multiply_inverse(@matrixd)
+@matrixa.matrix_division(@matrixd)
+```
+
+And for others:
+```ruby 
+@matrixConst.inverse()
+@matrixConst.transpose()
+```
+
+#### Other
+CsrMatrix offers standard display and assorted property assertion functions for your sparse matrix:
+
+```ruby 
+@matrixSparse3x3.print_full()
+@matrixSparse3x3.print_sparse()
+@matrixSparse3x3.get_value(4)
+@matrixSparse3x3.index(1,1)
+@matrixSparse3x3.det()
+@matrixSparse3x3.determinant()
+@matrixSparse3x3.rank()
+@matrixFloat2x2.decompose()
+@matrixDense3x3.trace()
+@matrixDense3x3.tr()
+@matrixSparse3x3.transpose()
+@matrixSparse3x3.t()
+```
+
+#### Exporting CsrMatrix
+If you would like to integrate the matrix with your other code, you can simply disassemble it and reconstruct it at your leisure:
+
+```ruby
+@matrix.decompose()
+@matrix.decomp_to_matrix()
+```
 
 ## Development
 

data/lib/csrmatrix/arithmetic.rb

@@ -1,91 +1,130 @@
 require "matrix"
 require "csrmatrix/exceptions"
+require "contracts"
+require "csrmatrix/mcontracts"
 
 module CsrMatrix    
   module Arithmetic
+    include Contracts::Core
+    C = Contracts
 
+    # Brings in exception module for exception testing
     def self.included(exceptions)
       exceptions.send :include, Exceptions
     end
 
-    # class MatrixDimException < StandardError; end      
-    # class ArgumentNullException < StandardError; end
-    # class MatrixTypeException < StandardError; end     
-
-    # REFERENCE: To use module functions in module
-    # Class.new.extend(Decompositions).lup()
-
+    Contract C::Num => C::ArrayOf[C::Num]
     def scalar_multiply(value)
-      if value == nil
-        raise ArgumentNullException.new, "Multiply by nil error."
-        return false
-      end
+      # multiply the matrix by a scalar value
+      is_invariant?
+
       @val.each_index do |i|
         @val[i] = @val[i] * value
       end
-    end
+    end # scalar_multiply
     
+    Contract C::Num => C::ArrayOf[C::Num]
     def scalar_add(value)
-      if value == nil
-        raise ArgumentNullException.new, "Add by nil error."
-        return false
-      end
-      # create an identity matrix with the value
-      # matrix_add the new identity matrix to the given matrix
+      # manipulate the matrix by adding a value at each index
+      is_invariant?
+
       @val.each_index do |i|
         @val[i] = @val[i] + value
       end
-    end
+    end # scalar_add
 
+    Contract C::Num => C::ArrayOf[C::Num]
     def scalar_subtract(value)
-      if value == nil
-        raise ArgumentNullException.new, "Subtract by nil error."
-        return false
-      end
-      # create an identity matrix with the value
-      # matrix_subtract the new identity matrix to the given matrix
+      is_invariant? 
+      
+      # manipulate the matrix by subtracting the value at each index
       @val.each_index do |i|
         @val[i] = @val[i] - value
       end
-    end
+    end # scalar_subtract
 
+    Contract C::Num => C::ArrayOf[C::Or[Float, Float]]
     def scalar_division(value)
-      if value == nil
-        raise ArgumentNullException.new, "Divide by nil error."
-        return false
-      end
+      is_invariant?
+      # manipulate the matrix by dividing the value at each index
+      # post  boolean, updated matrix (in floats, if previously was not)
       @val.each_index do |i|
         @val[i] = @val[i] / value.to_f
       end
-    end
+    end # scalar_division
 
+    Contract C::Num => C::ArrayOf[C::Num]
     def scalar_exp(value)
-      if value == nil
-        raise ArgumentNullException.new, "Exp. by nil error."
-        return false
-      end
+      is_invariant?
+      # manipulate the matrix by finding the exponential at each index
       @val.each_index do |i|
         @val[i] = @val[i] ** value
       end
-    end
+    end # scalar_exp
 
+    Contract C::Num => C::Bool
     def inverse()
+      is_invariant?
+      # sets the inverse of this matrix
+      # pre   existing matrix (matrix.not_null?)
+      # post  inverted matrix
       m = Matrix.rows(self.decompose)
       self.build_from_array(m.inv().to_a())
-    end
+    end # inverse
 
-    # FIXME: Convert with CSR functions
+    Contract C::None => C::ArrayOf[C::Num]
     def transpose()
-      m = Matrix.rows(self.decompose)
-      self.build_from_array(m.transpose.to_a())
-    end
+      is_invariant?
+      # transpose the matrix 
+
+			new_row_ptr = Array.new(self.columns+1, 0)
+			new_col_ind = Array.new(self.col_ind.count(), 0)
+			new_val = Array.new(self.val.count(), 0)
+			current_row = 0
+			current_column = 0
+	
+			for i in 0..self.columns-1
+				for j in 0..self.col_ind.count(i)-1
+					# get the row
+					index = self.col_ind.find_index(i)
+					self.col_ind[index] = -1
+					for k in 1..self.row_ptr.count()-1
+						if self.row_ptr[k-1] <= index && index < self.row_ptr[k]
+							current_row = k
+							break
+						end
+					end
+
+					# update values
+					new_row_ptr[i+1] += 1
+					new_val[current_column] = val[index]
+					new_col_ind[current_column] = current_row-1
+					current_column += 1
+				end
+			end
 
+			# fill in row_ptr
+			for i in 1..self.rows-1
+				self.row_ptr[i] = new_row_ptr[i] + new_row_ptr[i-1]
+			end	
+
+			@col_ind = new_col_ind
+			@val = new_val
+    end # transpose
+
+    Contract C::None => C::ArrayOf[C::Num]
     def t()
-      self.transpose()
-    end
+      is_invariant?
+      # transpose the matrix 
+      # post  array of decomposed matrix values
+			self.transpose()
+    end # t
 
+    Contract C::Num => C::ArrayOf[C::Num]
     def matrix_vector(vector) 
       # dev based on http://www.mathcs.emory.edu/~cheung/Courses/561/Syllabus/3-C/sparse.html
+      # multiplies the matrix by a vector value (in array form)
+      is_invariant?
       result = Array.new(vector.length, 0)
       i = 0
       while i < vector.length do
@@ -97,13 +136,15 @@ module CsrMatrix
         i += 1
       end   
       return result
-    end   
+    end # matrix_vector
 
     # dev based on http://stackoverflow.com/questions/29598299/csr-matrix-matrix-multiplication
-    # multiply dense (non-dense) matrix to csr matrix [eg. [1, 2]] x 2d array
-    # key: the dense matrix is LEFT SIDE, the csr matrix is RIGHT SIDE
+    Contract C::ArrayOf[C::ArrayOf[C::Num]] => C::ArrayOf[C::ArrayOf[C::Num]]
     def matrix_multiply(matrix)
-      # matrix order, assumes both matrices are square
+      # multiply dense (non-dense) matrix to csr matrix [eg. [1, 2]] x 2d array
+      is_invariant?
+      # pre   matrix to multiply, existing matrix (matrix.not_null?)
+      # post  array holding resulting matrix
       res = Array.new(max_row(matrix)) { Array.new(@columns, 0) } # first denotes row, second denotes columns
       n = matrix.length
       i = 0
@@ -128,114 +169,169 @@ module CsrMatrix
         i += 1
       end
       return res
-    end
+    end # matrix_multiply
 
-    # multiply two csr together - ref: http://www.mcs.anl.gov/papers/P5007-0813_1.pdf
+    Contract MContracts::TwoDMatrixType => C::ArrayOf[C::ArrayOf[C::Num]]
     def multiply_csr(matrix)
+      # multiply two csr together - ref: http://www.mcs.anl.gov/papers/P5007-0813_1.pdf
+      is_invariant?
       return matrix.matrix_multiply(self.decompose())
-    end 
+    end # multiply_csr
 
-    # helper function to determine deim count is equal
+    Contract MContracts::TwoDMatrixType => C::Bool
     def is_same_dim(matrix)
+      # helper function to determine dim count is equal
+      is_invariant?
       return self.dimensions() == matrix.dimensions()
-    end
+    end # is_same_dim
 
+    Contract MContracts::TwoDMatrixType => C::ArrayOf[C::ArrayOf[C::Num]]
     def matrix_add(matrix)
-      if self.is_same_dim(matrix)
-        res = Array.new(@rows) { Array.new(@columns, 0) }
-        row_idx = 0
-        cnta = 0 # total logged entries for matrix a 
-        cntb = 0
-        while row_idx < @rows # eg. 0 1 2
-          rowa = @row_ptr[row_idx + 1] # eg. 0 2 4 7
-          rowb = matrix.row_ptr[row_idx + 1]
-          while cnta < rowa
-            # keep adding values to res until they're equal
-            res[row_idx][@col_ind[cnta]] += @val[cnta]
-            cnta += 1;
-          end
-          while cntb < rowb
-            res[row_idx][@col_ind[cntb]] += matrix.val[cntb]
-            cntb += 1;
-          end  
-          row_idx += 1;
-        end
-        return res
-      end 
-      raise Exceptions::MatrixDimException.new, "Matrix does not have same dimensions; cannot add."
-      return false
-    end
+      # adds a matrix to existing matrix
+      is_invariant?
+      if !self.is_same_dim(matrix)
+        raise Exceptions::MatrixDimException.new, "Matrix does not have same dimensions; cannot add."
+        return false
+      end
 
-    def matrix_subtract(matrix)
-      if self.is_same_dim(matrix)
-        res = Array.new(@rows) { Array.new(@columns, 0) }
-        row_idx = 0
-        cnta = 0 # total logged entries for matrix a 
-        cntb = 0
-        while row_idx < @rows # eg. 0 1 2
-          rowa = @row_ptr[row_idx + 1] # eg. 0 2 4 7
-          rowb = matrix.row_ptr[row_idx + 1]
-          while cnta < rowa
-            # keep adding values to res until they're equal
-            res[row_idx][@col_ind[cnta]] += @val[cnta]
-            cnta += 1;
-          end
-          while cntb < rowb
-            res[row_idx][@col_ind[cntb]] -= matrix.val[cntb]
-            cntb += 1;
-          end  
-          row_idx += 1;
+      res = Array.new(@rows) { Array.new(@columns, 0) }
+      row_idx = 0
+      cnta = 0 # total logged entries for matrix a 
+      cntb = 0
+      while row_idx < @rows # eg. 0 1 2
+        rowa = @row_ptr[row_idx + 1] # eg. 0 2 4 7
+        rowb = matrix.row_ptr[row_idx + 1]
+        while cnta < rowa
+          # keep adding values to res until they're equal
+          res[row_idx][@col_ind[cnta]] += @val[cnta]
+          cnta += 1;
         end
-        return res
-      end 
-      raise Exceptions::MatrixDimException.new, "Matrix does not have same dimensions; cannot subtract."
-      return false
-    end
+        while cntb < rowb
+          res[row_idx][@col_ind[cntb]] += matrix.val[cntb]
+          cntb += 1;
+        end  
+        row_idx += 1;
+      end
+      return res
+    end # matrix_add
 
-    # multiply y by x^-1; y * x^-1
-    # FIXME: Possibly consider rewording for context:
-    def matrix_left_division(matrix)
-      if !matrix.is_a?(TwoDMatrix)
-        raise Exceptions::MatrixTypeException.new, "Matrix is not usable type."
+    Contract MContracts::TwoDMatrixType => C::ArrayOf[C::ArrayOf[C::Num]]
+    def matrix_subtract(matrix)
+      # subtracts a matrix to existing matrix
+      is_invariant?
+      if !self.is_same_dim(matrix)
+        raise Exceptions::MatrixDimException.new, "Matrix does not have same dimensions; cannot subtract."
         return false
       end
+
+      res = Array.new(@rows) { Array.new(@columns, 0) }
+      row_idx = 0
+      cnta = 0 # total logged entries for matrix a 
+      cntb = 0
+      while row_idx < @rows # eg. 0 1 2
+        rowa = @row_ptr[row_idx + 1] # eg. 0 2 4 7
+        rowb = matrix.row_ptr[row_idx + 1]
+        while cnta < rowa
+          # keep adding values to res until they're equal
+          res[row_idx][@col_ind[cnta]] += @val[cnta]
+          cnta += 1;
+        end
+        while cntb < rowb
+          res[row_idx][@col_ind[cntb]] -= matrix.val[cntb]
+          cntb += 1;
+        end  
+        row_idx += 1;
+      end
+      return res
+    end # matrix_subtract
+
+    Contract MContracts::TwoDMatrixType => C::ArrayOf[C::ArrayOf[C::Num]]
+    def multiply_inverse(matrix)
+      # divides (multiply by the inverse of ) a matrix to existing matrix
+      # sets y * x^-1, where x is your matrix and y is the accepted matrix
+      is_invariant?
       if !matrix.square? || !self.square?
         raise Exceptions::MatrixDimException.new, "Matrices does not have usable dimensions; cannot divide."
         return false
       end
+
       tmpmatrix = TwoDMatrix.new
       tmpmatrix = matrix
       tmpmatrix.inverse()
       return self.multiply_csr(tmpmatrix)
-    end
+    end # matrix_inverse
 
     # multiply x by y^-1; x * y^-1 
-    # FIXME: Possibly consider rewording for context: not doing x / y; doing x * y^-1
-    def matrix_right_division(matrix)
-      if !matrix.is_a?(TwoDMatrix)
-        raise Exceptions::MatrixTypeException.new, "Matrix is not usable type."
-        return false
-      end
+    Contract MContracts::TwoDMatrixType => C::ArrayOf[C::ArrayOf[C::Num]]
+    def inverse_multiply(matrix)
+      # divides (multiply by the inverse of ) a matrix to existing matrix
+      # sets x * y^-1, where x is your matrix and y is the accepted matrix
+      is_invariant?
       if !matrix.square? || !self.square?
         raise Exceptions::MatrixDimException.new, "Matrices does not have usable dimensions; cannot divide."
         return false
       end
+
       tmpmatrix = TwoDMatrix.new
       tmpmatrix = self
       tmpmatrix.inverse()
       return matrix.multiply_csr(tmpmatrix)
+    end # inverse_multiply
+
+    Contract C::None => C::Num
+    def count_in_dim()
+      is_invariant?
+      # helper function, identifies the number of expected values in matrix
+      # eg. 2x2 matrix returns 4 values
+      return self.rows * self.columns
     end
 
-    # Identifies the 'row' value of an array (eg. the number of entries in a row)
-    # Helper function, will clean after.
+    Contract MContracts::TwoDMatrixType => C::ArrayOf[C::ArrayOf[C::Num]]
+    def matrix_division(matrix)
+      # linear division of one matrix to the next
+      is_invariant?
+      if matrix.val.count() != matrix.count_in_dim()
+        raise Exceptions::DivideByZeroException.new, "Calculations return divide by zero error."
+        return false
+      end 
+      if !self.is_same_dim(matrix)
+        raise Exceptions::MatrixDimException.new, "Matrix does not have same dimensions; cannot add."
+        return false
+      end
+
+      res = Array.new(@rows) { Array.new(@columns, 0) }
+      row_idx = 0
+      cnta = 0 # total logged entries for matrix a 
+      cntb = 0
+      while row_idx < @rows # eg. 0 1 2
+        rowa = @row_ptr[row_idx + 1] # eg. 0 2 4 7
+        rowb = matrix.row_ptr[row_idx + 1]
+        while cnta < rowa
+          # keep adding values to res until they're equal
+          res[row_idx][@col_ind[cnta]] += @val[cnta]
+          cnta += 1;
+        end
+        while cntb < rowb
+          res[row_idx][@col_ind[cntb]] = res[row_idx][@col_ind[cntb]].to_f / matrix.val[cntb]
+          cntb += 1;
+        end  
+        row_idx += 1;
+      end
+      return res
+    end # matrix_division
+
+    Contract C::ArrayOf[C::Num] => C::Nat
     def max_row(array)
+      # Identifies the 'row' value of an array (eg. the number of entries in a row)
+      is_invariant?
+      
       values = array
       max_count = 0
       values.each_index do |i|
         max_count += 1
       end
       return max_count
-    end
+    end # max_row
 
-  end 
-end
+  end # Arithmetic
+end # CsrMatrix

data/lib/csrmatrix/decompositions.rb

@@ -1,22 +1,24 @@
 module CsrMatrix
-    module Decompositions
+	module Decompositions
+		include Contracts::Core
+    C = Contracts
 
-        def eigen()
-            eigensystem()
-        end
-        
-        def eigensystem()
-            m = Matrix.rows(self.decompose)
-            return m.eigensystem().to_a[0].to_a
-        end
-        
-        def lup()
-            puts "lup"
-        end
-        
-        def lup_decomposition()
-
-        end
-        
-    end
-end
+    Contract C::None => C::ArrayOf[C::ArrayOf[C::Num]]
+		def eigen()
+			# alias for eigensystem
+			# returns a list in the form {eigenvalues, eigenvectors}
+			is_invariant?
+			
+  		self.eigenvalue()
+		end # eigen
+      
+    Contract C::None => C::ArrayOf[C::ArrayOf[C::Num]]
+		def eigenvalue()
+			# identifies the eigenvalues of a matrix
+			is_invariant?
+			# post 	eigenvalues of the matrix
+			m = Matrix.rows(self.decompose)
+			return m.eigensystem().to_a[1].round().to_a
+		end # eigenvalue
+  end # Decompositions
+end # CsrMatrix

data/lib/csrmatrix/exceptions.rb

@@ -1,11 +1,24 @@
 module CsrMatrix
     module Exceptions
-        class NullMatrixException < StandardError; end     
+        # Occurs when user enters a null matrix for processing.
+        class NullMatrixException < StandardError; end 
+
+        # Occurs when a sparse matrix operation occurs wherein its dimensions result in the operation being unavailable.   
         class MatrixDimException < StandardError; end      
-        class ArithmeticException < StandardError; end     
-        class MatrixTypeException < StandardError; end     
+
+        # Occurs when the matrix builder expects a specific type; and is provided the wrong type to generate the sparse matrix.
+        class MatrixTypeException < StandardError; end 
+
+        # Occurs when the system divides by 0; standard arithmetic error.    
         class DivideByZeroException < StandardError; end   
+
+        # Occurs when index queried is out of range of the matrix.
         class IndexOutOfRangeException < StandardError; end
+        
+        # Occurs when the sparse matrix is used in processing against a null / nil value.
         class ArgumentNullException < StandardError; end   
-    end
-end
+
+        #
+        class InvariantError < StandardError; end 
+    end # exceptions
+end # csrmatrix