nmatrix 0.0.3 → 0.0.4

data/lib/nmatrix/nmatrix.rb

@@ -1,3 +1,4 @@
+#--
 # = NMatrix
 #
 # A linear algebra library for scientific computation in Ruby.
@@ -8,8 +9,8 @@
 #
 # == Copyright Information
 #
-# SciRuby is Copyright (c) 2010 - 2012, Ruby Science Foundation
-# NMatrix is Copyright (c) 2012, Ruby Science Foundation
+# SciRuby is Copyright (c) 2010 - 2013, Ruby Science Foundation
+# NMatrix is Copyright (c) 2013, Ruby Science Foundation
 #
 # Please see LICENSE.txt for additional copyright notices.
 #
@@ -24,20 +25,15 @@
 #
 # This file adds a few additional pieces of functionality (e.g., inspect,
 # pretty_print).
-
-############
-# Requires #
-############
+#++
 
 require_relative './shortcuts.rb'
-
-#######################
-# Classes and Modules #
-#######################
+require_relative './lapack.rb'
 
 class NMatrix
-	# Read and write extensions for NMatrix. These are only loaded when needed.
-	module IO
+  # Read and write extensions for NMatrix. These are only loaded when needed.
+  #
+  module IO
     module Matlab
       class << self
         def load_mat file_path
@@ -54,10 +50,9 @@ class NMatrix
     autoload :Market, 'nmatrix/io/market'
   end
 
-
-	# TODO: Make this actually pretty.
-	def pretty_print(q = nil)
-		if dim != 2 || (dim == 2 && shape[1] > 10) # FIXME: Come up with a better way of restricting the display
+  # TODO: Make this actually pretty.
+  def pretty_print(q = nil) #:nodoc:
+    if dim != 2 || (dim == 2 && shape[1] > 10) # FIXME: Come up with a better way of restricting the display
       inspect
     else
 
@@ -65,17 +60,17 @@ class NMatrix
         ary = []
         (0...shape[1]).each do |j|
           o = begin
-            self[i, j]
-          rescue ArgumentError
-            nil
-          end
+                self[i, j]
+              rescue ArgumentError
+                nil
+              end
           ary << (o.nil? ? 'nil' : o)
         end
         ary.inspect
       end
 
       if q.nil?
-        puts arr.join("\n")
+        puts "[" + arr.join("\n") + "]"
       else
         q.group(1, "", "\n") do
           q.seplist(arr, lambda { q.text "  " }, :each)  { |v| q.text v.to_s }
@@ -83,21 +78,64 @@ class NMatrix
       end
 
     end
-	end
-	alias :pp :pretty_print
+  end
+  alias :pp :pretty_print
 
-  # These shortcuts use #shape to return the number of rows and columns.
+  #
+  # call-seq:
+  #     rows -> Integer
+  #
+  # This shortcut use #shape to return the number of rows (the first dimension)
+  # of the matrix.
+  #
   def rows
     shape[0]
   end
-  
+
+  #
+  # call-seq:
+  #     cols -> Integer
+  #
+  # This shortcut use #shape to return the number of columns (the second
+  # dimension) of the matrix.
+  #
   def cols
     shape[1]
   end
 
-  # Use LAPACK to calculate the inverse of the matrix (in-place). Only works on dense matrices.
+  #
+  # call-seq:
+  #     to_hash -> Hash
+  #
+  # Create a Ruby Hash from an NMatrix.
+  #
+  def to_hash
+    if stype == :yale
+      h = {}
+      each_stored_with_indices do |val,i,j|
+        next if val == 0 # Don't bother storing the diagonal zero values -- only non-zeros.
+        if h.has_key?(i)
+          h[i][j] = val
+        else
+          h[i] = {j => val}
+        end
+      end
+      h
+    else # dense and list should use a C internal functions.
+      to_hash_c
+    end
+  end
+  alias :to_h :to_hash
+
+  #
+  # call-seq:
+  #     invert! -> NMatrix
+  #
+  # Use LAPACK to calculate the inverse of the matrix (in-place). Only works on
+  # dense matrices.
   #
   # Note: If you don't have LAPACK, e.g., on a Mac, this may not work yet.
