nmatrix 0.1.0 → 0.2.0

data/lib/nmatrix/lapack_core.rb

@@ -0,0 +1,181 @@
+#--
+# = NMatrix
+#
+# A linear algebra library for scientific computation in Ruby.
+# NMatrix is part of SciRuby.
+#
+# NMatrix was originally inspired by and derived from NArray, by
+# Masahiro Tanaka: http://narray.rubyforge.org
+#
+# == Copyright Information
+#
+# SciRuby is Copyright (c) 2010 - 2014, Ruby Science Foundation
+# NMatrix is Copyright (c) 2012 - 2014, John Woods and the Ruby Science Foundation
+#
+# Please see LICENSE.txt for additional copyright notices.
+#
+# == Contributing
+#
+# By contributing source code to SciRuby, you agree to be bound by
+# our Contributor Agreement:
+#
+# * https://github.com/SciRuby/sciruby/wiki/Contributor-Agreement
+#
+# == lapack_core.rb
+#
+# This file contains friendlier interfaces to LAPACK functions
+# implemented in C.
+# This file is only for functions available with the core nmatrix gem
+# (no external libraries needed).
+#
+# Note: most of these functions are borrowed from ATLAS, which is available under a BSD-
+# style license.
+#++
+
+class NMatrix
+
+  module LAPACK
+
+    #Add functions from C extension to main LAPACK module
+    class << self
+      NMatrix::Internal::LAPACK.singleton_methods.each do |m|
+        define_method m, NMatrix::Internal::LAPACK.method(m).to_proc
+      end
+    end
+
+    class << self
+      # Solve the matrix equation AX = B, where A is a symmetric (or Hermitian)
+      # positive-definite matrix. If A is a nxn matrix, B must be mxn.
+      # Depending on the value of uplo, only the upper or lower half of +a+
+      # is read.
+      # This uses the Cholesky decomposition so it should be faster than
+      # the generic NMatrix#solve method.
+      # Doesn't modify inputs.
+      # Requires either the nmatrix-atlas or nmatrix-lapacke gem.
+      # * *Arguments* :
+      #   - +uplo+ -> Either +:upper+ or +:lower+. Specifies which half of +a+ to read.
+      #   - +a+ -> The matrix A.
+      #   - +b+ -> The right-hand side B.
+      # * *Returns* :
+      #   - The solution X
+      def posv(uplo, a, b)
+        raise(NotImplementedError, "Either the nmatrix-atlas or nmatrix-lapacke gem must be installed to use posv")
+      end
+
+      #     laswp(matrix, ipiv) -> NMatrix
+      #
+      # Permute the columns of a matrix (in-place) according to the Array +ipiv+.
+      #
+      def laswp(matrix, ipiv)
+        raise(ArgumentError, "expected NMatrix for argument 0") unless matrix.is_a?(NMatrix)
+        raise(StorageTypeError, "LAPACK functions only work on :dense NMatrix instances") unless matrix.stype == :dense
+        raise(ArgumentError, "expected Array ipiv to have no more entries than NMatrix a has columns") if ipiv.size > matrix.shape[1]
+
+        clapack_laswp(matrix.shape[0], matrix, matrix.shape[1], 0, ipiv.size-1, ipiv, 1)
+      end
+
+      def alloc_svd_result(matrix)
+        [
+          NMatrix.new(matrix.shape[0], dtype: matrix.dtype),
+          NMatrix.new([[matrix.shape[0],matrix.shape[1]].min,1], dtype: matrix.abs_dtype),
+          NMatrix.new(matrix.shape[1], dtype: matrix.dtype)
+        ]
+      end
+
+
+      #
+      # call-seq:
+      #     gesvd(matrix) -> [u, sigma, v_transpose]
+      #     gesvd(matrix) -> [u, sigma, v_conjugate_transpose] # complex
+      #
+      # Compute the singular value decomposition of a matrix using LAPACK's GESVD function.
+      #
+      # Optionally accepts a +workspace_size+ parameter, which will be honored only if it is larger than what LAPACK
+      # requires.
+      #
+      # Requires either the nmatrix-lapacke or nmatrix-atlas gem.
+      #
+      def gesvd(matrix, workspace_size=1)
+        raise(NotImplementedError,"gesvd requires either the nmatrix-atlas or nmatrix-lapacke gem")
+      end
+
+      #
+      # call-seq:
+      #     gesdd(matrix) -> [u, sigma, v_transpose]
+      #     gesdd(matrix) -> [u, sigma, v_conjugate_transpose] # complex
+      #
+      # Compute the singular value decomposition of a matrix using LAPACK's GESDD function. This uses a divide-and-conquer
+      # strategy. See also #gesvd.
+      #
+      # Optionally accepts a +workspace_size+ parameter, which will be honored only if it is larger than what LAPACK
+      # requires.
+      #
+      # Requires either the nmatrix-lapacke or nmatrix-atlas gem.
+      #
+      def gesdd(matrix, workspace_size=nil)
+        raise(NotImplementedError,"gesvd requires either the nmatrix-atlas or nmatrix-lapacke gem")
+      end
+
+      #
+      # call-seq:
+      #     geev(matrix) -> [eigenvalues, left_eigenvectors, right_eigenvectors]
+      #     geev(matrix, :left) -> [eigenvalues, left_eigenvectors]
+      #     geev(matrix, :right) -> [eigenvalues, right_eigenvectors]
+      #
+      # Perform eigenvalue decomposition on a matrix using LAPACK's xGEEV function.
+      #
+      # +eigenvalues+ is a n-by-1 NMatrix containing the eigenvalues.
+      #
+      # +right_eigenvalues+ is a n-by-n matrix such that its j'th column
+      # contains the (right) eigenvalue of +matrix+ corresponding
+      # to the j'th eigenvalue.
+      # This means that +matrix+ = RDR^(-1),
+      # where R is +right_eigenvalues+ and D is the diagonal matrix formed
+      # from +eigenvalues+.
+      #
+      # +left_eigenvalues+ is n-by-n and its columns are the left
+      # eigenvalues of +matrix+, using the {definition of left eigenvalue
+      # from LAPACK}[https://software.intel.com/en-us/node/521147].
+      #
+      # For real dtypes, +eigenvalues+ and the eigenvector matrices
+      # will be complex if and only if +matrix+ has complex eigenvalues.
+      #
+      # Only available if nmatrix-lapack or nmatrix-atlas is installed.
+      #
+      def geev(matrix, which=:both)
+        raise(NotImplementedError, "geev requires either the nmatrix-atlas or nmatrix-lapack gem")
+      end
+
+      # The following are functions that used to be implemented in C, but
+      # now require nmatrix-atlas to run properly, so we can just
+      # implemented their stubs in Ruby.
+      def lapack_gesvd(jobu, jobvt, m, n, a, lda, s, u, ldu, vt, ldvt, lwork)
+        raise(NotImplementedError,"lapack_gesvd requires the nmatrix-atlas gem")
+      end
+
+      def lapack_gesdd(jobz, m, n, a, lda, s, u, ldu, vt, ldvt, lwork)
+        raise(NotImplementedError,"lapack_gesdd requires the nmatrix-atlas gem")
+      end
+
+      def lapack_geev(jobvl, jobvr, n, a, lda, w, wi, vl, ldvl, vr, ldvr, lwork)
+        raise(NotImplementedError,"lapack_geev requires the nmatrix-atlas gem")
+      end
+
+      def clapack_potrf(order, uplo, n, a, lda)
+        raise(NotImplementedError,"clapack_potrf requires the nmatrix-atlas gem")
+      end
+
+      def clapack_potri(order, uplo, n, a, lda)
+        raise(NotImplementedError,"clapack_potri requires the nmatrix-atlas gem")
+      end
+
+      def clapack_potrs(order, uplo, n, nrhs, a, lda, b, ldb)
+        raise(NotImplementedError,"clapack_potrs requires the nmatrix-atlas gem")
+      end
+
+      def clapack_getri(order, n, a, lda, ipiv)
+        raise(NotImplementedError,"clapack_getri requires the nmatrix-atlas gem")
+      end
+    end
+  end
+end

