rubysl-matrix 1.0.0 → 2.1.0

data/lib/matrix/lup_decomposition.rb

@@ -0,0 +1,218 @@
+class Matrix
+  # Adapted from JAMA: http://math.nist.gov/javanumerics/jama/
+
+  #
+  # For an m-by-n matrix A with m >= n, the LU decomposition is an m-by-n
+  # unit lower triangular matrix L, an n-by-n upper triangular matrix U,
+  # and a m-by-m permutation matrix P so that L*U = P*A.
+  # If m < n, then L is m-by-m and U is m-by-n.
+  #
+  # The LUP decomposition with pivoting always exists, even if the matrix is
+  # singular, so the constructor will never fail.  The primary use of the
+  # LU decomposition is in the solution of square systems of simultaneous
+  # linear equations.  This will fail if singular? returns true.
+  #
+
+  class LUPDecomposition
+    # Returns the lower triangular factor +L+
+
+    include Matrix::ConversionHelper
+
+    def l
+      Matrix.build(@row_count, [@column_count, @row_count].min) do |i, j|
+        if (i > j)
+          @lu[i][j]
+        elsif (i == j)
+          1
+        else
+          0
+        end
+      end
+    end
+
+    # Returns the upper triangular factor +U+
+
+    def u
+      Matrix.build([@column_count, @row_count].min, @column_count) do |i, j|
+        if (i <= j)
+          @lu[i][j]
+        else
+          0
+        end
+      end
+    end
+
+    # Returns the permutation matrix +P+
+
+    def p
+      rows = Array.new(@row_count){Array.new(@row_count, 0)}
+      @pivots.each_with_index{|p, i| rows[i][p] = 1}
+      Matrix.send :new, rows, @row_count
+    end
+
+    # Returns +L+, +U+, +P+ in an array
+
+    def to_ary
+      [l, u, p]
+    end
+    alias_method :to_a, :to_ary
+
+    # Returns the pivoting indices
+
+    attr_reader :pivots
+
+    # Returns +true+ if +U+, and hence +A+, is singular.
+
+    def singular? ()
+      @column_count.times do |j|
+        if (@lu[j][j] == 0)
+          return true
+        end
+      end
+      false
+    end
+
+    # Returns the determinant of +A+, calculated efficiently
+    # from the factorization.
+
+    def det
+      if (@row_count != @column_count)
+        Matrix.Raise Matrix::ErrDimensionMismatch
+      end
+      d = @pivot_sign
+      @column_count.times do |j|
+        d *= @lu[j][j]
+      end
+      d
+    end
+    alias_method :determinant, :det
+
+    # Returns +m+ so that <tt>A*m = b</tt>,
+    # or equivalently so that <tt>L*U*m = P*b</tt>
+    # +b+ can be a Matrix or a Vector
+
+    def solve b
+      if (singular?)
+        Matrix.Raise Matrix::ErrNotRegular, "Matrix is singular."
+      end
+      if b.is_a? Matrix
+        if (b.row_count != @row_count)
+          Matrix.Raise Matrix::ErrDimensionMismatch
+        end
+
+        # Copy right hand side with pivoting
+        nx = b.column_count
+        m = @pivots.map{|row| b.row(row).to_a}
+
+        # Solve L*Y = P*b
+        @column_count.times do |k|
+          (k+1).upto(@column_count-1) do |i|
+            nx.times do |j|
+              m[i][j] -= m[k][j]*@lu[i][k]
+            end
+          end
+        end
+        # Solve U*m = Y
+        (@column_count-1).downto(0) do |k|
+          nx.times do |j|
+            m[k][j] = m[k][j].quo(@lu[k][k])
+          end
+          k.times do |i|
+            nx.times do |j|
+              m[i][j] -= m[k][j]*@lu[i][k]
+            end
+          end
+        end
+        Matrix.send :new, m, nx
+      else # same algorithm, specialized for simpler case of a vector
+        b = convert_to_array(b)
+        if (b.size != @row_count)
+          Matrix.Raise Matrix::ErrDimensionMismatch
+        end
+
+        # Copy right hand side with pivoting
+        m = b.values_at(*@pivots)
+
+        # Solve L*Y = P*b
+        @column_count.times do |k|
+          (k+1).upto(@column_count-1) do |i|
+            m[i] -= m[k]*@lu[i][k]
+          end
+        end
+        # Solve U*m = Y
+        (@column_count-1).downto(0) do |k|
+          m[k] = m[k].quo(@lu[k][k])
+          k.times do |i|
+            m[i] -= m[k]*@lu[i][k]
+          end
+        end
+        Vector.elements(m, false)
+      end
+    end
+
+    def initialize a
+      raise TypeError, "Expected Matrix but got #{a.class}" unless a.is_a?(Matrix)
+      # Use a "left-looking", dot-product, Crout/Doolittle algorithm.
+      @lu = a.to_a
+      @row_count = a.row_count
+      @column_count = a.column_count
+      @pivots = Array.new(@row_count)
+      @row_count.times do |i|
+         @pivots[i] = i
+      end
+      @pivot_sign = 1
+      lu_col_j = Array.new(@row_count)
+
+      # Outer loop.
+
+      @column_count.times do |j|
+
+        # Make a copy of the j-th column to localize references.
+
+        @row_count.times do |i|
+          lu_col_j[i] = @lu[i][j]
+        end
+
+        # Apply previous transformations.
+
+        @row_count.times do |i|
+          lu_row_i = @lu[i]
+
+          # Most of the time is spent in the following dot product.
+
+          kmax = [i, j].min
+          s = 0
+          kmax.times do |k|
+            s += lu_row_i[k]*lu_col_j[k]
+          end
+
+          lu_row_i[j] = lu_col_j[i] -= s
+        end
+
+        # Find pivot and exchange if necessary.
+
+        p = j
+        (j+1).upto(@row_count-1) do |i|
+          if (lu_col_j[i].abs > lu_col_j[p].abs)
+            p = i
+          end
+        end
+        if (p != j)
+          @column_count.times do |k|
+            t = @lu[p][k]; @lu[p][k] = @lu[j][k]; @lu[j][k] = t
+          end
+          k = @pivots[p]; @pivots[p] = @pivots[j]; @pivots[j] = k
+          @pivot_sign = -@pivot_sign
+        end
+
+        # Compute multipliers.
+
+        if (j < @row_count && @lu[j][j] != 0)
+          (j+1).upto(@row_count-1) do |i|
+            @lu[i][j] = @lu[i][j].quo(@lu[j][j])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubysl/matrix/matrix.rb

