123456789_123456789_123456789_123456789_123456789_

Class: Matrix

Relationships & Source Files
Namespace Children
Modules:
CoercionHelper, ConversionHelper
Classes:
EigenvalueDecomposition, LUPDecomposition, Scalar
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, ConversionHelper
Instance Chain:
self, CoercionHelper, ::ExceptionForMatrix, Enumerable
Inherits: Object
Defined in: lib/matrix.rb,
lib/matrix/eigenvalue_decomposition.rb,
lib/matrix/lup_decomposition.rb,
lib/matrix/version.rb

Overview

The Matrix class represents a mathematical matrix. It provides methods for creating matrices, operating on them arithmetically and algebraically, and determining their mathematical properties such as trace, rank, inverse, determinant, or eigensystem.

Constant Summary

Class Method Summary

ConversionHelper - Extended

convert_to_array

Converts the obj to an Array.

Instance Attribute Summary

Instance Method Summary

CoercionHelper - Included

#apply_through_coercion

Applies the operator oper with argument obj through coercion of obj

Constructor Details

.new(rows, column_count = rows[0].size) ⇒ Matrix

new is private; use .rows, .columns, .[], etc… to create.

[ GitHub ] 

  


# File 'lib/matrix.rb', line 322



def initialize(rows, column_count = rows[0].size)
  # No checking is done at this point. rows must be an Array of Arrays.
  # 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_count = column_count
end


  







Class Method Details



  

    .[](*rows)  
  



  

    

Creates a matrix where each argument is a row.



Matrix[ [25, 93], [-1, 66] ]
#   =>  25 93
#       -1 66


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 78



def Matrix.[](*rows)
  rows(rows, false)
end


  








  

    .build(row_count, column_count = row_count)  
  



  

    

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.



m = Matrix.build(2, 4) {|row, col| col - row }
#  => Matrix[[0, 1, 2, 3], [-1, 0, 1, 2]]
m = Matrix.build(3) { rand }
#  => a 3x3 matrix with random elements


  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 123



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_count
end


  








  

    .column_vector(column)  
  



  

    

Creates a single-column matrix where the values of that column are as given in #column.



Matrix.column_vector([4,5,6])
#  => 4
#     5
#     6


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 209



def Matrix.column_vector(column)
  column = convert_to_array(column)
  new [column].transpose, 1
end


  








  

    .columns(columns)  
  



  

    

Creates a matrix using columns as an array of column vectors.



Matrix.columns([[25, 93], [-1, 66]])
#   =>  25 -1
#       93 66


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 108



def Matrix.columns(columns)
  rows(columns, false).transpose
end


  








  

    .combine(*matrices) {|*elements| ... }   



  

    

Create a matrix by combining matrices entrywise, using the given block



x = Matrix[[6, 6], [4, 4]]
y = Matrix[[1, 2], [3, 4]]
Matrix.combine(x, y) {|a, b| a - b} # => Matrix[[5, 4], [1, 0]]


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 288



def Matrix.combine(*matrices)
  return to_enum(__method__, *matrices) unless block_given?

  return Matrix.empty if matrices.empty?
  matrices.map!(&CoercionHelper.method(:coerce_to_matrix))
  x = matrices.first
  matrices.each do |m|
    raise ErrDimensionMismatch unless x.row_count == m.row_count && x.column_count == m.column_count
  end

  rows = Array.new(x.row_count) do |i|
    Array.new(x.column_count) do |j|
      yield matrices.map{|m| m[i,j]}
    end
  end
  new rows, x.column_count
end


  








  

    .diagonal(*values)  
  



  

    

Creates a matrix where the diagonal elements are composed of values.



Matrix.diagonal(9, 5, -3)
#  =>  9  0  0
#      0  5  0
#      0  0 -3


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 143



def Matrix.diagonal(*values)
  size = values.size
  return Matrix.empty if size == 0
  rows = Array.new(size) {|j|
    row = Array.new(size, 0)
    row[j] = values[j]
    row
  }
  new rows
end


  








  

    .empty(row_count = 0, column_count = 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[ [], [] ]
#  => true
n = Matrix.empty(0, 3)
n == Matrix.columns([ [], [], [] ])
#  => true
m * n
#  => Matrix[[0, 0, 0], [0, 0, 0]]


  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 227



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_count, column_count)
end


  








  

    .hstack(x, *matrices)  
  



  

    

Create a matrix by stacking matrices horizontally



x = Matrix[[1, 2], [3, 4]]
y = Matrix[[5, 6], [7, 8]]
Matrix.hstack(x, y) # => Matrix[[1, 2, 5, 6], [3, 4, 7, 8]]


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 262



def Matrix.hstack(x, *matrices)
  x = CoercionHelper.coerce_to_matrix(x)
  result = x.send(:rows).map(&:dup)
  total_column_count = x.column_count
  matrices.each do |m|
    m = CoercionHelper.coerce_to_matrix(m)
    if m.row_count != x.row_count
      raise ErrDimensionMismatch, "The given matrices must have #{x.row_count} rows, but one has #{m.row_count}"
    end
    result.each_with_index do |row, i|
      row.concat m.send(:rows)[i]
    end
    total_column_count += m.column_count
  end
  new result, total_column_count
end


  








  

    I(n)  
  



  

    

Alias for .identity.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 176



alias_method :I, :identity


  








  

    .identity(n)  
    Also known as: .unit, .I
  



  

    

Creates an n by n identity matrix.



Matrix.identity(2)
#  => 1 0
#     0 1


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 171



def Matrix.identity(n)
  scalar(n, 1)
end


  








  

    .row_vector(row)  
  



  

    

Creates a single-row matrix where the values of that row are as given in #row.