data/lib/nmatrix/lapack_plugin.rb

@@ -0,0 +1,44 @@
+#--
+# = NMatrix
+#
+# A linear algebra library for scientific computation in Ruby.
+# NMatrix is part of SciRuby.
+#
+# NMatrix was originally inspired by and derived from NArray, by
+# Masahiro Tanaka: http://narray.rubyforge.org
+#
+# == Copyright Information
+#
+# SciRuby is Copyright (c) 2010 - 2014, Ruby Science Foundation
+# NMatrix is Copyright (c) 2012 - 2014, John Woods and the Ruby Science Foundation
+#
+# Please see LICENSE.txt for additional copyright notices.
+#
+# == Contributing
+#
+# By contributing source code to SciRuby, you agree to be bound by
+# our Contributor Agreement:
+#
+# * https://github.com/SciRuby/sciruby/wiki/Contributor-Agreement
+#
+# == lapack_plugin.rb
+#
+# This file `require`s either nmatrix-atlas or nmatrix-lapacke depending on which
+# is available.
+#
+# The idea is that if a developer wants to use a LAPACK feature which is provided
+# by both of these gems (e.g. NMatrix#potrf! or NMatrix::LAPACK.geev),
+# but doesn't care which one is installed, they can
+# just `require 'nmatrix/lapack_plugin'` rather than having to choose between
+# `require 'nmatrix/lapacke'` or `require 'nmatrix/lapacke'` 
+#++
+
+begin
+  require 'nmatrix/atlas'
+rescue LoadError
+  begin
+    require 'nmatrix/lapacke'
+  rescue LoadError
+    raise(LoadError,"Either nmatrix-atlas or nmatrix-lapacke must be installed")
+  end
+end