@@ -32,79 +32,99 @@ end
 # == Method Catalogue
 #
 # To create a matrix:
-# * <tt> Matrix[*rows]                  </tt>
-# * <tt> Matrix.[](*rows)               </tt>
-# * <tt> Matrix.rows(rows, copy = true) </tt>
-# * <tt> Matrix.columns(columns)        </tt>
-# * <tt> Matrix.build(row_size, column_size, &block) </tt>
-# * <tt> Matrix.diagonal(*values)       </tt>
-# * <tt> Matrix.scalar(n, value)        </tt>
-# * <tt> Matrix.identity(n)             </tt>
-# * <tt> Matrix.unit(n)                 </tt>
-# * <tt> Matrix.I(n)                    </tt>
-# * <tt> Matrix.zero(n)                 </tt>
-# * <tt> Matrix.row_vector(row)         </tt>
-# * <tt> Matrix.column_vector(column)   </tt>
+# * Matrix[*rows]
+# * Matrix.[](*rows)
+# * Matrix.rows(rows, copy = true)
+# * Matrix.columns(columns)
+# * Matrix.build(row_count, column_count, &block)
+# * Matrix.diagonal(*values)
+# * Matrix.scalar(n, value)
+# * Matrix.identity(n)
+# * Matrix.unit(n)
+# * Matrix.I(n)
+# * Matrix.zero(n)
+# * Matrix.row_vector(row)
+# * Matrix.column_vector(column)
 #
 # To access Matrix elements/columns/rows/submatrices/properties:
-# * <tt>  [](i, j)                      </tt>
-# * <tt> #row_size                      </tt>
-# * <tt> #column_size                   </tt>
-# * <tt> #row(i)                        </tt>
-# * <tt> #column(j)                     </tt>
-# * <tt> #collect                       </tt>
-# * <tt> #map                           </tt>
-# * <tt> #each                          </tt>
-# * <tt> #each_with_index               </tt>
-# * <tt> #minor(*param)                 </tt>
+# * #[](i, j)
+# * #row_count (row_size)
+# * #column_count (column_size)
+# * #row(i)
+# * #column(j)
+# * #collect
+# * #map
+# * #each
+# * #each_with_index
+# * #find_index
+# * #minor(*param)
 #
 # Properties of a matrix:
-# * <tt> #empty?                        </tt>
-# * <tt> #real?                         </tt>
-# * <tt> #regular?                      </tt>
-# * <tt> #singular?                     </tt>
-# * <tt> #square?                       </tt>
+# * #diagonal?
+# * #empty?
+# * #hermitian?
+# * #lower_triangular?
+# * #normal?
+# * #orthogonal?
+# * #permutation?
+# * #real?
+# * #regular?
+# * #singular?
+# * #square?
+# * #symmetric?
+# * #unitary?
+# * #upper_triangular?
+# * #zero?
 #
 # Matrix arithmetic:
-# * <tt>  *(m)                          </tt>
-# * <tt>  +(m)                          </tt>
-# * <tt>  -(m)                          </tt>
-# * <tt> #/(m)                          </tt>
-# * <tt> #inverse                       </tt>
-# * <tt> #inv                           </tt>
-# * <tt>  **                            </tt>
+# * #*(m)
+# * #+(m)
+# * #-(m)
+# * #/(m)
+# * #inverse
+# * #inv
+# * #**
 #
 # Matrix functions:
-# * <tt> #determinant                   </tt>
-# * <tt> #det                           </tt>
-# * <tt> #rank                          </tt>
-# * <tt> #trace                         </tt>
-# * <tt> #tr                            </tt>
-# * <tt> #transpose                     </tt>
-# * <tt> #t                             </tt>
+# * #determinant
+# * #det
+# * #rank
+# * #round
+# * #trace
+# * #tr
+# * #transpose
+# * #t
+#
+# Matrix decompositions:
+# * #eigen
+# * #eigensystem
+# * #lup
+# * #lup_decomposition
 #
 # Complex arithmetic:
-# * <tt> conj                           </tt>
-# * <tt> conjugate                      </tt>
-# * <tt> imag                           </tt>
-# * <tt> imaginary                      </tt>
-# * <tt> real                           </tt>
-# * <tt> rect                           </tt>
-# * <tt> rectangular                    </tt>
+# * conj
+# * conjugate
+# * imag
+# * imaginary
+# * real
+# * rect
+# * rectangular
 #
 # Conversion to other data types:
-# * <tt> #coerce(other)                 </tt>
-# * <tt> #row_vectors                   </tt>
-# * <tt> #column_vectors                </tt>
-# * <tt> #to_a                          </tt>
+# * #coerce(other)
+# * #row_vectors
+# * #column_vectors
+# * #to_a
 #
 # String representations:
-# * <tt> #to_s                          </tt>
-# * <tt> #inspect                       </tt>
+# * #to_s
+# * #inspect
 #
 class Matrix
   include Enumerable
   include ExceptionForMatrix
+  autoload :EigenvalueDecomposition, "matrix/eigenvalue_decomposition"
+  autoload :LUPDecomposition, "matrix/lup_decomposition"
 
   # instance creations
   private_class_method :new
@@ -118,7 +138,7 @@ class Matrix
   #          -1 66
   #
   def Matrix.[](*rows)
-    Matrix.rows(rows, false)
+    rows(rows, false)
   end
 
   #