Matrix.row_vector([4,5,6])
#  => 4 5 6


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 196



def Matrix.row_vector(row)
  row = convert_to_array(row)
  new [row]
end


  








  

    .rows(rows, copy = true)  
  



  

    

Creates a matrix where rows is an array of arrays, each of which is a row of the matrix.  If the optional argument copy is false, use the given arrays as the internal structure of the matrix without copying.



Matrix.rows([[25, 93], [-1, 66]])
#   =>  25 93
#       -1 66


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 90



def Matrix.rows(rows, copy = true)
  rows = convert_to_array(rows, copy)
  rows.map! do |row|
    convert_to_array(row, copy)
  end
  size = (rows[0] || []).size
  rows.each do |row|
    raise ErrDimensionMismatch, "row size differs (#{row.size} should be #{size})" unless row.size == size
  end
  new rows, size
end


  








  

    .scalar(n, value)  
  



  

    

Creates an n by n diagonal matrix where each diagonal element is value.



Matrix.scalar(2, 5)
#  => 5 0
#     0 5


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 161



def Matrix.scalar(n, value)
  diagonal(*Array.new(n, value))
end


  








  

    .unit(n)  
  



  

    

Alias for .identity.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 175



alias_method :unit, :identity


  








  

    .vstack(x, *matrices)  
  



  

    

Create a matrix by stacking matrices vertically



x = Matrix[[1, 2], [3, 4]]
y = Matrix[[5, 6], [7, 8]]
Matrix.vstack(x, y) # => Matrix[[1, 2], [3, 4], [5, 6], [7, 8]]


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 241



def Matrix.vstack(x, *matrices)
  x = CoercionHelper.coerce_to_matrix(x)
  result = x.send(:rows).map(&:dup)
  matrices.each do |m|
    m = CoercionHelper.coerce_to_matrix(m)
    if m.column_count != x.column_count
      raise ErrDimensionMismatch, "The given matrices must have #{x.column_count} columns, but one has #{m.column_count}"
    end
    result.concat(m.send(:rows))
  end
  new result, x.column_count
end


  








  

    .zero(row_count, column_count = row_count)  
  



  

    

Creates a zero matrix.



Matrix.zero(2)
#  => 0 0
#     0 0


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 185



def Matrix.zero(row_count, column_count = row_count)
  rows = Array.new(row_count){Array.new(column_count, 0)}
  new rows, column_count
end


  







Instance Attribute Details



  

    #antisymmetric?  ⇒ Boolean  (readonly)
    Also known as: #skew_symmetric?
  



  

    

Returns true if this is an antisymmetric matrix. Raises an error if matrix is not square.


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 973



def antisymmetric?
  raise ErrDimensionMismatch unless square?
  each_with_index(:upper) do |e, row, col|
    return false unless e == -rows[col][row]
  end
  true
end


  








  

    #column_count   (readonly)
    Also known as: #column_size
  



  

    

Returns the number of columns.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 456



attr_reader :column_count


  








  

    #column_size   (readonly)
  



  

    

Alias for #column_count.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 457



alias_method :column_size, :column_count


  








  

    #diagonal?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a diagonal matrix. Raises an error if matrix is not square.


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 839



def diagonal?
  raise ErrDimensionMismatch unless square?
  each(:off_diagonal).all?(&:zero?)
end


  








  

    #empty?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is an empty matrix, i.e. if the number of rows or the number of columns is 0.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 848



def empty?
  column_count == 0 || row_count == 0
end


  








  

    #hermitian?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is an hermitian matrix. Raises an error if matrix is not square.


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 856



def hermitian?
  raise ErrDimensionMismatch unless square?
  each_with_index(:upper).all? do |e, row, col|
    e == rows[col][row].conj
  end
end


  








  

    #lower_triangular?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a lower triangular matrix.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 866



def lower_triangular?
  each(:strict_upper).all?(&:zero?)
end


  








  

    #normal?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a normal matrix. Raises an error if matrix is not square.


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 874



def normal?
  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


  








  

    #orthogonal?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is an orthogonal matrix Raises an error if matrix is not square.


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 892



def orthogonal?
  raise ErrDimensionMismatch unless square?

  rows.each_with_index do |row_i, i|
    rows.each_with_index do |row_j, j|
      s = 0
      row_count.times do |k|
        s += row_i[k] * row_j[k]
      end
      return false unless s == (i == j ? 1 : 0)
    end
  end
  true
end


  








  

    #permutation?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a permutation matrix Raises an error if matrix is not square.


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 911



def permutation?
  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


  








  

    #real?  ⇒ Boolean  (readonly)
  



  

    

Returns true if all entries of the matrix are real.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 932



def real?
  all?(&:real?)
end


  








  

    #regular?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a regular (i.e. non-singular) matrix.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 939



def regular?
  not singular?
end


  








  

    #rows   (readonly, protected)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 69



attr_reader :rows


  








  

    #singular?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a singular matrix.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 946



def singular?
  determinant == 0
end


  








  

    #skew_symmetric?   (readonly)
  



  

    

Alias for #antisymmetric?.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 980



alias_method :skew_symmetric?, :antisymmetric?


  








  

    #square?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a square matrix.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 953



def square?
  column_count == row_count
end


  








  

    #symmetric?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a symmetric matrix. Raises an error if matrix is not square.


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 961



def symmetric?
  raise ErrDimensionMismatch unless square?
  each_with_index(:strict_upper) do |e, row, col|
    return false if e != rows[col][row]
  end
  true
end


  








  

    #unitary?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a unitary matrix Raises an error if matrix is not square.


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 986