data/lib/nmatrix/math.rb

@@ -36,6 +36,31 @@ class NMatrix
       :asinh, :atanh, :exp, :log2, :log10, :sqrt, :cbrt, :erf, :erfc, :gamma, :-@]
   end
 
+  # Methods for generating permutation matrix from LU factorization results.
+  module FactorizeLUMethods
+    class << self
+      def permutation_matrix_from(pivot_array)
+        perm_arry = permutation_array_for(pivot_array)
+        n         = NMatrix.zeros(perm_arry.size, dtype: :byte)
+
+        perm_arry.each_with_index { |e, i| n[e,i] = 1 }
+
+        n
+      end
+
+      def permutation_array_for(pivot_array)
+        perm_arry = Array.new(pivot_array.size) { |i| i }
+        perm_arry.each_index do |i|
+          #the pivot indices returned by LAPACK getrf are indexed starting
+          #from 1, so we need to subtract 1 here
+          perm_arry[i], perm_arry[pivot_array[i]-1] = perm_arry[pivot_array[i]-1], perm_arry[i]
+        end
+
+        perm_arry
+      end
+    end
+  end
+
   #
   # call-seq:
   #     invert! -> NMatrix
@@ -44,23 +69,18 @@ class NMatrix
   # Only works on dense matrices. Alternatively uses in-place Gauss-Jordan 
   # elimination.
   #
+  # * *Raises* :
+  #   - +StorageTypeError+ -> only implemented on dense matrices.
+  #   - +ShapeError+ -> matrix must be square.
+  #   - +DataTypeError+ -> cannot invert an integer matrix in-place.
+  #
   def invert!
-    if NMatrix.has_clapack?
-      # Get the pivot array; factor the matrix
-      pivot = self.getrf!
-
-      # Now calculate the inverse using the pivot array
-      NMatrix::LAPACK::clapack_getri(:row, self.shape[1], self, self.shape[1], pivot)
+    raise(StorageTypeError, "invert only works on dense matrices currently") unless self.dense?
+    raise(ShapeError, "Cannot invert non-square matrix") unless self.dim == 2 && self.shape[0] == self.shape[1]
+    raise(DataTypeError, "Cannot invert an integer matrix in-place") if self.integer_dtype?
 
-      self
-    else
-      if self.integer_dtype?
-        __inverse__(self.cast(dtype: :rational128), true)
-      else
-        dtype = self.dtype
-        __inverse__(self, true)
-      end
-    end
+    #No internal implementation of getri, so use this other function
+    __inverse__(self, true)
   end
 
   #
@@ -70,45 +90,42 @@ class NMatrix
   # Make a copy of the matrix, then invert using Gauss-Jordan elimination.
   # Works without LAPACK.
   #
-  #
   # * *Returns* :
-  #   - A dense NMatrix.
-  #
-  def invert lda=nil, ldb=nil
-    if lda.nil? and ldb.nil?
-      if NMatrix.has_clapack?
-        begin
-          self.cast(:dense, self.dtype).invert! # call CLAPACK version
-        rescue NotImplementedError # probably a rational matrix
-          inverse = self.clone
-          __inverse__(inverse, false)
-        end
-      elsif self.integer_dtype? # FIXME: This check is probably too slow.
-        rational_self = self.cast(dtype: :rational128)
-        inverse       = rational_self.clone
-        rational_self.__inverse__(inverse, false)
-      else
-        inverse       = self.clone
-        __inverse__(inverse, false)
-      end
+  #   - A dense NMatrix. Will be the same type as the input NMatrix,
+  #   except if the input is an integral dtype, in which case it will be a
+  #   :float64 NMatrix.
+  #
+  # * *Raises* :
+  #   - +StorageTypeError+ -> only implemented on dense matrices.
+  #   - +ShapeError+ -> matrix must be square.
+  #
+  def invert
+    #write this in terms of invert! so plugins will only have to overwrite
+    #invert! and not invert
+    if self.integer_dtype?
+      cloned = self.cast(dtype: :float64)
+      cloned.invert!
     else