@@ -136,7 +156,7 @@ class Matrix
     end
     size = (rows[0] || []).size
     rows.each do |row|
-      Matrix.Raise ErrDimensionMismatch, "row size differs (#{row.size} should be #{size})" unless row.size == size
+      raise ErrDimensionMismatch, "row size differs (#{row.size} should be #{size})" unless row.size == size
     end
     new rows, size
   end
@@ -148,11 +168,11 @@ class Matrix
   #          93 66
   #
   def Matrix.columns(columns)
-    Matrix.rows(columns, false).transpose
+    rows(columns, false).transpose
   end
 
   #
-  # Creates a matrix of size +row_size+ x +column_size+.
+  # Creates a matrix of size +row_count+ x +column_count+.
   # It fills the values by calling the given block,
   # passing the current row and column.
   # Returns an enumerator if no block is given.
@@ -162,17 +182,17 @@ class Matrix
   #   m = Matrix.build(3) { rand }
   #     => a 3x3 matrix with random elements
   #
-  def Matrix.build(row_size, column_size = row_size)
-    row_size = CoercionHelper.coerce_to_int(row_size)
-    column_size = CoercionHelper.coerce_to_int(column_size)
-    raise ArgumentError if row_size < 0 || column_size < 0
-    return to_enum :build, row_size, column_size unless block_given?
-    rows = row_size.times.map do |i|
-      column_size.times.map do |j|
+  def Matrix.build(row_count, column_count = row_count)
+    row_count = CoercionHelper.coerce_to_int(row_count)
+    column_count = CoercionHelper.coerce_to_int(column_count)
+    raise ArgumentError if row_count < 0 || column_count < 0
+    return to_enum :build, row_count, column_count unless block_given?
+    rows = Array.new(row_count) do |i|
+      Array.new(column_count) do |j|
         yield i, j
       end
     end
-    new rows, column_size
+    new rows, column_count
   end
 
   #
@@ -184,7 +204,7 @@ class Matrix
   #
   def Matrix.diagonal(*values)
     size = values.size