def unitary?
  raise ErrDimensionMismatch unless square?
  rows.each_with_index do |row_i, i|
    rows.each_with_index do |row_j, j|
      s = 0
      row_count.times do |k|
        s += row_i[k].conj * row_j[k]
      end
      return false unless s == (i == j ? 1 : 0)
    end
  end
  true
end


  








  

    #upper_triangular?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is an upper triangular matrix.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1003



def upper_triangular?
  each(:strict_lower).all?(&:zero?)
end


  








  

    #zero?  ⇒ Boolean  (readonly)
  



  

    

Returns true if this is a matrix with only zero elements


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1010



def zero?
  all?(&:zero?)
end


  







Instance Method Details



  

    #*(m)  
  



  

    

Matrix multiplication.



Matrix[[2,4], [6,8]] * Matrix.identity(2)
#  => 2 4
#     6 8


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1058



def *(m) # m is matrix or vector or number
  case(m)
  when Numeric
    new_rows = @rows.collect {|row|
      row.collect {|e| e * m }
    }
    return new_matrix new_rows, column_count
  when Vector
    m = self.class.column_vector(m)
    r = self * m
    return r.column(0)
  when Matrix
    raise ErrDimensionMismatch if column_count != m.row_count
    m_rows = m.rows
    new_rows = rows.map do |row_i|
      Array.new(m.column_count) do |j|
        vij = 0
        column_count.times do |k|
          vij += row_i[k] * m_rows[k][j]
        end
        vij
      end
    end
    return new_matrix new_rows, m.column_count
  else
    return apply_through_coercion(m, __method__)
  end
end


  








  

    #**(exp)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1237



def **(exp)
  case exp
  when Integer
    case
    when exp == 0
      raise ErrDimensionMismatch unless square?
      self.class.identity(column_count)
    when exp < 0
      inverse.power_int(-exp)
    else
      power_int(exp)
    end
  when Numeric
    v, d, v_inv = eigensystem
    v * self.class.diagonal(*d.each(:diagonal).map{|e| e ** exp}) * v_inv
  else
    raise ErrOperationNotDefined, ["**", self.class, exp.class]
  end
end


  








  

    #+(m)  
  



  

    

Matrix addition.



Matrix.scalar(2,5) + Matrix[[1,0], [-4,7]]
#  =>  6  0
#     -4 12


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1093



def +(m)
  case m
  when Numeric
    raise ErrOperationNotDefined, ["+", self.class, m.class]
  when Vector
    m = self.class.column_vector(m)
  when Matrix
  else
    return apply_through_coercion(m, __method__)
  end

  raise ErrDimensionMismatch unless row_count == m.row_count && column_count == m.column_count

  rows = Array.new(row_count) {|i|
    Array.new(column_count) {|j|
      self[i, j] + m[i, j]
    }
  }
  new_matrix rows, column_count
end


  








  

    #+@  
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1283



def +@
  self
end


  








  

    #-(m)  
  



  

    

Matrix subtraction.



Matrix[[1,5], [4,2]] - Matrix[[9,3], [-4,1]]
#  => -8  2
#      8  1


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1120



def -(m)
  case m
  when Numeric
    raise ErrOperationNotDefined, ["-", self.class, m.class]
  when Vector
    m = self.class.column_vector(m)
  when Matrix
  else
    return apply_through_coercion(m, __method__)
  end

  raise ErrDimensionMismatch unless row_count == m.row_count && column_count == m.column_count

  rows = Array.new(row_count) {|i|
    Array.new(column_count) {|j|
      self[i, j] - m[i, j]
    }
  }
  new_matrix rows, column_count
end


  








  

    #-@  
  



  

    

Unary matrix negation.



-Matrix[[1,5], [4,2]]
# => -1 -5
#    -4 -2


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1292



def -@
  collect {|e| -e }
end


  








  

    #/(other)  
  



  

    

Matrix division (multiplication by the inverse).



Matrix[[7,6], [3,9]] / Matrix[[2,9], [3,1]]
#  => -7  1
#     -3 -6


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1147



def /(other)
  case other
  when Numeric
    rows = @rows.collect {|row|
      row.collect {|e| e / other }
    }
    return new_matrix rows, column_count
  when Matrix
    return self * other.inverse
  else
    return apply_through_coercion(other, __method__)
  end
end


  








  

    #==(other)  
  



  

    

Returns whether the two matrices contain equal elements.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1021



def ==(other)
  return false unless Matrix === other &&
                      column_count == other.column_count # necessary for empty matrices
  rows == other.rows
end


  








  

    #[](i, j)  
    Also known as: #element, #component
  



  

    

Returns element (i,j) of the matrix.  That is: row i, column j.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 337



def [](i, j)
  @rows.fetch(i){return nil}[j]
end


  








  

    #[]=(integer, integer, element)      Also known as: #set_element, #set_component
  



  

    