-      inverse = self.clone_structure
-      if self.integer_dtype?
-        __inverse_exact__(inverse.cast(dtype: :rational128), lda, ldb)
-      else
-        dtype = self.dtype
-        __inverse_exact__(inverse, lda, ldb)
-      end
+      cloned = self.clone
+      cloned.invert!
     end
   end
   alias :inverse :invert
 
   #
   # call-seq:
-  #     getrf! -> NMatrix
+  #     getrf! -> Array
   #
   # LU factorization of a general M-by-N matrix +A+ using partial pivoting with
-  # row interchanges. Only works in dense matrices.
+  # row interchanges. The LU factorization is A = PLU, where P is a row permutation
+  # matrix, L is a lower triangular matrix with unit diagonals, and U is an upper
+  # triangular matrix (note that this convention is different from the
+  # clapack_getrf behavior, but matches the standard LAPACK getrf).
+  # +A+ is overwritten with the elements of L and U (the unit
+  # diagonal elements of L are not saved). P is not returned directly and must be
+  # constructed from the pivot array ipiv. The row indices in ipiv are indexed
+  # starting from 1.
+  # Only works for dense matrices.
   #
   # * *Returns* :
   #   - The IPIV vector. The L and U matrices are stored in A.
@@ -117,44 +134,51 @@ class NMatrix
   #
   def getrf!
     raise(StorageTypeError, "ATLAS functions only work on dense matrices") unless self.dense?
-    NMatrix::LAPACK::clapack_getrf(:row, self.shape[0], self.shape[1], self, self.shape[1])
-  end
-
 
-  #
-  # call-seq:
-  #     getrf -> NMatrix
-  #
-  # In-place version of #getrf!. Returns the new matrix, which contains L and U matrices.
-  #
-  # * *Raises* :
-  #   - +StorageTypeError+ -> ATLAS functions only work on dense matrices.
-  #
-  def getrf
-    a = self.clone
-    a.getrf!
-    return a
+    #For row-major matrices, clapack_getrf uses a different convention than
+    #described above (U has unit diagonal elements instead of L and columns
+    #are interchanged rather than rows). For column-major matrices, clapack
+    #uses the stanard conventions. So we just transpose the matrix before
+    #and after calling clapack_getrf.
+    #Unfortunately, this is not a very good way, uses a lot of memory.
+    temp = self.transpose
+    ipiv = NMatrix::LAPACK::clapack_getrf(:col, self.shape[0], self.shape[1], temp, self.shape[0])
+    temp = temp.transpose
+    self[0...self.shape[0], 0...self.shape[1]] = temp
+
+    #for some reason, in clapack_getrf, the indices in ipiv start from 0
+    #instead of 1 as in LAPACK.
+    ipiv.each_index { |i| ipiv[i]+=1 }
+
+    return ipiv
   end
 
-
   #
   # call-seq:
   #     potrf!(upper_or_lower) -> NMatrix
   #
   # Cholesky factorization of a symmetric positive-definite matrix -- or, if complex,
-  # a Hermitian positive-definite matrix +A+. This uses the ATLAS function clapack_potrf,
-  # so the result will be written in either the upper or lower triangular portion of the
-  # matrix upon which it is called.
+  # a Hermitian positive-definite matrix +A+.
+  # The result will be written in either the upper or lower triangular portion of the
+  # matrix, depending on whether the argument is +:upper+ or +:lower+.
+  # Also the function only reads in the upper or lower part of the matrix,
+  # so it doesn't actually have to be symmetric/Hermitian.
+  # However, if the matrix (i.e. the symmetric matrix implied by the lower/upper
+  # half) is not positive-definite, the function will return nonsense.
+  #
+  # This functions requires either the nmatrix-atlas or nmatrix-lapacke gem
+  # installed.
   #
   # * *Returns* :
   #   the triangular portion specified by the parameter
   # * *Raises* :
   #   - +StorageTypeError+ -> ATLAS functions only work on dense matrices.
+  #   - +ShapeError+ -> Must be square.
+  #   - +NotImplementedError+ -> If called without nmatrix-atlas or nmatrix-lapacke gem
   #
   def potrf!(which)
-    raise(StorageTypeError, "ATLAS functions only work on dense matrices") unless self.dense?
-    # FIXME: Surely there's an easy way to calculate one of these from the other. Do we really need to run twice?
-    NMatrix::LAPACK::clapack_potrf(:row, which, self.shape[0], self, self.shape[1])
+    # The real implementation is in the plugin files.
+    raise(NotImplementedError, "potrf! requires either the nmatrix-atlas or nmatrix-lapacke gem")
   end
 
   def potrf_upper!