+  #
   def invert!
     # Get the pivot array; factor the matrix
     pivot = self.getrf!
@@ -108,33 +146,64 @@ class NMatrix
     self
   end
 
-  # Make a copy of the matrix, then invert it (requires LAPACK). Returns a dense matrix.
+  #
+  # call-seq:
+  #     invert -> NMatrix
+  #
+  # Make a copy of the matrix, then invert it (requires LAPACK).
+  #
+  # * *Returns* :
+  #   - A dense NMatrix.
+  #
   def invert
     self.cast(:dense, self.dtype).invert!
   end
-
   alias :inverse :invert
 
-  # Calls clapack_getrf and returns the pivot array (dense only).
+  #
+  # call-seq:
+  #     getrf! -> NMatrix
+  #
+  # LU factorization of a general M-by-N matrix +A+ using partial pivoting with
+  # row interchanges. Only works in dense matrices.
+  #
+  # * *Returns* :
+  #   - The IPIV vector. The L and U matrices are stored in A.
+  # * *Raises* :
+  #   - +StorageTypeError+ -> ATLAS functions only work on dense matrices.
+  #
   def getrf!
     raise(StorageTypeError, "ATLAS functions only work on dense matrices") unless self.stype == :dense
     NMatrix::LAPACK::clapack_getrf(:row, self.shape[0], self.shape[1], self, self.shape[0])
   end
 
-  # Calculate the determinant by way of LU decomposition. This is accomplished using
-  # clapack_getrf, and then by summing the diagonal elements. There is a risk of
-  # underflow/overflow.
   #
-  # There are probably also more efficient ways to calculate the determinant. This method
-  # requires making a copy of the matrix, since clapack_getrf modifies its input.
+  # call-seq:
+  #     det -> determinant
+  #
+  # Calculate the determinant by way of LU decomposition. This is accomplished
+  # using clapack_getrf, and then by summing the diagonal elements. There is a
+  # risk of underflow/overflow.
+  #
+  # There are probably also more efficient ways to calculate the determinant.
+  # This method requires making a copy of the matrix, since clapack_getrf
+  # modifies its input.
+  #
+  # For smaller matrices, you may be able to use +#det_exact+.
   #
-  # For smaller matrices, you may be able to use det_exact.
+  # This function is guaranteed to return the same type of data in the matrix
+  # upon which it is called.
+  # In other words, if you call it on a rational matrix, you'll get a rational
+  # number back.
   #
-  # This function is guaranteed to return the same type of data in the matrix upon which it is called.
-  # In other words, if you call it on a rational matrix, you'll get a rational number back.
+  # Integer matrices are converted to rational matrices for the purposes of
+  # performing the calculation, as xGETRF can't work on integer matrices.
+  #
+  # * *Returns* :
+  #   - The determinant of the matrix. It's the same type as the matrix's dtype.
+  # * *Raises* :
+  #   - +NotImplementedError+ -> Must be used in 2D matrices.
   #
-  # Integer matrices are converted to rational matrices for the purposes of performing the calculation,
-  # as xGETRF can't work on integer matrices.
   def det
     raise(NotImplementedError, "determinant can be calculated only for 2D matrices") unless self.dim == 2
 
@@ -142,7 +211,8 @@ class NMatrix
     new_dtype = [:byte,:int8,:int16,:int32,:int64].include?(self.dtype) ? :rational128 : self.dtype
     copy = self.cast(:dense, new_dtype)
 
-    # Need to know the number of permutations. We'll add up the diagonals of the factorized matrix.
+    # Need to know the number of permutations. We'll add up the diagonals of
+    # the factorized matrix.
     pivot = copy.getrf!
 
     prod = pivot.size % 2 == 1 ? -1 : 1 # odd permutations => negative
@@ -154,72 +224,106 @@ class NMatrix
     new_dtype != self.dtype ? prod.to_i : prod
   end
 