Set element or elements of matrix.


  





  
Raises:


    
  
  • 
    (FrozenError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 351



def []=(i, j, v)
  raise FrozenError, "can't modify frozen Matrix" if frozen?
  rows = check_range(i, :row) or row = check_int(i, :row)
  columns = check_range(j, :column) or column = check_int(j, :column)
  if rows && columns
    set_row_and_col_range(rows, columns, v)
  elsif rows
    set_row_range(rows, column, v)
  elsif columns
    set_col_range(row, columns, v)
  else
    set_value(row, column, v)
  end
end


  








  

    #abs  
  



  

    

Returns the absolute value elementwise


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1299



def abs
  collect(&:abs)
end


  








  

    #adjoint  
  



  

    

Returns the adjoint of the matrix.



Matrix[ [i,1],[2,-i] ].adjoint
#  => -i 2
#      1 i


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1595



def adjoint
  conjugate.transpose
end


  








  

    #adjugate  
  



  

    

Returns the adjugate of the matrix.



Matrix[ [7,6],[3,9] ].adjugate
#  => 9 -6
#     -3 7


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 793



def adjugate
  raise ErrDimensionMismatch unless square?
  Matrix.build(row_count, column_count) do |row, column|
    cofactor(column, row)
  end
end


  








  

    #check_int(val, direction)   (private)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 376



private def check_int(val, direction)
  count = direction == :row ? row_count : column_count
  CoercionHelper.check_int(val, count, direction)
end


  








  

    #check_range(val, direction)   (private)
  



  

    

Returns range or nil


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 370



private def check_range(val, direction)
  return unless val.is_a?(Range)
  count = direction == :row ? row_count : column_count
  CoercionHelper.check_range(val, count, direction)
end


  








  

    #coerce(other)  
  



  

    

The coerce method provides support for Ruby type coercion. This coercion mechanism is used by Ruby to handle mixed-type numeric operations: it is intended to find a compatible common type between the two operands of the operator. See also Numeric#coerce.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1648



def coerce(other)
  case other
  when Numeric
    return Scalar.new(other), self
  else
    raise TypeError, "#{self.class} can't be coerced into #{other.class}"
  end
end


  








  

    #cofactor(row, column)  
  



  

    

Returns the (row, column) cofactor which is obtained by multiplying the first minor by (-1)**(row + column).



Matrix.diagonal(9, 5, -3, 4).cofactor(1, 1)
#  => -108


  





  
Raises:


    
  
  • 
    (RuntimeError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 778



def cofactor(row, column)
  raise RuntimeError, "cofactor of empty matrix is not defined" if empty?
  raise ErrDimensionMismatch unless square?

  det_of_minor = first_minor(row, column).determinant
  det_of_minor * (-1) ** (row + column)
end


  








  

    #cofactor_expansion(row: nil, column: nil)  
  



  

    

Alias for #laplace_expansion.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 828



alias_method :cofactor_expansion, :laplace_expansion


  








  

    #collect(which = :all, &block)  
    Also known as: #map
  



  

    

Returns a matrix that is the result of iteration of the given block over all elements of the matrix. 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] ].collect { |e| e**2 } #  => 1  4 #     9 16
    



  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 508



def collect(which = :all, &block) # :yield: e
  return to_enum(:collect, which) unless block_given?
  dup.collect!(which, &block)
end


  








  

    #collect!(which = :all)  
    Also known as: #map!
  



  

    