@@ -168,30 +192,102 @@ class NMatrix
 
   #
   # call-seq:
-  #     factorize_cholesky -> ...
+  #     factorize_cholesky -> [upper NMatrix, lower NMatrix]
   #
-  # Cholesky factorization of a matrix.
+  # Calculates the Cholesky factorization of a matrix and returns the
+  # upper and lower matrices such that A=LU and L=U*, where * is
+  # either the transpose or conjugate transpose.
+  #
+  # Unlike potrf!, this makes method requires that the original is matrix is
+  # symmetric or Hermitian. However, it is still your responsibility to make
+  # sure it is positive-definite.
   def factorize_cholesky
-    [self.clone.potrf_upper!.triu!,
-    self.clone.potrf_lower!.tril!]
+    raise "Matrix must be symmetric/Hermitian for Cholesky factorization" unless self.hermitian?
+    l = self.clone.potrf_lower!.tril!
+    u = l.conjugate_transpose
+    [u,l]
   end
 
   #
   # call-seq:
   #     factorize_lu -> ...
   #
-  # LU factorization of a matrix.
-  #
-  # FIXME: For some reason, getrf seems to require that the matrix be transposed first -- and then you have to transpose the
-  # FIXME: result again. Ideally, this would be an in-place factorize instead, and would be called nm_factorize_lu_bang.
-  #
-  def factorize_lu
+  # LU factorization of a matrix. Optionally return the permutation matrix.
+  #   Note that computing the permutation matrix will introduce a slight memory
+  #   and time overhead. 
+  # 
+  # == Arguments
+  # 
+  # +with_permutation_matrix+ - If set to *true* will return the permutation 
+  #   matrix alongwith the LU factorization as a second return value.
+  # 
+  def factorize_lu with_permutation_matrix=nil
     raise(NotImplementedError, "only implemented for dense storage") unless self.stype == :dense
     raise(NotImplementedError, "matrix is not 2-dimensional") unless self.dimensions == 2
 
-    t = self.transpose
-    NMatrix::LAPACK::clapack_getrf(:row, t.shape[0], t.shape[1], t, t.shape[1])
-    t.transpose
+    t     = self.clone
+    pivot = t.getrf!
+    return t unless with_permutation_matrix
+
+    [t, FactorizeLUMethods.permutation_matrix_from(pivot)]
+  end
+
+  # Reduce self to upper hessenberg form using householder transforms.
+  # 
+  # == References
+  #
+  # * http://en.wikipedia.org/wiki/Hessenberg_matrix
+  # * http://www.mymathlib.com/c_source/matrices/eigen/hessenberg_orthog.c
+  def hessenberg
+    clone.hessenberg!
+  end
+
+  # Destructive version of #hessenberg
+  def hessenberg!
+    raise ShapeError, "Trying to reduce non 2D matrix to hessenberg form" if 
+      shape.size != 2
+    raise ShapeError, "Trying to reduce non-square matrix to hessenberg form" if 
+      shape[0] != shape[1]
+    raise StorageTypeError, "Matrix must be dense" if stype != :dense
+    raise TypeError, "Works with float matrices only" unless 
+      [:float64,:float32].include?(dtype)
+
+    __hessenberg__(self)
+    self
+  end
+
+  # Solve the matrix equation AX = B, where A is +self+, B is the first
+  # argument, and X is returned. A must be a nxn square matrix, while B must be
+  # nxm. Only works with dense
+  # matrices and non-integer, non-object data types.
+  # 
+  # == Usage
+  # 
+  #   a = NMatrix.new [2,2], [3,1,1,2], dtype: dtype
+  #   b = NMatrix.new [2,1], [9,8], dtype: dtype
+  #   a.solve(b)
+  def solve b
+    raise(ShapeError, "Must be called on square matrix") unless self.dim == 2 && self.shape[0] == self.shape[1]
+    raise(ShapeError, "number of rows of b must equal number of cols of self") if 
+      self.shape[1] != b.shape[0]
+    raise ArgumentError, "only works with dense matrices" if self.stype != :dense
+    raise ArgumentError, "only works for non-integer, non-object dtypes" if 
+      integer_dtype? or object_dtype? or b.integer_dtype? or b.object_dtype?
+
+    x     = b.clone
+    clone = self.clone
+    n = self.shape[0]
+    nrhs = b.shape[1]
+
+    ipiv = NMatrix::LAPACK.clapack_getrf(:row, n, n, clone, n)
+    # When we call clapack_getrs with :row, actually only the first matrix
+    # (i.e. clone) is interpreted as row-major, while the other matrix (x)
+    # is interpreted as column-major. See here: http://math-atlas.sourceforge.net/faq.html#RowSolve
+    # So we must transpose x before and after
+    # calling it.
+    x = x.transpose
+    NMatrix::LAPACK.clapack_getrs(:row, :no_transpose, n, nrhs, clone, n, ipiv, x, n)
+    x.transpose
   end
 
   #