-    rows = (0 ... size).collect {|j|
+    rows = Array.new(size) {|j|
       row = Array.new(size, 0)
       row[j] = values[j]
       row
@@ -200,7 +220,7 @@ class Matrix
   #        0 5
   #
   def Matrix.scalar(n, value)
-    Matrix.diagonal(*Array.new(n, value))
+    diagonal(*Array.new(n, value))
   end
 
   #
@@ -210,7 +230,7 @@ class Matrix
   #        0 1
   #
   def Matrix.identity(n)
-    Matrix.scalar(n, 1)
+    scalar(n, 1)
   end
   class << Matrix
     alias unit identity
@@ -218,13 +238,14 @@ class Matrix
   end
 
   #
-  # Creates an +n+ by +n+ zero matrix.
+  # Creates a zero matrix.
   #   Matrix.zero(2)
   #     => 0 0
   #        0 0
   #
-  def Matrix.zero(n)
-    Matrix.scalar(n, 0)
+  def Matrix.zero(row_count, column_count = row_count)
+    rows = Array.new(row_count){Array.new(column_count, 0)}
+    new rows, column_count
   end
 
   #
@@ -252,8 +273,8 @@ class Matrix
   end
 
   #
-  # Creates a empty matrix of +row_size+ x +column_size+.
-  # At least one of +row_size+ or +column_size+ must be 0.
+  # Creates a empty matrix of +row_count+ x +column_count+.
+  # At least one of +row_count+ or +column_count+ must be 0.
   #
   #   m = Matrix.empty(2, 0)
   #   m == Matrix[ [], [] ]
@@ -264,26 +285,26 @@ class Matrix
   #   m * n
   #     => Matrix[[0, 0, 0], [0, 0, 0]]
   #
-  def Matrix.empty(row_size = 0, column_size = 0)
-    Matrix.Raise ArgumentError, "One size must be 0" if column_size != 0 && row_size != 0
-    Matrix.Raise ArgumentError, "Negative size" if column_size < 0 || row_size < 0
+  def Matrix.empty(row_count = 0, column_count = 0)
+    raise ArgumentError, "One size must be 0" if column_count != 0 && row_count != 0
+    raise ArgumentError, "Negative size" if column_count < 0 || row_count < 0
 
-    new([[]]*row_size, column_size)
+    new([[]]*row_count, column_count)
   end
 
   #
   # Matrix.new is private; use Matrix.rows, columns, [], etc... to create.
   #
-  def initialize(rows, column_size = rows[0].size)
+  def initialize(rows, column_count = rows[0].size)
     # No checking is done at this point. rows must be an Array of Arrays.
-    # column_size must be the size of the first row, if there is one,
+    # column_count must be the size of the first row, if there is one,
     # otherwise it *must* be specified and can be any integer >= 0
     @rows = rows
-    @column_size = column_size
+    @column_count = column_count
   end
 
-  def new_matrix(rows, column_size = rows[0].size) # :nodoc:
-    Matrix.send(:new, rows, column_size) # bypass privacy of Matrix.new
+  def new_matrix(rows, column_count = rows[0].size) # :nodoc:
+    self.class.send(:new, rows, column_count) # bypass privacy of Matrix.new
   end
   private :new_matrix
 
@@ -306,14 +327,16 @@ class Matrix
   #
   # Returns the number of rows.
   #
-  def row_size
+  def row_count
     @rows.size
   end
 
+  alias_method :row_size, :row_count
   #
   # Returns the number of columns.
   #
-  attr_reader :column_size
+  attr_reader :column_count
+  alias_method :column_size, :column_count
 
   #
   # Returns row vector number +i+ of the matrix as a Vector (starting at 0 like
@@ -335,14 +358,14 @@ class Matrix
   #
   def column(j) # :yield: e
     if block_given?
-      return self if j >= column_size || j < -column_size
-      row_size.times do |i|
+      return self if j >= column_count || j < -column_count
+      row_count.times do |i|
         yield @rows[i][j]
       end
       self
     else
-      return nil if j >= column_size || j < -column_size
-      col = (0 ... row_size).collect {|i|
+      return nil if j >= column_count || j < -column_count
+      col = Array.new(row_count) {|i|
         @rows[i][j]
       }
       Vector.elements(col, false)
@@ -359,46 +382,167 @@ class Matrix
   def collect(&block) # :yield: e
     return to_enum(:collect) unless block_given?
     rows = @rows.collect{|row| row.collect(&block)}
-    new_matrix rows, column_size
+    new_matrix rows, column_count
   end
   alias map collect
 
   #
   # Yields all elements of the matrix, starting with those of the first row,
-  # or returns an Enumerator is no block given
+  # or returns an Enumerator is no block given.
+  # Elements can be restricted by passing an argument:
+  # * :all (default): yields all elements
+  # * :diagonal: yields only elements on the diagonal
+  # * :off_diagonal: yields all elements except on the diagonal
+  # * :lower: yields only elements on or below the diagonal
+  # * :strict_lower: yields only elements below the diagonal
+  # * :strict_upper: yields only elements above the diagonal
+  # * :upper: yields only elements on or above the diagonal
+  #
   #   Matrix[ [1,2], [3,4] ].each { |e| puts e }
   #     # => prints the numbers 1 to 4
-  #
-  def each(&block) # :yield: e
-    return to_enum(:each) unless block_given?
-    @rows.each do |row|
-      row.each(&block)
+  #   Matrix[ [1,2], [3,4] ].each(:strict_lower).to_a # => [3]
+  #
+  def each(which = :all) # :yield: e
+    return to_enum :each, which unless block_given?
+    last = column_count - 1
+    case which
+    when :all
+      block = Proc.new
+      @rows.each do |row|
+        row.each(&block)
+      end
+    when :diagonal
+      @rows.each_with_index do |row, row_index|
+        yield row.fetch(row_index){return self}
+      end
+    when :off_diagonal
+      @rows.each_with_index do |row, row_index|
+        column_count.times do |col_index|
+          yield row[col_index] unless row_index == col_index
+        end
+      end
+    when :lower
+      @rows.each_with_index do |row, row_index|
+        0.upto([row_index, last].min) do |col_index|
+          yield row[col_index]
+        end
+      end
+    when :strict_lower
+      @rows.each_with_index do |row, row_index|
+        [row_index, column_count].min.times do |col_index|
+          yield row[col_index]
+        end
+      end
+    when :strict_upper
+      @rows.each_with_index do |row, row_index|
+        (row_index+1).upto(last) do |col_index|
+          yield row[col_index]
+        end
+      end
+    when :upper
+      @rows.each_with_index do |row, row_index|
+        row_index.upto(last) do |col_index|
+          yield row[col_index]
+        end
+      end
+    else
+      raise ArgumentError, "expected #{which.inspect} to be one of :all, :diagonal, :off_diagonal, :lower, :strict_lower, :strict_upper or :upper"
     end
     self
   end
 
   #
-  # Yields all elements of the matrix, starting with those of the first row,
-  # along with the row index and column index,
-  # or returns an Enumerator is no block given
+  # Same as #each, but the row index and column index in addition to the element
+  #
   #   Matrix[ [1,2], [3,4] ].each_with_index do |e, row, col|
   #     puts "#{e} at #{row}, #{col}"
   #   end
-  #     # => 1 at 0, 0
-  #     # => 2 at 0, 1
-  #     # => 3 at 1, 0
-  #     # => 4 at 1, 1
-  #
-  def each_with_index(&block) # :yield: e, row, column
-    return to_enum(:each_with_index) unless block_given?
-    @rows.each_with_index do |row, row_index|
-      row.each_with_index do |e, col_index|
-        yield e, row_index, col_index
+  #     # => Prints:
+  #     #    1 at 0, 0
+  #     #    2 at 0, 1
+  #     #    3 at 1, 0
+  #     #    4 at 1, 1
+  #
+  def each_with_index(which = :all) # :yield: e, row, column
+    return to_enum :each_with_index, which unless block_given?
+    last = column_count - 1
+    case which
+    when :all
+      @rows.each_with_index do |row, row_index|
+        row.each_with_index do |e, col_index|
+          yield e, row_index, col_index
+        end
       end
+    when :diagonal
+      @rows.each_with_index do |row, row_index|
+        yield row.fetch(row_index){return self}, row_index, row_index
+      end
+    when :off_diagonal
+      @rows.each_with_index do |row, row_index|
+        column_count.times do |col_index|
+          yield row[col_index], row_index, col_index unless row_index == col_index
+        end
+      end
+    when :lower
+      @rows.each_with_index do |row, row_index|
+        0.upto([row_index, last].min) do |col_index|
+          yield row[col_index], row_index, col_index
+        end
+      end
+    when :strict_lower
+      @rows.each_with_index do |row, row_index|
+        [row_index, column_count].min.times do |col_index|
+          yield row[col_index], row_index, col_index
+        end
+      end
+    when :strict_upper
+      @rows.each_with_index do |row, row_index|
+        (row_index+1).upto(last) do |col_index|
+          yield row[col_index], row_index, col_index
+        end
+      end
+    when :upper
+      @rows.each_with_index do |row, row_index|
+        row_index.upto(last) do |col_index|
+          yield row[col_index], row_index, col_index
+        end
+      end
+    else
+      raise ArgumentError, "expected #{which.inspect} to be one of :all, :diagonal, :off_diagonal, :lower, :strict_lower, :strict_upper or :upper"
     end
     self
   end
 
+  SELECTORS = {all: true, diagonal: true, off_diagonal: true, lower: true, strict_lower: true, strict_upper: true, upper: true}.freeze
+  #
+  # :call-seq:
+  #   index(value, selector = :all) -> [row, column]
+  #   index(selector = :all){ block } -> [row, column]
+  #   index(selector = :all) -> an_enumerator
+  #
+  # The index method is specialized to return the index as [row, column]
+  # It also accepts an optional +selector+ argument, see #each for details.
+  #
+  #   Matrix[ [1,2], [3,4] ].index(&:even?) # => [0, 1]
+  #   Matrix[ [1,1], [1,1] ].index(1, :strict_lower) # => [1, 0]
+  #
+  def index(*args)
+    raise ArgumentError, "wrong number of arguments(#{args.size} for 0-2)" if args.size > 2
+    which = (args.size == 2 || SELECTORS.include?(args.last)) ? args.pop : :all
+    return to_enum :find_index, which, *args unless block_given? || args.size == 1
+    if args.size == 1
+      value = args.first
+      each_with_index(which) do |e, row_index, col_index|
+        return row_index, col_index if e == value
+      end
+    else
+      each_with_index(which) do |e, row_index, col_index|
+        return row_index, col_index if yield e
+      end
+    end
+    nil
+  end
+  alias_method :find_index, :index
   #
   # Returns a section of the matrix.  The parameters are either:
   # *  start_row, nrows, start_col, ncols; OR
@@ -410,51 +554,136 @@ class Matrix
   #
   # Like Array#[], negative indices count backward from the end of the
   # row or column (-1 is the last element). Returns nil if the starting
-  # row or column is greater than row_size or column_size respectively.
+  # row or column is greater than row_count or column_count respectively.
   #
   def minor(*param)
     case param.size
     when 2
       row_range, col_range = param
       from_row = row_range.first
-      from_row += row_size if from_row < 0
+      from_row += row_count if from_row < 0
       to_row = row_range.end
-      to_row += row_size if to_row < 0
+      to_row += row_count if to_row < 0
       to_row += 1 unless row_range.exclude_end?
       size_row = to_row - from_row
 
       from_col = col_range.first
-      from_col += column_size if from_col < 0
+      from_col += column_count if from_col < 0
       to_col = col_range.end
-      to_col += column_size if to_col < 0
+      to_col += column_count if to_col < 0
       to_col += 1 unless col_range.exclude_end?
       size_col = to_col - from_col
     when 4
       from_row, size_row, from_col, size_col = param
       return nil if size_row < 0 || size_col < 0
-      from_row += row_size if from_row < 0
-      from_col += column_size if from_col < 0
+      from_row += row_count if from_row < 0
+      from_col += column_count if from_col < 0
     else
-      Matrix.Raise ArgumentError, param.inspect
+      raise ArgumentError, param.inspect
     end
 
-    return nil if from_row > row_size || from_col > column_size || from_row < 0 || from_col < 0
+    return nil if from_row > row_count || from_col > column_count || from_row < 0 || from_col < 0
     rows = @rows[from_row, size_row].collect{|row|
       row[from_col, size_col]
     }
-    new_matrix rows, column_size - from_col
+    new_matrix rows, [column_count - from_col, size_col].min
   end
 
   #--
   # TESTING -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
   #++
 
+  #
+  # Returns +true+ is this is a diagonal matrix.
+  # Raises an error if matrix is not square.
+  #
+  def diagonal?
+    Matrix.Raise ErrDimensionMismatch unless square?
+    each(:off_diagonal).all?(&:zero?)
+  end
+
   #
   # Returns +true+ if this is an empty matrix, i.e. if the number of rows
   # or the number of columns is 0.
   #
   def empty?
-    column_size == 0 || row_size == 0
+    column_count == 0 || row_count == 0
+  end
+
+  #
+  # Returns +true+ is this is an hermitian matrix.
+  # Raises an error if matrix is not square.
+  #
+  def hermitian?
+    Matrix.Raise ErrDimensionMismatch unless square?
+    each_with_index(:upper).all? do |e, row, col|
+      e == rows[col][row].conj
+    end
+  end
+
+  #
+  # Returns +true+ is this is a lower triangular matrix.
+  #
+  def lower_triangular?
+    each(:strict_upper).all?(&:zero?)
+  end
+
+  #
+  # Returns +true+ is this is a normal matrix.
+  # Raises an error if matrix is not square.
+  #
+  def normal?
+    Matrix.Raise ErrDimensionMismatch unless square?
+    rows.each_with_index do |row_i, i|
+      rows.each_with_index do |row_j, j|
+        s = 0
+        rows.each_with_index do |row_k, k|
+          s += row_i[k] * row_j[k].conj - row_k[i].conj * row_k[j]
+        end
+        return false unless s == 0
+      end
+    end
+    true
+  end
+
+  #
+  # Returns +true+ is this is an orthogonal matrix
+  # Raises an error if matrix is not square.
+  #
+  def orthogonal?
+    Matrix.Raise ErrDimensionMismatch unless square?
+    rows.each_with_index do |row, i|
+      column_count.times do |j|
+        s = 0
+        row_count.times do |k|
+          s += row[k] * rows[k][j]
+        end
+        return false unless s == (i == j ? 1 : 0)
+      end
+    end
+    true
+  end
+
+  #
+  # Returns +true+ is this is a permutation matrix
+  # Raises an error if matrix is not square.
+  #
+  def permutation?
+    Matrix.Raise ErrDimensionMismatch unless square?
+    cols = Array.new(column_count)
+    rows.each_with_index do |row, i|
+      found = false
+      row.each_with_index do |e, j|
+        if e == 1
+          return false if found || cols[j]
+          found = cols[j] = true
+        elsif e != 0
+          return false
+        end
+      end
+      return false unless found
+    end
+    true
   end
 
   #
@@ -482,7 +711,51 @@ class Matrix
   # Returns +true+ is this is a square matrix.
   #
   def square?
-    column_size == row_size
+    column_count == row_count
+  end
+
+  #
+  # Returns +true+ is this is a symmetric matrix.
+  # Raises an error if matrix is not square.
+  #
+  def symmetric?
+    Matrix.Raise ErrDimensionMismatch unless square?
+    each_with_index(:strict_upper) do |e, row, col|
+      return false if e != rows[col][row]
+    end
+    true
+  end
+
+  #
+  # Returns +true+ is this is a unitary matrix
+  # Raises an error if matrix is not square.
+  #
+  def unitary?
+    Matrix.Raise ErrDimensionMismatch unless square?
+    rows.each_with_index do |row, i|
+      column_count.times do |j|
+        s = 0
+        row_count.times do |k|
+          s += row[k].conj * rows[k][j]
+        end
+        return false unless s == (i == j ? 1 : 0)
+      end
+    end
+    true
+  end
+
+  #
+  # Returns +true+ is this is an upper triangular matrix.
+  #
+  def upper_triangular?
+    each(:strict_lower).all?(&:zero?)
+  end
+
+  #
+  # Returns +true+ is this is a matrix with only zero elements
+  #
+  def zero?
+    all?(&:zero?)
   end
 
   #--
@@ -493,12 +766,14 @@ class Matrix
   # Returns +true+ if and only if the two matrices contain equal elements.
   #
   def ==(other)
-    return false unless Matrix === other
+    return false unless Matrix === other &&
+                        column_count == other.column_count # necessary for empty matrices
     rows == other.rows
   end
 
   def eql?(other)
-    return false unless Matrix === other
+    return false unless Matrix === other &&
+                        column_count == other.column_count # necessary for empty matrices
     rows.eql? other.rows
   end
 
@@ -508,7 +783,7 @@ class Matrix
   # There should be no good reason to do this since Matrices are immutable.
   #
   def clone
-    new_matrix @rows.map(&:dup), column_size
+    new_matrix @rows.map(&:dup), column_count
   end
 
   #
@@ -532,26 +807,24 @@ class Matrix
     case(m)
     when Numeric
       rows = @rows.collect {|row|
-        row.collect {|e|
-          e * m
-        }
+        row.collect {|e| e * m }
       }
-      return new_matrix rows, column_size
+      return new_matrix rows, column_count
     when Vector
-      m = Matrix.column_vector(m)
+      m = self.class.column_vector(m)
       r = self * m
       return r.column(0)
     when Matrix
-      Matrix.Raise ErrDimensionMismatch if column_size != m.row_size
+      Matrix.Raise ErrDimensionMismatch if column_count != m.row_count
 
-      rows = (0 ... row_size).collect {|i|
-        (0 ... m.column_size).collect {|j|
-          (0 ... column_size).inject(0) do |vij, k|
+      rows = Array.new(row_count) {|i|
+        Array.new(m.column_count) {|j|
+          (0 ... column_count).inject(0) do |vij, k|
             vij + self[i, k] * m[k, j]
           end
         }
       }
-      return new_matrix rows, m.column_size
+      return new_matrix rows, m.column_count
     else
       return apply_through_coercion(m, __method__)
     end
@@ -568,20 +841,20 @@ class Matrix
     when Numeric
       Matrix.Raise ErrOperationNotDefined, "+", self.class, m.class
     when Vector
-      m = Matrix.column_vector(m)
+      m = self.class.column_vector(m)
     when Matrix
     else
       return apply_through_coercion(m, __method__)
     end
 
-    Matrix.Raise ErrDimensionMismatch unless row_size == m.row_size and column_size == m.column_size
+    Matrix.Raise ErrDimensionMismatch unless row_count == m.row_count and column_count == m.column_count
 
-    rows = (0 ... row_size).collect {|i|
-      (0 ... column_size).collect {|j|
+    rows = Array.new(row_count) {|i|
+      Array.new(column_count) {|j|
         self[i, j] + m[i, j]
       }
     }
-    new_matrix rows, column_size
+    new_matrix rows, column_count
   end
 
   #
@@ -595,20 +868,20 @@ class Matrix
     when Numeric
       Matrix.Raise ErrOperationNotDefined, "-", self.class, m.class
     when Vector
-      m = Matrix.column_vector(m)
+      m = self.class.column_vector(m)
     when Matrix
     else
       return apply_through_coercion(m, __method__)
     end
 
-    Matrix.Raise ErrDimensionMismatch unless row_size == m.row_size and column_size == m.column_size
+    Matrix.Raise ErrDimensionMismatch unless row_count == m.row_count and column_count == m.column_count
 
-    rows = (0 ... row_size).collect {|i|
-      (0 ... column_size).collect {|j|
+    rows = Array.new(row_count) {|i|
+      Array.new(column_count) {|j|
         self[i, j] - m[i, j]
       }
     }
-    new_matrix rows, column_size
+    new_matrix rows, column_count
   end
 
   #
@@ -621,11 +894,9 @@ class Matrix
     case other
     when Numeric
       rows = @rows.collect {|row|
-        row.collect {|e|
-          e / other
-        }
+        row.collect {|e| e / other }
       }
-      return new_matrix rows, column_size
+      return new_matrix rows, column_count
     when Matrix
       return self * other.inverse
     else
@@ -641,12 +912,12 @@ class Matrix
   #
   def inverse
     Matrix.Raise ErrDimensionMismatch unless square?
-    Matrix.I(row_size).send(:inverse_from, self)
+    self.class.I(row_count).send(:inverse_from, self)
   end
   alias inv inverse
 
   def inverse_from(src) # :nodoc:
-    last = row_size - 1
+    last = row_count - 1
     a = src.to_a
 
     0.upto(last) do |k|
@@ -691,8 +962,10 @@ class Matrix
   private :inverse_from
 
   #
-  # Matrix exponentiation.  Currently implemented for integer powers only.
+  # Matrix exponentiation.
   # Equivalent to multiplying the matrix by itself N times.
+  # Non integer exponents will be handled by diagonalizing the matrix.
+  #
   #   Matrix[[7,6], [3,9]] ** 2
   #     => 67 96
   #        48 99
@@ -703,7 +976,7 @@ class Matrix
       x = self
       if other <= 0
         x = self.inverse
-        return Matrix.identity(self.column_size) if other == 0
+        return self.class.identity(self.column_count) if other == 0
         other = -other
       end
       z = nil
@@ -712,6 +985,9 @@ class Matrix
         return z if (other >>= 1).zero?
         x *= x
       end
+    when Numeric
+      v, d, v_inv = eigensystem
+      v * self.class.diagonal(*d.each(:diagonal).map{|e| e ** other}) * v_inv
     else
       Matrix.Raise ErrOperationNotDefined, "**", self.class, other.class
     end
@@ -734,7 +1010,7 @@ class Matrix
   def determinant
     Matrix.Raise ErrDimensionMismatch unless square?
     m = @rows
-    case row_size
+    case row_count
       # Up to 4x4, give result using Laplacian expansion by minors.
       # This will typically be faster, as well as giving good results
       # in case of Floats
@@ -783,7 +1059,7 @@ class Matrix
   # intermediate results with better precision.
   #
   def determinant_bareiss
-    size = row_size
+    size = row_count
     last = size - 1
     a = to_a
     no_pivot = Proc.new{ return 0 }
@@ -815,7 +1091,7 @@ class Matrix
   #
   def determinant_e
     warn "#{caller(1)[0]}: warning: Matrix#determinant_e is deprecated; use #determinant"
-    rank
+    determinant
   end
   alias det_e determinant_e
 
@@ -832,9 +1108,8 @@ class Matrix
     # We currently use Bareiss' multistep integer-preserving gaussian elimination
     # (see comments on determinant)
     a = to_a
-    last_column = column_size - 1
-    last_row = row_size - 1
-    rank = 0
+    last_column = column_count - 1
+    last_row = row_count - 1
     pivot_row = 0
     previous_pivot = 1
     0.upto(last_column) do |k|
@@ -865,6 +1140,12 @@ class Matrix
     rank
   end
 
+  # Returns a matrix with entries rounded to the given precision
+  # (see Float#round)
+  #
+  def round(ndigits=0)
+    map{|e| e.round(ndigits)}
+  end
 
   #
   # Returns the trace (sum of diagonal elements) of the matrix.
@@ -873,7 +1154,7 @@ class Matrix
   #
   def trace
     Matrix.Raise ErrDimensionMismatch unless square?
-    (0...column_size).inject(0) do |tr, i|
+    (0...column_count).inject(0) do |tr, i|
       tr + @rows[i][i]
     end
   end
@@ -890,11 +1171,43 @@ class Matrix
   #        2 4 6
   #
   def transpose
-    return Matrix.empty(column_size, 0) if row_size.zero?
-    new_matrix @rows.transpose, row_size
+    return self.class.empty(column_count, 0) if row_count.zero?
+    new_matrix @rows.transpose, row_count
   end
   alias t transpose
 
+  #--
+  # DECOMPOSITIONS -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+  #++
+
+  #
+  # Returns the Eigensystem of the matrix; see +EigenvalueDecomposition+.
+  #   m = Matrix[[1, 2], [3, 4]]
+  #   v, d, v_inv = m.eigensystem
+  #   d.diagonal? # => true
+  #   v.inv == v_inv # => true
+  #   (v * d * v_inv).round(5) == m # => true
+  #
+  def eigensystem
+    EigenvalueDecomposition.new(self)
+  end
+  alias eigen eigensystem
+
+  #
+  # Returns the LUP decomposition of the matrix; see +LUPDecomposition+.
+  #   a = Matrix[[1, 2], [3, 4]]
+  #   l, u, p = a.lup
+  #   l.lower_triangular? # => true
+  #   u.upper_triangular? # => true
+  #   p.permutation?      # => true
+  #   l * u == p * a      # => true
+  #   a.lup.solve([2, 5]) # => Vector[(1/1), (1/2)]
+  #
+  def lup
+    LUPDecomposition.new(self)
+  end
+  alias lup_decomposition lup
+
   #--
   # COMPLEX ARITHMETIC -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   #++
@@ -975,7 +1288,7 @@ class Matrix
   # Returns an array of the row vectors of the matrix.  See Vector.
   #
   def row_vectors
-    (0 ... row_size).collect {|i|
+    Array.new(row_count) {|i|
       row(i)
     }
   end
@@ -984,7 +1297,7 @@ class Matrix
   # Returns an array of the column vectors of the matrix.  See Vector.
   #
   def column_vectors
-    (0 ... column_size).collect {|i|
+    Array.new(column_count) {|i|
       column(i)
     }
   end
@@ -993,7 +1306,7 @@ class Matrix
   # Returns an array of arrays that describe the rows of the matrix.
   #
   def to_a
-    @rows.collect{|row| row.dup}
+    @rows.collect(&:dup)
   end
 
   def elements_to_f
@@ -1020,9 +1333,9 @@ class Matrix
   #
   def to_s
     if empty?
-      "Matrix.empty(#{row_size}, #{column_size})"
+      "#{self.class}.empty(#{row_count}, #{column_count})"
     else
-      "Matrix[" + @rows.collect{|row|
+      "#{self.class}[" + @rows.collect{|row|
         "[" + row.collect{|e| e.to_s}.join(", ") + "]"
       }.join(", ")+"]"
     end
@@ -1033,9 +1346,9 @@ class Matrix
   #
   def inspect
     if empty?
-      "Matrix.empty(#{row_size}, #{column_size})"
+      "#{self.class}.empty(#{row_count}, #{column_count})"
     else
-      "Matrix#{@rows.inspect}"
+      "#{self.class}#{@rows.inspect}"
     end
   end
 
@@ -1189,37 +1502,41 @@ end
 # == Method Catalogue
 #
 # To create a Vector:
-# * <tt>  Vector.[](*array)                   </tt>
-# * <tt>  Vector.elements(array, copy = true) </tt>
+# * Vector.[](*array)
+# * Vector.elements(array, copy = true)
 #
 # To access elements:
-# * <tt>  [](i)                               </tt>
+# * #[](i)
 #
 # To enumerate the elements:
-# * <tt> #each2(v)                            </tt>
-# * <tt> #collect2(v)                         </tt>
+# * #each2(v)
+# * #collect2(v)
 #
 # Vector arithmetic:
-# * <tt>  *(x) "is matrix or number"          </tt>
-# * <tt>  +(v)                                </tt>
-# * <tt>  -(v)                                </tt>
+# * #*(x) "is matrix or number"
+# * #+(v)
+# * #-(v)
 #
 # Vector functions:
-# * <tt> #inner_product(v)                    </tt>
-# * <tt> #collect                             </tt>
-# * <tt> #map                                 </tt>
-# * <tt> #map2(v)                             </tt>
-# * <tt> #r                                   </tt>
-# * <tt> #size                                </tt>
+# * #inner_product(v)
+# * #cross_product(v)
+# * #collect
+# * #magnitude
+# * #map
+# * #map2(v)
+# * #norm
+# * #normalize
+# * #r
+# * #size
 #
 # Conversion to other data types:
-# * <tt> #covector                            </tt>
-# * <tt> #to_a                                </tt>
-# * <tt> #coerce(other)                       </tt>
+# * #covector
+# * #to_a
+# * #coerce(other)
 #
 # String representations:
-# * <tt> #to_s                                </tt>
-# * <tt> #inspect                             </tt>
+# * #to_s
+# * #inspect
 #
 class Vector
   include ExceptionForMatrix
@@ -1237,7 +1554,7 @@ class Vector
   #   Vector[7, 4, ...]
   #
   def Vector.[](*array)
-    new convert_to_array(array, copy = false)
+    new convert_to_array(array, false)
   end
 
   #
@@ -1315,7 +1632,7 @@ class Vector
     raise TypeError, "Integer is not like Vector" if v.kind_of?(Integer)
     Vector.Raise ErrDimensionMismatch if size != v.size
     return to_enum(:collect2, v) unless block_given?
-    size.times.collect do |i|
+    Array.new(size) do |i|
       yield @elements[i], v[i]
     end
   end
@@ -1341,7 +1658,7 @@ class Vector
   # Return a copy of the vector.
   #
   def clone
-    Vector.elements(@elements)
+    self.class.elements(@elements)
   end
 
   #
@@ -1362,7 +1679,7 @@ class Vector
     case x
     when Numeric
       els = @elements.collect{|e| e * x}
-      Vector.elements(els, false)
+      self.class.elements(els, false)
     when Matrix
       Matrix.column_vector(self) * x
     when Vector
@@ -1382,7 +1699,7 @@ class Vector
       els = collect2(v) {|v1, v2|
         v1 + v2
       }
-      Vector.elements(els, false)
+      self.class.elements(els, false)
     when Matrix
       Matrix.column_vector(self) + v
     else
@@ -1400,7 +1717,7 @@ class Vector
       els = collect2(v) {|v1, v2|
         v1 - v2
       }
-      Vector.elements(els, false)
+      self.class.elements(els, false)
     when Matrix
       Matrix.column_vector(self) - v
     else
@@ -1415,7 +1732,7 @@ class Vector
     case x
     when Numeric
       els = @elements.collect{|e| e / x}
-      Vector.elements(els, false)
+      self.class.elements(els, false)
     when Matrix, Vector
       Vector.Raise ErrOperationNotDefined, "/", self.class, x.class
     else
@@ -1436,36 +1753,63 @@ class Vector
 
     p = 0
     each2(v) {|v1, v2|
-      p += v1 * v2
+      p += v1 * v2.conj
     }
     p
   end
 
+  #
+  # Returns the cross product of this vector with the other.
+  #   Vector[1, 0, 0].cross_product Vector[0, 1, 0]   => Vector[0, 0, 1]
+  #
+  def cross_product(v)
+    Vector.Raise ErrDimensionMismatch unless size == v.size && v.size == 3
+    Vector[ v[1]*@elements[2] - v[2]*@elements[1],
+            v[2]*@elements[0] - v[0]*@elements[2],
+            v[0]*@elements[1] - v[1]*@elements[0] ]
+  end
+
   #
   # Like Array#collect.
   #
   def collect(&block) # :yield: e
     return to_enum(:collect) unless block_given?
     els = @elements.collect(&block)
-    Vector.elements(els, false)
+    self.class.elements(els, false)
   end
   alias map collect
 
+  #
+  # Returns the modulus (Pythagorean distance) of the vector.
+  #   Vector[5,8,2].r => 9.643650761
+  #
+  def magnitude
+    Math.sqrt(@elements.inject(0) {|v, e| v + e.abs2})
+  end
+  alias r magnitude
+  alias norm magnitude
+
   #
   # Like Vector#collect2, but returns a Vector instead of an Array.
   #
   def map2(v, &block) # :yield: e1, e2
     return to_enum(:map2, v) unless block_given?
     els = collect2(v, &block)
-    Vector.elements(els, false)
+    self.class.elements(els, false)
   end
 
+  class ZeroVectorError < StandardError
+  end
   #
-  # Returns the modulus (Pythagorean distance) of the vector.
-  #   Vector[5,8,2].r => 9.643650761
+  # Returns a new vector with the same direction but with norm 1.
+  #   v = Vector[5,8,2].normalize
+  #   # => Vector[0.5184758473652127, 0.8295613557843402, 0.20739033894608505]
+  #   v.norm => 1.0
   #
-  def r
-    Math.sqrt(@elements.inject(0) {|v, e| v + e*e})
+  def normalize
+    n = magnitude
+    raise ZeroVectorError, "Zero vectors can not be normalized" if n == 0
+    self / n
   end
 
   #--
@@ -1532,6 +1876,6 @@ class Vector
   # Overrides Object#inspect
   #
   def inspect
-    str = "Vector"+@elements.inspect
+    "Vector" + @elements.inspect
   end
 end