Invokes the given block for each element of matrix, replacing the element with the value returned by the block. 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
    



  





  
Raises:


    
  
  • 
    (FrozenError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 526



def collect!(which = :all)
  return to_enum(:collect!, which) unless block_given?
  raise FrozenError, "can't modify frozen Matrix" if frozen?
  each_with_index(which){ |e, row_index, col_index| @rows[row_index][col_index] = yield e }
end


  








  

    #column(j)  
  



  

    

Returns column vector number j of the matrix as a ::Vector (starting at 0 like an array).  When a block is given, the elements of that vector are iterated.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 477



def column(j) # :yield: e
  if block_given?
    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_count || j < -column_count
    col = Array.new(row_count) {|i|
      @rows[i][j]
    }
    Vector.elements(col, false)
  end
end


  








  

    #column_vectors  
  



  

    

Returns an array of the column vectors of the matrix.  See Vector.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1669



def column_vectors
  Array.new(column_count) {|i|
    column(i)
  }
end


  








  

    #combine(*other_matrices) {|*elements| ... }   



  

    

Creates new matrix by combining with other_matrices entrywise, using the given block.



x = Matrix[[6, 6], [4, 4]]
y = Matrix[[1, 2], [3, 4]]
x.combine(y) {|a, b| a - b} # => Matrix[[5, 4], [1, 0]]


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 315



def combine(*matrices, &block)
  Matrix.combine(self, *matrices, &block)
end


  








  

    #component(i, j)  
  



  

    

Alias for #[].


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 341



alias component []


  








  

    #conj  
  



  

    

Alias for #conjugate.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1586



alias_method :conj, :conjugate


  








  

    #conjugate  
    Also known as: #conj
  



  

    

Returns the conjugate of the matrix.



Matrix[[Complex(1,2), Complex(0,1), 0], [1, 2, 3]]
#  => 1+2i   i  0
#        1   2  3
Matrix[[Complex(1,2), Complex(0,1), 0], [1, 2, 3]].conjugate
#  => 1-2i  -i  0
#        1   2  3


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1583



def conjugate
  collect(&:conjugate)
end


  








  

    #det  
  



  

    

Alias for #determinant.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1355



alias_method :det, :determinant


  








  

    #det_e  
  



  

    

Alias for #determinant_e.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1402



alias_method :det_e, :determinant_e


  








  

    #determinant  
    Also known as: #det
  



  

    

Returns the determinant of the matrix.



Beware that using Float values can yield erroneous results because of their lack of precision. Consider using exact types like Rational or BigDecimal instead.



Matrix[[7,6], [3,9]].determinant
#  => 45


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1317



def determinant
  raise ErrDimensionMismatch unless square?
  m = @rows
  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
  when 0
    +1
  when 1
    + m[0][0]
  when 2
    + m[0][0] * m[1][1] - m[0][1] * m[1][0]
  when 3
    m0, m1, m2 = m
    + m0[0] * m1[1] * m2[2] - m0[0] * m1[2] * m2[1] \
    - m0[1] * m1[0] * m2[2] + m0[1] * m1[2] * m2[0] \
    + m0[2] * m1[0] * m2[1] - m0[2] * m1[1] * m2[0]
  when 4
    m0, m1, m2, m3 = m
    + m0[0] * m1[1] * m2[2] * m3[3] - m0[0] * m1[1] * m2[3] * m3[2] \
    - m0[0] * m1[2] * m2[1] * m3[3] + m0[0] * m1[2] * m2[3] * m3[1] \
    + m0[0] * m1[3] * m2[1] * m3[2] - m0[0] * m1[3] * m2[2] * m3[1] \
    - m0[1] * m1[0] * m2[2] * m3[3] + m0[1] * m1[0] * m2[3] * m3[2] \
    + m0[1] * m1[2] * m2[0] * m3[3] - m0[1] * m1[2] * m2[3] * m3[0] \
    - m0[1] * m1[3] * m2[0] * m3[2] + m0[1] * m1[3] * m2[2] * m3[0] \
    + m0[2] * m1[0] * m2[1] * m3[3] - m0[2] * m1[0] * m2[3] * m3[1] \
    - m0[2] * m1[1] * m2[0] * m3[3] + m0[2] * m1[1] * m2[3] * m3[0] \
    + m0[2] * m1[3] * m2[0] * m3[1] - m0[2] * m1[3] * m2[1] * m3[0] \
    - m0[3] * m1[0] * m2[1] * m3[2] + m0[3] * m1[0] * m2[2] * m3[1] \
    + m0[3] * m1[1] * m2[0] * m3[2] - m0[3] * m1[1] * m2[2] * m3[0] \
    - m0[3] * m1[2] * m2[0] * m3[1] + m0[3] * m1[2] * m2[1] * m3[0]
  else
    # For bigger matrices, use an efficient and general algorithm.
    # Currently, we use the Gauss-Bareiss algorithm
    determinant_bareiss
  end
end


  








  

    #determinant_bareiss   (private)
  



  

    

Private. Use #determinant



Returns the determinant of the matrix, using Bareiss’ multistep integer-preserving gaussian elimination. It has the same computational cost order O(n^3) as standard Gaussian elimination. Intermediate results are fraction free and of lower complexity. A matrix of Integers will have thus intermediate results that are also Integers, with smaller bignums (if any), while a matrix of Float will usually have intermediate results with better precision.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1368



private def determinant_bareiss
  size = row_count
  last = size - 1
  a = to_a
  no_pivot = Proc.new{ return 0 }
  sign = +1
  pivot = 1
  size.times do |k|
    previous_pivot = pivot
    if (pivot = a[k][k]) == 0
      switch = (k+1 ... size).find(no_pivot) {|row|
        a[row][k] != 0
      }
      a[switch], a[k] = a[k], a[switch]
      pivot = a[k][k]
      sign = -sign
    end
    (k+1).upto(last) do |i|
      ai = a[i]
      (k+1).upto(last) do |j|
        ai[j] =  (pivot * ai[j] - ai[k] * a[k][j]) / previous_pivot
      end
    end
  end
  sign * pivot
end


  








  

    #determinant_e  
    Also known as: #det_e
  



  

    

deprecated; use #determinant


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1398



def determinant_e
  warn "Matrix#determinant_e is deprecated; use #determinant", uplevel: 1
  determinant
end


  








  

    #each(which = :all, &block)  
  



  

    

Yields all elements of the matrix, starting with those of the first row, or returns an Enumerator if 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
Matrix[ [1,2], [3,4] ].each(:strict_lower).to_a # => [3]
    



  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 556



def each(which = :all, &block) # :yield: e
  return to_enum :each, which unless block_given?
  last = column_count - 1
  case which
  when :all
    @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


  








  

    #each_with_index(which = :all)  
  



  

    

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
  # => Prints:
  #    1 at 0, 0
  #    2 at 0, 1
  #    3 at 1, 0
  #    4 at 1, 1


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 616



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


  








  

    #eigen  
  



  

    

Alias for #eigensystem.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1553



alias_method :eigen, :eigensystem


  








  

    #eigensystem  
    Also known as: #eigen
  



  

    

Returns the Eigensystem of the matrix; see ::Matrix::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


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1550



def eigensystem
  EigenvalueDecomposition.new(self)
end


  








  

    #element(i, j)  
  



  

    

Alias for #[].


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 340



alias element []


  








  

    #elements_to_f  
  



  

    

Deprecated.



Use map(&:to_f)


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1692



def elements_to_f
  warn "Matrix#elements_to_f is deprecated, use map(&:to_f)", uplevel: 1
  map(&:to_f)
end


  








  

    #elements_to_i  
  



  

    

Deprecated.



Use map(&:to_i)


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1700



def elements_to_i
  warn "Matrix#elements_to_i is deprecated, use map(&:to_i)", uplevel: 1
  map(&:to_i)
end


  








  

    #elements_to_r  
  



  

    

Deprecated.



Use map(&:to_r)


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1708



def elements_to_r
  warn "Matrix#elements_to_r is deprecated, use map(&:to_r)", uplevel: 1
  map(&:to_r)
end


  








  

    #entrywise_product(m)  
  



  

    

Alias for #hadamard_product.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1170



alias_method :entrywise_product, :hadamard_product


  








  

    #eql?(other)  ⇒ Boolean 
  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1027



def eql?(other)
  return false unless Matrix === other &&
                      column_count == other.column_count # necessary for empty matrices
  rows.eql? other.rows
end


  








  

    #find_index(*args)  
  



  

    

Alias for #index.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 695



alias_method :find_index, :index


  








  

    #first_minor(row, column)  
  



  

    

Returns the submatrix obtained by deleting the specified row and column.



Matrix.diagonal(9, 5, -3, 4).first_minor(1, 2)
#  => 9 0 0
#     0 0 0
#     0 0 4


  





  
Raises:


    
  
  • 
    (RuntimeError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 751



def first_minor(row, column)
  raise RuntimeError, "first_minor of empty matrix is not defined" if empty?

  unless 0 <= row && row < row_count
    raise ArgumentError, "invalid row (#{row.inspect} for 0..#{row_count - 1})"
  end

  unless 0 <= column && column < column_count
    raise ArgumentError, "invalid column (#{column.inspect} for 0..#{column_count - 1})"
  end

  arrays = to_a
  arrays.delete_at(row)
  arrays.each do |array|
    array.delete_at(column)
  end

  new_matrix arrays, column_count - 1
end


  








  

    #freeze  
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 534



def freeze
  @rows.each(&:freeze).freeze

  super
end


  








  

    #hadamard_product(m)  
    Also known as: #entrywise_product
  



  

    

Hadamard product



Matrix[[1,2], [3,4]].hadamard_product(Matrix[[1,2], [3,2]])
#  => 1  4
#     9  8


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1167



def hadamard_product(m)
  combine(m){|a, b| a * b}
end


  








  

    #hash  
  



  

    

Returns a hash-code for the matrix.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1044



def hash
  @rows.hash
end


  








  

    #hstack(*matrices)  
  



  

    

Returns a new matrix resulting by stacking horizontally the receiver with the given matrices



x = Matrix[[1, 2], [3, 4]]
y = Matrix[[5, 6], [7, 8]]
x.hstack(y) # => Matrix[[1, 2, 5, 6], [3, 4, 7, 8]]


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1412



def hstack(*matrices)
  self.class.hstack(self, *matrices)
end


  








  

    #imag  
  



  

    

Alias for #imaginary.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1611



alias_method :imag, :imaginary


  








  

    #imaginary  
    Also known as: #imag
  



  

    

Returns the imaginary part of the matrix.



Matrix[[Complex(1,2), Complex(0,1), 0], [1, 2, 3]]
#  => 1+2i  i  0
#        1  2  3
Matrix[[Complex(1,2), Complex(0,1), 0], [1, 2, 3]].imaginary
#  =>   2i  i  0
#        0  0  0


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1608



def imaginary
  collect(&:imaginary)
end


  








  

    

      #index(value, selector = :all)  ⇒ Array, column 
      #index(selector = :all)  ⇒ Array, column 
      #index(selector = :all)  ⇒ Enumerator 
    

    Also known as: #find_index
  



  

    

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]


  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 679



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


  








  

    #initialize_copy(m)   (private)
  



  

    

Called for dup & clone.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1036



private def initialize_copy(m)
  super
  @rows = @rows.map(&:dup) unless frozen?
end


  








  

    #inspect  
  



  

    

Overrides Object#inspect


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1733



def inspect
  if empty?
    "#{self.class}.empty(#{row_count}, #{column_count})"
  else
    "#{self.class}#{@rows.inspect}"
  end
end


  








  

    #inv  
  



  

    

Alias for #inverse.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1182



alias_method :inv, :inverse


  








  

    #inverse  
    Also known as: #inv
  



  

    

Returns the inverse of the matrix.



Matrix[[-1, -1], [0, -1]].inverse
#  => -1  1
#      0 -1


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1178



def inverse
  raise ErrDimensionMismatch unless square?
  self.class.I(row_count).send(:inverse_from, self)
end


  








  

    #inverse_from(src)   (private)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1184



private def inverse_from(src) # :nodoc:
  last = row_count - 1
  a = src.to_a

  0.upto(last) do |k|
    i = k
    akk = a[k][k].abs
    (k+1).upto(last) do |j|
      v = a[j][k].abs
      if v > akk
        i = j
        akk = v
      end
    end
    raise ErrNotRegular if akk == 0
    if i != k
      a[i], a[k] = a[k], a[i]
      @rows[i], @rows[k] = @rows[k], @rows[i]
    end
    akk = a[k][k]

    0.upto(last) do |ii|
      next if ii == k
      q = a[ii][k].quo(akk)
      a[ii][k] = 0

      (k + 1).upto(last) do |j|
        a[ii][j] -= a[k][j] * q
      end
      0.upto(last) do |j|
        @rows[ii][j] -= @rows[k][j] * q
      end
    end

    (k+1).upto(last) do |j|
      a[k][j] = a[k][j].quo(akk)
    end
    0.upto(last) do |j|
      @rows[k][j] = @rows[k][j].quo(akk)
    end
  end
  self
end


  








  

    #laplace_expansion(row: nil, column: nil)  
    Also known as: #cofactor_expansion
  



  

    

Returns the Laplace expansion along given row or column.



Matrix[[7,6], [3,9]].laplace_expansion(column: 1)
# => 45

Matrix[[Vector[1, 0], Vector[0, 1]], [2, 3]].laplace_expansion(row: 0)
# => Vector[3, -2]


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 810



def laplace_expansion(row: nil, column: nil)
  num = row || column

  if !num || (row && column)
    raise ArgumentError, "exactly one the row or column arguments must be specified"
  end

  raise ErrDimensionMismatch unless square?
  raise RuntimeError, "laplace_expansion of empty matrix is not defined" if empty?

  unless 0 <= num && num < row_count
    raise ArgumentError, "invalid num (#{num.inspect} for 0..#{row_count - 1})"
  end

  send(row ? :row : :column, num).map.with_index { |e, k|
    e * cofactor(*(row ? [num, k] : [k,num]))
  }.inject(:+)
end


  








  

    #lup  
    Also known as: #lup_decomposition
  



  

    

Returns the LUP decomposition of the matrix; see ::Matrix::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)]


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1565