+  #
+  # call-seq:
+  #     complex_conjugate -> NMatrix
+  #     complex_conjugate(new_stype) -> NMatrix
+  #
+  # Get the complex conjugate of this matrix. See also complex_conjugate! for
+  # an in-place operation (provided the dtype is already +:complex64+ or
+  # +:complex128+).
+  #
+  # Doesn't work on list matrices, but you can optionally pass in the stype you
+  # want to cast to if you're dealing with a list matrix.
+  #
+  # * *Arguments* :
+  #   - +new_stype+ -> stype for the new matrix.
+  # * *Returns* :
+  #   - If the original NMatrix isn't complex, the result is a +:complex128+ NMatrix. Otherwise, it's the original dtype.
+  #
+  def complex_conjugate(new_stype = self.stype)
+    self.cast(new_stype, NMatrix::upcast(dtype, :complex64)).complex_conjugate!
+  end
+
+  #
+  # call-seq:
+  #     conjugate_transpose -> NMatrix
+  #
+  # Calculate the conjugate transpose of a matrix. If your dtype is already
+  # complex, this should only require one copy (for the transpose).
+  #
+  # * *Returns* :
+  #   - The conjugate transpose of the matrix as a copy.
+  #
+  def conjugate_transpose
+    self.transpose.complex_conjugate!
+  end
+
+  #
+  # call-seq:
+  #     hermitian? -> Boolean
+  #
+  # A hermitian matrix is a complex square matrix that is equal to its
+  # conjugate transpose. (http://en.wikipedia.org/wiki/Hermitian_matrix)
+  #
+  # * *Returns* :
+  #   - True if +self+ is a hermitian matrix, nil otherwise.
+  #
+  def hermitian?
+    return false if self.dim != 2 or self.shape[0] != self.shape[1]
+
+    if [:complex64, :complex128].include?(self.dtype)
+      # TODO: Write much faster Hermitian test in C
+      self.eql?(self.conjugate_transpose)
+    else
+      symmetric?
+    end
+  end
+
+  def inspect #:nodoc:
+    original_inspect = super()
+    original_inspect = original_inspect[0...original_inspect.size-1]
+    original_inspect + " " + inspect_helper.join(" ") + ">"
+  end
+
+  def __yale_ary__to_s(sym) #:nodoc:
+    ary = self.send("__yale_#{sym.to_s}__".to_sym)
 
-	# Get the complex conjugate of this matrix. See also complex_conjugate! for
-	# an in-place operation (provided the dtype is already :complex64 or
-	# :complex128).
-	#
-	# Does not work on list matrices, but you can optionally pass in the type you
-	# want to cast to if you're dealing with a list matrix.
-	def complex_conjugate(new_stype = self.stype)
-		self.cast(new_stype, NMatrix::upcast(dtype, :complex64)).complex_conjugate!
-	end
-
-	# Calculate the conjugate transpose of a matrix. If your dtype is already
-	# complex, this should only require one copy (for the transpose).
-	def conjugate_transpose
-		self.transpose.complex_conjugate!
-	end
-
-	def hermitian?
-		return false if self.dim != 2 or self.shape[0] != self.shape[1]
-		
-		if [:complex64, :complex128].include?(self.dtype)
-			# TODO: Write much faster Hermitian test in C
-			self.eql?(self.conjugate_transpose)
-		else
-			symmetric?
-		end
-	end
-
-	def inspect
-		original_inspect = super()
-		original_inspect = original_inspect[0...original_inspect.size-1]
-		original_inspect + inspect_helper.join(" ") + ">"
-	end
-
-	def __yale_ary__to_s(sym)
-		ary = self.send("__yale_#{sym.to_s}__".to_sym)
-		
-		'[' + ary.collect { |a| a ? a : 'nil'}.join(',') + ']'
-	end
-
-	class << self
-		def load_file(file_path)
-			NMatrix::IO::Mat5Reader.new(File.open(file_path, 'rb')).to_ruby
-		end
-
-	end
-
-protected
-	def inspect_helper
-		ary = []
-		ary << "shape:[#{shape.join(',')}]" << "dtype:#{dtype}" << "stype:#{stype}"
-
-		if stype == :yale
-			ary <<	"capacity:#{capacity}"
+    '[' + ary.collect { |a| a ? a : 'nil'}.join(',') + ']'
+  end
+
+  class << self
+    #
+    # call-seq:
+    #     load_file(path) -> Mat5Reader
+    #
+    # * *Arguments* :
+    #   - +path+ -> The path to a version 5 .mat file.
+    # * *Returns* :
+    #   - A Mat5Reader object.
+    #
+    def load_file(file_path)
+      NMatrix::IO::Mat5Reader.new(File.open(file_path, 'rb')).to_ruby
+    end
+  end
+
+  protected
+  def inspect_helper #:nodoc:
+    ary = []
+    ary << "shape:[#{shape.join(',')}]" << "dtype:#{dtype}" << "stype:#{stype}"
+
+    if stype == :yale
+      ary <<	"capacity:#{capacity}"
 
       # These are enabled by the DEBUG_YALE compiler flag in extconf.rb.
       if respond_to?(:__yale_a__)
         ary << "ija:#{__yale_ary__to_s(:ija)}" << "ia:#{__yale_ary__to_s(:ia)}" <<