@@ -254,24 +350,80 @@ class NMatrix
   def gesdd(workspace_size=nil)
     self.clone.gesdd!(workspace_size)
   end
+
   #
   # call-seq:
   #     laswp!(ary) -> NMatrix
   #
-  # In-place permute the columns of a dense matrix using LASWP according to the order given in an Array +ary+.
-  # Not yet implemented for yale or list.
-  def laswp!(ary)
-    NMatrix::LAPACK::laswp(self, ary)
+  # In-place permute the columns of a dense matrix using LASWP according to the order given as an array +ary+.
+  #
+  # If +:convention+ is +:lapack+, then +ary+ represents a sequence of pair-wise permutations which are 
+  # performed successively. That is, the i'th entry of +ary+ is the index of the column to swap 
+  # the i'th column with, having already applied all earlier swaps. 
+  #
+  # If +:convention+ is +:intuitive+, then +ary+ represents the order of columns after the permutation. 
+  # That is, the i'th entry of +ary+ is the index of the column that will be in position i after the 
+  # reordering (Matlab-like behaviour). This is the default.
+  #
+  # Not yet implemented for yale or list. 
+  #
+  # == Arguments
+  #
+  # * +ary+ - An Array specifying the order of the columns. See above for details.
+  # 
+  # == Options
+  # 
+  # * +:covention+ - Possible values are +:lapack+ and +:intuitive+. Default is +:intuitive+. See above for details.
+  #
+  def laswp!(ary, opts={})
+    raise(StorageTypeError, "ATLAS functions only work on dense matrices") unless self.dense?
+    opts = { convention: :intuitive }.merge(opts)
+    
+    if opts[:convention] == :intuitive
+      if ary.length != ary.uniq.length
+        raise(ArgumentError, "No duplicated entries in the order array are allowed under convention :intuitive")
+      end
+      n = self.shape[1]
+      p = []
+      order = (0...n).to_a
+      0.upto(n-2) do |i|
+        p[i] = order.index(ary[i])
+        order[i], order[p[i]] = order[p[i]], order[i]
+      end
+      p[n-1] = n-1
+    else
+      p = ary
+    end
+
+    NMatrix::LAPACK::laswp(self, p)
   end
 
   #
   # call-seq:
   #     laswp(ary) -> NMatrix
   #
-  # Permute the columns of a dense matrix using LASWP according to the order given in an Array +ary+.
-  # Not yet implemented for yale or list.
-  def laswp(ary)
-    self.clone.laswp!(ary)
+  # Permute the columns of a dense matrix using LASWP according to the order given in an array +ary+.
+  #
+  # If +:convention+ is +:lapack+, then +ary+ represents a sequence of pair-wise permutations which are 
+  # performed successively. That is, the i'th entry of +ary+ is the index of the column to swap 
+  # the i'th column with, having already applied all earlier swaps. This is the default.
+  #
+  # If +:convention+ is +:intuitive+, then +ary+ represents the order of columns after the permutation. 
+  # That is, the i'th entry of +ary+ is the index of the column that will be in position i after the 
+  # reordering (Matlab-like behaviour). 
+  #
+  # Not yet implemented for yale or list. 
+  #
+  # == Arguments
+  #
+  # * +ary+ - An Array specifying the order of the columns. See above for details.
+  # 
+  # == Options
+  # 
+  # * +:covention+ - Possible values are +:lapack+ and +:intuitive+. Default is +:lapack+. See above for details.
+  #
+  def laswp(ary, opts={})
+    self.clone.laswp!(ary, opts)
   end
 
   #
@@ -279,7 +431,7 @@ class NMatrix
   #     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
+  # using clapack_getrf, and then by taking the product of the diagonal elements. There is a
   # risk of underflow/overflow.
   #
   # There are probably also more efficient ways to calculate the determinant.
@@ -290,35 +442,38 @@ class NMatrix
   #
   # 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
+  # Integer matrices are converted to floating point 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.
+  #   - +ShapeError+ -> Must be used on square matrices.
   #
   def det
-    raise(NotImplementedError, "determinant can be calculated only for 2D matrices") unless self.dim == 2
+    raise(ShapeError, "determinant can be calculated only for square matrices") unless self.dim == 2 && self.shape[0] == self.shape[1]
 
     # Cast to a dtype for which getrf is implemented