def lup
  LUPDecomposition.new(self)
end


  








  

    #lup_decomposition  
  



  

    

Alias for #lup.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1568



alias_method :lup_decomposition, :lup


  








  

    #map(which = :all, &block)  
  



  

    

Alias for #collect.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 512



alias_method :map, :collect


  








  

    #map!(which = :all)  
  



  

    

Alias for #collect!.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 532



alias map! collect!


  








  

    #minor(*param)  
  



  

    

Returns a section of the matrix.  The parameters are either:


  • 

    start_row, nrows, start_col, ncols; OR
    

  • 

    row_range, col_range
    




Matrix.diagonal(9, 5, -3).minor(0..1, 0..2)
#  => 9 0 0
#     0 5 0



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_count or column_count respectively.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 710



def minor(*param)
  case param.size
  when 2
    row_range, col_range = param
    from_row = row_range.first
    from_row += row_count if from_row < 0
    to_row = row_range.end
    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_count if from_col < 0
    to_col = col_range.end
    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_count if from_row < 0
    from_col += column_count if from_col < 0
  else
    raise ArgumentError, param.inspect
  end

  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_count - from_col, size_col].min
end


  








  

    #new_matrix(rows, column_count = rows[0].size)   (private)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 330



private def new_matrix(rows, column_count = rows[0].size) # :nodoc:
  self.class.send(:new, rows, column_count) # bypass privacy of Matrix.new