-				  			"ja:#{__yale_ary__to_s(:ja)}" << "a:#{__yale_ary__to_s(:a)}" << "d:#{__yale_ary__to_s(:d)}" <<
-					  		"lu:#{__yale_ary__to_s(:lu)}" << "yale_size:#{__yale_size__}"
+          "ja:#{__yale_ary__to_s(:ja)}" << "a:#{__yale_ary__to_s(:a)}" << "d:#{__yale_ary__to_s(:d)}" <<
+          "lu:#{__yale_ary__to_s(:lu)}" << "yale_size:#{__yale_size__}"
       end
 
-		end
+    end
 
-		ary
-	end
+    ary
+  end
 end
-
-require_relative "./lapack.rb"

data/lib/nmatrix/nvector.rb

@@ -1,3 +1,4 @@
+#--
 # = NMatrix
 #
 # A linear algebra library for scientific computation in Ruby.
@@ -8,8 +9,8 @@
 #
 # == Copyright Information
 #
-# SciRuby is Copyright (c) 2010 - 2012, Ruby Science Foundation
-# NMatrix is Copyright (c) 2012, Ruby Science Foundation
+# SciRuby is Copyright (c) 2010 - 2013, Ruby Science Foundation
+# NMatrix is Copyright (c) 2013, Ruby Science Foundation
 #
 # Please see LICENSE.txt for additional copyright notices.
 #
@@ -23,81 +24,189 @@
 # == nmatrix.rb
 #
 # This file defines the NVector class.
-
-############
-# Requires #
-############
-
-
-#######################
-# Classes and Modules #
-#######################
+#++
 
 # This is a specific type of NMatrix in which only one dimension is not 1.
 # Although it is stored as a dim-2, n x 1, matrix, it acts as a dim-1 vector
 # of size n. If the @orientation flag is set to :row, it is stored as 1 x n
 # instead of n x 1.
 class NVector < NMatrix
-	def initialize(length, *args)
-		super(:dense, [length, 1], *args)
+  #
+  # call-seq:
+  #     new(length) -> NVector
+  #     new(length, values) -> NVector
+  #     new(length, values, dtype) -> NVector
+  #
+  # Creates a new NVector.
+  #
+  # * *Arguments* :
+  #   - +length+ -> Size of the vector.
+  #   - +values+ -> (optional) Initial values of the vector. Default is 0.
+  #   - +dtype+ -> (optional) Default is a guess from the +values+.
+  # * *Returns* :
+  #   -
+  #
+  def initialize(length, *args)
+    super(:dense, [length, 1], *args)
     orientation
   end
 
-	# Orientation defaults to column (e.g., [3,1] is a column of length 3). It
-	# may also be row, e.g., for [1,5].
-	def orientation
-		@orientation ||= :column
-	end
+  #
+  # call-seq:
+  #     orientation -> Symbol
+  #
+  # Orientation defaults to column (e.g., [3,1] is a column of length 3). It
+  # may also be row, e.g., for [1,5].
+  #
+  def orientation
+    @orientation ||= :column
+  end
 
-	def transpose
-		t = super()
+  #
+  # call-seq:
+  #     transpose -> NVector
+  #
+  # Returns a transposed copy of the vector.
+  #
+  # * *Returns* :
+  #   - NVector containing the transposed vector.
+  #
+  def transpose
+    t = super()
     t.flip!
-	end
+  end
 