-    new_dtype = [:byte,:int8,:int16,:int32,:int64].include?(self.dtype) ? :rational128 : self.dtype
+    new_dtype = self.integer_dtype? ? :float64 : 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.
     pivot = copy.getrf!
 
-    prod = pivot.size % 2 == 1 ? -1 : 1 # odd permutations => negative
+    num_perm = 0 #number of permutations
+    pivot.each_with_index do |swap, i|
+      #pivot indexes rows starting from 1, instead of 0, so need to subtract 1 here
+      num_perm += 1 if swap-1 != i
+    end
+    prod = num_perm % 2 == 1 ? -1 : 1 # odd permutations => negative
     [shape[0],shape[1]].min.times do |i|
       prod *= copy[i,i]
     end
 
     # Convert back to an integer if necessary
-    new_dtype != self.dtype ? prod.to_i : prod
+    new_dtype != self.dtype ? prod.round : prod #prevent rounding errors
   end
 
   #
@@ -342,6 +497,120 @@ class NMatrix
     self.cast(new_stype, NMatrix::upcast(dtype, :complex64)).complex_conjugate!
   end
 
+  # Calculate the variance co-variance matrix
+  # 
+  # == Options
+  # 
+  # * +:for_sample_data+ - Default true. If set to false will consider the denominator for
+  #   population data (i.e. N, as opposed to N-1 for sample data).
+  # 
+  # == References
+  # 
+  # * http://stattrek.com/matrix-algebra/covariance-matrix.aspx
+  def cov(opts={})
+    raise TypeError, "Only works for non-integer dtypes" if integer_dtype?
+     opts = {
+      for_sample_data: true
+    }.merge(opts)
+    
+    denominator      = opts[:for_sample_data] ? rows - 1 : rows
+    ones             = NMatrix.ones [rows,1] 
+    deviation_scores = self - ones.dot(ones.transpose).dot(self) / rows
+    deviation_scores.transpose.dot(deviation_scores) / denominator
+  end
+
+  # Calculate the correlation matrix.
+  def corr
+    raise NotImplementedError, "Does not work for complex dtypes" if complex_dtype?
+    standard_deviation = std
+    cov / (standard_deviation.transpose.dot(standard_deviation))
+  end
+
+  # Raise a square matrix to a power. Be careful of numeric overflows!
+  # In case *n* is 0, an identity matrix of the same dimension is returned. In case
+  # of negative *n*, the matrix is inverted and the absolute value of *n* taken 
+  # for computing the power.
+  # 
+  # == Arguments
+  # 
+  # * +n+ - Integer to which self is to be raised.
+  # 
+  # == References
+  # 
+  # * R.G Dromey - How to Solve it by Computer. Link - 
+  #     http://www.amazon.com/Solve-Computer-Prentice-Hall-International-Science/dp/0134340019/ref=sr_1_1?ie=UTF8&qid=1422605572&sr=8-1&keywords=how+to+solve+it+by+computer
+  def pow n
+    raise ShapeError, "Only works with 2D square matrices." if 
+      shape[0] != shape[1] or shape.size != 2
+    raise TypeError, "Only works with integer powers" unless n.is_a?(Integer)
+
+    sequence = (integer_dtype? ? self.cast(dtype: :int64) : self).clone
+    product  = NMatrix.eye shape[0], dtype: sequence.dtype, stype: sequence.stype 
+
+    if n == 0
+      return NMatrix.eye(shape, dtype: dtype, stype: stype)
+    elsif n == 1
+      return sequence
+    elsif n < 0
+      n = n.abs
+      sequence.invert!
+      product = NMatrix.eye shape[0], dtype: sequence.dtype, stype: sequence.stype
+    end
+
+    # Decompose n to reduce the number of multiplications.
+    while n > 0
+      product = product.dot(sequence) if n % 2 == 1
+      n = n / 2
+      sequence = sequence.dot(sequence)
+    end
+
+    product
+  end
+
+  # Compute the Kronecker product of +self+ and other NMatrix
+  #
+  # === Arguments
+  #
+  #   * +mat+ - A 2D NMatrix object
+  #
+  # === Usage 
+  #  
+  #  a = NMatrix.new([2,2],[1,2,
+  #                         3,4])
+  #  b = NMatrix.new([2,3],[1,1,1,
+  #                         1,1,1], dtype: :float64)
+  #  a.kron_prod(b) # => [ [1.0, 1.0, 1.0, 2.0, 2.0, 2.0]
+  #                        [1.0, 1.0, 1.0, 2.0, 2.0, 2.0]
+  #                        [3.0, 3.0, 3.0, 4.0, 4.0, 4.0]
+  #                        [3.0, 3.0, 3.0, 4.0, 4.0, 4.0] ]
+  #    
+  def kron_prod(mat)
+    unless self.dimensions==2 and mat.dimensions==2
+      raise ShapeError, "Implemented for 2D NMatrix objects only."
+    end
+
+    # compute the shape [n,m] of the product matrix
+    n, m = self.shape[0]*mat.shape[0], self.shape[1]*mat.shape[1]
+    # compute the entries of the product matrix
+    kron_prod_array = []
+    if self.yale?
+      # +:yale+ requires to get the row by copy in order to apply +#transpose+ to it
+      self.each_row(getby=:copy) do |selfr|
+        mat.each_row do |matr|
+          kron_prod_array += (selfr.transpose.dot matr).to_flat_a
+        end
+      end
+    else
+      self.each_row do |selfr|
+        mat.each_row do |matr|
+          kron_prod_array += (selfr.transpose.dot matr).to_flat_a
+        end
+      end
+    end
+
+    NMatrix.new([n,m], kron_prod_array) 
+  end
+
   #
   # call-seq:
   #     conjugate_transpose -> NMatrix