end


  








  

    #power_int(exp)   (protected)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1257



protected def power_int(exp)
  # assumes `exp` is an Integer > 0
  #
  # Previous algorithm:
  #   build M**2, M**4 = (M**2)**2, M**8, ... and multiplying those you need
  #   e.g. M**0b1011 = M**11 = M * M**2 * M**8
  #                              ^  ^
  #   (highlighted the 2 out of 5 multiplications involving `M * x`)
  #
  # Current algorithm has same number of multiplications but with lower exponents:
  #    M**11 = M * (M * M**4)**2
  #              ^    ^  ^
  #   (highlighted the 3 out of 5 multiplications involving `M * x`)
  #
  # This should be faster for all (non nil-potent) matrices.
  case
  when exp == 1
    self
  when exp.odd?
    self * power_int(exp - 1)
  else
    sqrt = power_int(exp / 2)
    sqrt * sqrt
  end
end


  








  

    #rank  
  



  

    

Returns the rank of the matrix. Beware that using Float values can yield erroneous results because of their lack of precision. Consider using exact types like Rational or BigDecimal instead.



Matrix[[7,6], [3,9]].rank
#  => 2


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1425



def rank
  # We currently use Bareiss' multistep integer-preserving gaussian elimination
  # (see comments on determinant)
  a = to_a
  last_column = column_count - 1
  last_row = row_count - 1
  pivot_row = 0
  previous_pivot = 1
  0.upto(last_column) do |k|
    switch_row = (pivot_row .. last_row).find {|row|
      a[row][k] != 0
    }
    if switch_row
      a[switch_row], a[pivot_row] = a[pivot_row], a[switch_row] unless pivot_row == switch_row
      pivot = a[pivot_row][k]
      (pivot_row+1).upto(last_row) do |i|
         ai = a[i]
         (k+1).upto(last_column) do |j|
           ai[j] =  (pivot * ai[j] - ai[k] * a[pivot_row][j]) / previous_pivot
         end
       end
      pivot_row += 1
      previous_pivot = pivot
    end
  end
  pivot_row
end


  








  

    #rank_e  
  



  

    

deprecated; use #rank


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1456



def rank_e
  warn "Matrix#rank_e is deprecated; use #rank", uplevel: 1
  rank
end


  








  

    #real   (readonly)
  



  

    

Returns the real part of the matrix.



Matrix[[Complex(1,2), Complex(0,1), 0], [1, 2, 3]]
#  => 1+2i  i  0
#        1  2  3
Matrix[[Complex(1,2), Complex(0,1), 0], [1, 2, 3]].real
#  =>    1  0  0
#        1  2  3


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1622



def real
  collect(&:real)
end


  








  

    #rect  
    Also known as: #rectangular
  



  

    

Returns an array containing matrices corresponding to the real and imaginary parts of the matrix



m.rect == [m.real, m.imag]  # ==> true for all matrices m


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1632



def rect
  [real, imag]
end


  








  

    #rectangular  
  



  

    

Alias for #rect.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1635



alias_method :rectangular, :rect


  








  

    #rotate_entries(rotation = :clockwise)  
  



  

    