-	def transpose!
-		super()
-		self.flip!
-	end
+  #
+  # call-seq:
+  #     transpose! -> NVector
+  #
+  # Transpose the vector in-place.
+  #
+  # * *Returns* :
+  #   - NVector containing the transposed vector.
+  #
+  def transpose!
+    super()
+    self.flip!
+  end
 
-	def multiply(m)
-		t = super(m)
+  #
+  # call-seq:
+  #     multiply(m) ->
+  #
+  # ...
+  #
+  # * *Arguments* :
+  #   - ++ ->
+  # * *Returns* :
+  #   -
+  #
+  def multiply(m)
+    t = super(m)
     t.flip!
-	end
+  end
+
+  #
+  # call-seq:
+  #     multiply!(m) ->
+  #
+  # ...
+  #
+  # * *Arguments* :
+  #   - ++ ->
+  # * *Returns* :
+  #   -
+  #
+  def multiply!(m)
+    super().flip!
+  end
 
-	def multiply!(m)
-		super().flip!
-	end
+  #
+  # call-seq:
+  #     vector[index] -> element
+  #     vector[range] -> NVector
+  #
+  # Retrieves an element or return a slice.
+  #
+  # Examples:
+  #
+  #   u = NVector.new(3, [10, 20, 30])
+  #   u[0]              # => 10
+  #   u[0] + u[1]       # => 30
+  #   u[0 .. 1].shape   # => [2, 1]
+  #
+  def [](i)
+    case @orientation
+    when :column;	super(i, 0)
+    when :row;	  super(0, i)
+    end
+  end
 
-	def [](i)
-		case @orientation
-		when :column;	super(i, 0)
-		when :row;	  super(0, i)
-		end
+  #
+  # call-seq:
+  #     vector[index] = obj -> obj
+  #
+  # Stores +value+ at position +index+.
+  #
+  def []=(i, val)
+    case @orientation
+    when :column;	super(i, 0, val)
+    when :row;	  super(0, i, val)
+    end
   end
 
-	def []=(i, val)
-		case @orientation
-		when :column;	super(i, 0, val)
-		when :row;	  super(0, i, val)
-		end
-	end
+  #
+  # call-seq:
+  #     dim -> 1
+  #
+  # Returns the dimension of a vector, which is 1.
+  #
+  def dim; 1; end
+
+  # shorthand for the dominant shape component
+  def size
+    shape[0] > 1 ? shape[0] : shape[1]
+  end
 
-	def dim; 1; end
+  # TODO: Make this actually pretty.
+  def pretty_print(q = nil) #:nodoc:
+    dim = @orientation == :row ? 1 : 0
 
-	# TODO: Make this actually pretty.
-	def pretty_print
-		dim = @orientation == :row ? 1 : 0
-		
-		puts (0...shape[dim]).inject(Array.new) { |a, i| a << self[i] }.join('  ')
-	end
+    arr = (0...shape[dim]).inject(Array.new){ |a, i| a << self[i] }
+
+    if q.nil?
+      puts "[" + arr.join("\n") + "]"
+    else
+      q.group(1, "", "\n") do
+        q.seplist(arr, lambda { q.text "  " }, :each)  { |v| q.text v.to_s }
+      end
+    end
+  end
+
+  def inspect #:nodoc:
+    original_inspect = super()
+    original_inspect = original_inspect[0...original_inspect.size-1]
+    original_inspect.gsub("@orientation=:#{self.orientation}", "orientation:#{self.orientation}") + ">"
+  end
 
 protected
-	def inspect_helper
-		super() << "orientation:#{self.orientation}"
-	end
-	
-	def flip_orientation!
-		returning(self) { @orientation = @orientation == :row ? :column : :row }
-	end
-	alias :flip! :flip_orientation!
+#  def inspect_helper #:nodoc:
+#    x = (super() << "orientation:#{self.orientation}") #.gsub(" @orientation=:#{self.orientation}", "")
+#    binding.pry
+#    x
+#  end
+
+  #
+  # call-seq:
+  #     flip_orientation! -> NVector
+  #
+  # Flip the orientation of the vector.
+  #
+  # * *Returns* :
+  #   - NVector with orientation changed.
+  #
+  def flip_orientation!
+    returning(self) { @orientation = @orientation == :row ? :column : :row }
+  end
+  alias :flip! :flip_orientation!
 end