@@ -356,27 +625,6 @@ class NMatrix
     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
-
   #
   # call-seq:
   #     trace -> Numeric
@@ -555,7 +803,10 @@ class NMatrix
   #
   # Return the sum of the contents of the vector. This is the BLAS asum routine.
   def asum incx=1, n=nil
-    return self[0].abs if self.shape == [1]
+    if self.shape == [1]
+      return self[0].abs unless self.complex_dtype?
+      return self[0].real.abs + self[0].imag.abs
+    end
     return method_missing(:asum, incx, n) unless vector?
     NMatrix::BLAS::asum(self, incx, self.size / incx)
   end
@@ -608,7 +859,7 @@ protected
   # These don't actually take an argument -- they're called reverse-polish style on the matrix.
   # This group always gets casted to float64.
   [:log, :log2, :log10, :sqrt, :sin, :cos, :tan, :acos, :asin, :atan, :cosh, :sinh, :tanh, :acosh,
-   :asinh, :atanh, :exp, :erf, :erfc, :gamma, :cbrt].each do |ewop|
+   :asinh, :atanh, :exp, :erf, :erfc, :gamma, :cbrt, :round].each do |ewop|
     define_method("__list_unary_#{ewop}__") do
       self.__list_map_stored__(nil) { |l| Math.send(ewop, l) }.cast(stype, NMatrix.upcast(dtype, :float64))
     end
@@ -648,31 +899,31 @@ protected
   end
   #:startdoc:
 
-  # These are for rounding each value of a matrix
-  def __list_unary_round__
+  # These are for rounding each value of a matrix. Takes an optional argument
+  def __list_unary_round__(precision)
     if self.complex_dtype?
-      self.__list_map_stored__(nil) { |l| Complex(l.real.round, l.imag.round) }
+      self.__list_map_stored__(nil) { |l| Complex(l.real.round(precision), l.imag.round(precision)) }
                                     .cast(stype, dtype)
     else
-      self.__list_map_stored__(nil) { |l| l.round }.cast(stype, dtype)
+      self.__list_map_stored__(nil) { |l| l.round(precision) }.cast(stype, dtype)
     end
   end
 
-  def __yale_unary_round__
+  def __yale_unary_round__(precision)
     if self.complex_dtype?
-      self.__yale_map_stored__ { |l| Complex(l.real.round, l.imag.round) }
+      self.__yale_map_stored__ { |l| Complex(l.real.round(precision), l.imag.round(precision)) }
                                     .cast(stype, dtype)
     else
-      self.__yale_map_stored__ { |l| l.round }.cast(stype, dtype)
+      self.__yale_map_stored__ { |l| l.round(precision) }.cast(stype, dtype)
     end
   end
 
-  def __dense_unary_round__
+  def __dense_unary_round__(precision)
     if self.complex_dtype?
-      self.__dense_map__ { |l| Complex(l.real.round, l.imag.round) }
+      self.__dense_map__ { |l| Complex(l.real.round(precision), l.imag.round(precision)) }
                                     .cast(stype, dtype)
     else
-      self.__dense_map__ { |l| l.round }.cast(stype, dtype)
+      self.__dense_map__ { |l| l.round(precision) }.cast(stype, dtype)
     end
   end
 
@@ -680,7 +931,7 @@ protected
   def dtype_for_floor_or_ceil
     if self.integer_dtype? or [:complex64, :complex128, :object].include?(self.dtype)
       return_dtype = dtype
-    elsif [:float32, :float64, :rational32,:rational64, :rational128].include?(self.dtype)
+    elsif [:float32, :float64].include?(self.dtype)
       return_dtype = :int64
     end