Returns a new matrix with rotated elements. The argument specifies the rotation (defaults to ‘:clockwise`):


  • 

    :clockwise, 1, -3, etc.: “turn right” - first row becomes last column
    

  • 

    :half_turn, 2, -2, etc.: first row becomes last row, elements in reverse order
    

  • 

    :counter_clockwise, -1, 3: “turn left” - first row becomes first column (but with elements in reverse order)
    


    m = Matrix[ [1, 2], [3, 4] ] r = m.rotate_entries(:clockwise) #  => Matrix[[3, 1], [4, 2]]
    



  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1473



def rotate_entries(rotation = :clockwise)
  rotation %= 4 if rotation.respond_to? :to_int

  case rotation
  when 0
    dup
  when 1, :clockwise
    new_matrix @rows.transpose.each(&:reverse!), row_count
  when 2, :half_turn
    new_matrix @rows.map(&:reverse).reverse!, column_count
  when 3, :counter_clockwise
    new_matrix @rows.transpose.reverse!, row_count
  else
    raise ArgumentError, "expected #{rotation.inspect} to be one of :clockwise, :counter_clockwise, :half_turn or an integer"
  end
end


  








  

    #round(ndigits = 0)  
  



  

    

Returns a matrix with entries rounded to the given precision (see Float#round)


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1493



def round(ndigits=0)
  map{|e| e.round(ndigits)}
end


  








  

    #row(i, &block)  
  



  

    

Returns row vector number i of the matrix as a ::Vector (starting at 0 like an array).  When a block is given, the elements of that vector are iterated.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 463



def row(i, &block) # :yield: e
  if block_given?
    @rows.fetch(i){return self}.each(&block)
    self
  else
    Vector.elements(@rows.fetch(i){return nil})
  end
end


  








  

    #row_count  
    Also known as: #row_size
  



  

    

Returns the number of rows.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 448



def row_count
  @rows.size
end


  








  

    #row_size  
  



  

    

Alias for #row_count.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 452



alias_method :row_size, :row_count


  








  

    #row_vectors  
  



  

    

Returns an array of the row vectors of the matrix.  See Vector.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1660



def row_vectors
  Array.new(row_count) {|i|
    row(i)
  }
end


  








  

    #set_col_range(row, col_range, value)   (private)
  



  

    
  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 432



private def set_col_range(row, col_range, value)
  value = if value.is_a?(Vector)
    value.to_a
  elsif value.is_a?(Matrix)
    raise ErrDimensionMismatch unless value.row_count == 1
    value.row(0).to_a
  else
    Array.new(col_range.size, value)
  end
  raise ErrDimensionMismatch unless col_range.size == value.size
  @rows[row][col_range] = value
end


  








  

    #set_column_vector(row_range, col, value)   (private)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 425



private def set_column_vector(row_range, col, value)
  value.each_with_index do |e, index|
    r = row_range.begin + index
    @rows[r][col] = e
  end
end


  








  

    #set_component(i, j, v)   (private)
  



  

    

Alias for #[]=.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 366



alias set_component []=


  








  

    #set_element(i, j, v)   (private)
  



  

    

Alias for #[]=.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 365



alias set_element []=


  








  

    #set_row_and_col_range(row_range, col_range, value)   (private)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 387



private def set_row_and_col_range(row_range, col_range, value)
  if value.is_a?(Matrix)
    if row_range.size != value.row_count || col_range.size != value.column_count
      raise ErrDimensionMismatch, [
        'Expected a Matrix of dimensions',
        "#{row_range.size}x#{col_range.size}",
        'got',
        "#{value.row_count}x#{value.column_count}",
      ].join(' ')
    end
    source = value.instance_variable_get :@rows
    row_range.each_with_index do |row, i|
      @rows[row][col_range] = source[i]
    end
  elsif value.is_a?(Vector)
    raise ErrDimensionMismatch, 'Expected a Matrix or a value, got a Vector'
  else
    value_to_set = Array.new(col_range.size, value)
    row_range.each do |i|
      @rows[i][col_range] = value_to_set
    end
  end
end


  








  

    #set_row_range(row_range, col, value)   (private)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 411



private def set_row_range(row_range, col, value)
  if value.is_a?(Vector)
    raise ErrDimensionMismatch unless row_range.size == value.size
    set_column_vector(row_range, col, value)
  elsif value.is_a?(Matrix)
    raise ErrDimensionMismatch unless value.column_count == 1
    value = value.column(0)
    raise ErrDimensionMismatch unless row_range.size == value.size
    set_column_vector(row_range, col, value)
  else
    @rows[row_range].each{|e| e[col] = value }
  end
end


  








  

    #set_value(row, col, value)   (private)
  



  

    
  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 381



private def set_value(row, col, value)
  raise ErrDimensionMismatch, "Expected a value, got a #{value.class}" if value.respond_to?(:to_matrix)

  @rows[row][col] = value
end


  








  

    #t  
  



  

    

Alias for #transpose.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1524



alias_method :t, :transpose


  








  

    #to_a  
  



  

    

Returns an array of arrays that describe the rows of the matrix.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1685



def to_a
  @rows.collect(&:dup)
end


  








  

    #to_matrix  
  



  

    

Explicit conversion to a Matrix. Returns self


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1678



def to_matrix
  self
end


  








  

    #to_s  
  



  

    

Overrides Object#to_s


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1720



def to_s
  if empty?
    "#{self.class}.empty(#{row_count}, #{column_count})"
  else
    "#{self.class}[" + @rows.collect{|row|
      "[" + row.collect{|e| e.to_s}.join(", ") + "]"
    }.join(", ")+"]"
  end
end


  








  

    #tr  
  



  

    

Alias for #trace.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1508



alias_method :tr, :trace


  








  

    #trace  
    Also known as: #tr
  



  

    

Returns the trace (sum of diagonal elements) of the matrix.



Matrix[[7,6], [3,9]].trace
#  => 16


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1502



def trace
  raise ErrDimensionMismatch unless square?
  (0...column_count).inject(0) do |tr, i|
    tr + @rows[i][i]
  end
end


  








  

    #transpose  
    Also known as: #t
  



  

    

Returns the transpose of the matrix.



Matrix[[1,2], [3,4], [5,6]]
#  => 1 2
#     3 4
#     5 6
Matrix[[1,2], [3,4], [5,6]].transpose
#  => 1 3 5
#     2 4 6


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1520



def transpose
  return self.class.empty(column_count, 0) if row_count.zero?
  new_matrix @rows.transpose, row_count
end


  








  

    #vstack(*matrices)  
  



  

    

Returns a new matrix resulting by stacking vertically the receiver with the given matrices



x = Matrix[[1, 2], [3, 4]]
y = Matrix[[5, 6], [7, 8]]
x.vstack(y) # => Matrix[[1, 2], [3, 4], [5, 6], [7, 8]]


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1534



def vstack(*matrices)
  self.class.vstack(self, *matrices)
end