Class: Matrix

Inherits:
Object
  • Object
show all
Extended by:
ConversionHelper
Includes:
Enumerable, ExceptionForMatrix, CoercionHelper
Defined in:
lib/matrix.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 (trace, rank, inverse, determinant).

Method Catalogue

To create a matrix:

  • Matrix[*rows]

  • Matrix.[](*rows)

  • Matrix.rows(rows, copy = true)

  • Matrix.columns(columns)

  • Matrix.build(row_size, column_size, &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:

  • [](i, j)

  • #row_size

  • #column_size

  • #row(i)

  • #column(j)

  • #collect

  • #map

  • #each

  • #each_with_index

  • #find_index

  • #minor(*param)

Properties of a matrix:

  • #diagonal?

  • #empty?

  • #hermitian?

  • #lower_triangular?

  • #normal?

  • #orthogonal?

  • #permutation?

  • #real?

  • #regular?

  • #singular?

  • #square?

  • #symmetric?

  • #unitary?

  • #upper_triangular?

  • #zero?

Matrix arithmetic:

  • *(m)

  • +(m)

  • -(m)

  • #/(m)

  • #inverse

  • #inv

  • **

Matrix functions:

  • #determinant

  • #det

  • #rank

  • #round

  • #trace

  • #tr

  • #transpose

  • #t

Matrix decompositions:

  • #eigen

  • #eigensystem

  • #lup

  • #lup_decomposition

Complex arithmetic:

  • conj

  • conjugate

  • imag

  • imaginary

  • real

  • rect

  • rectangular

Conversion to other data types:

  • #coerce(other)

  • #row_vectors

  • #column_vectors

  • #to_a

String representations:

  • #to_s

  • #inspect

Defined Under Namespace

Modules: CoercionHelper, ConversionHelper Classes: Scalar

Constant Summary collapse

SELECTORS = 
{all: true, diagonal: true, off_diagonal: true, lower: true, strict_lower: true, strict_upper: true, upper: true}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CoercionHelper

coerce_to, coerce_to_int

Constructor Details

#initialize(rows, column_size = rows[0].size) ⇒ Matrix

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



298
299
300
301
302
303
304
 
# File 'lib/matrix.rb', line 298

def initialize(rows, column_size = 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,
  # otherwise it *must* be specified and can be any integer >= 0
  @rows = rows
  @column_size = column_size
end

Instance Attribute Details

#column_size ⇒ Object (readonly)

Returns the number of columns.



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

def column_size
  @column_size
end

Class Method Details

.[](*rows) ⇒ Object

Creates a matrix where each argument is a row.

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



140
141
142
 
# File 'lib/matrix.rb', line 140

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

.build(row_size, column_size = row_size) ⇒ Object

Creates a matrix of size row_size x column_size. 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) 


185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/matrix.rb', line 185

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 = Array.new(row_size) do |i|
    Array.new(column_size) do |j|
      yield i, j
    end
  end
  new rows, column_size
end

.column_vector(column) ⇒ Object

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



270
271
272
273
 
# File 'lib/matrix.rb', line 270

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

.columns(columns) ⇒ Object

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

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



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

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

.diagonal(*values) ⇒ Object

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



205
206
207
208
209
210
211
212
213
 
# File 'lib/matrix.rb', line 205

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

.empty(row_size = 0, column_size = 0) ⇒ Object

Creates a empty matrix of row_size x column_size. At least one of row_size or column_size 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]]



288
289
290
291
292
293
 
# File 'lib/matrix.rb', line 288

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

  new([[]]*row_size, column_size)
end

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

Creates an n by n identity matrix.

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



232
233
234
 
# File 'lib/matrix.rb', line 232

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

.row_vector(row) ⇒ Object

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



257
258
259
260
 
# File 'lib/matrix.rb', line 257

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

.rows(rows, copy = true) ⇒ Object

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



152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/matrix.rb', line 152

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

.scalar(n, value) ⇒ Object

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

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



222
223
224
 
# File 'lib/matrix.rb', line 222

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

.zero(row_size, column_size = row_size) ⇒ Object

Creates a zero matrix.

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



246
247
248
249
 
# File 'lib/matrix.rb', line 246

def Matrix.zero(row_size, column_size = row_size)
  rows = Array.new(row_size){Array.new(column_size, 0)}
  new rows, column_size
end

Instance Method Details

#*(m) ⇒ Object

Matrix multiplication.

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



803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
 
# File 'lib/matrix.rb', line 803

def *(m) # m is matrix or vector or number
  case(m)
  when Numeric
    rows = @rows.collect {|row|
      row.collect {|e| e * m }
    }
    return new_matrix rows, column_size
  when Vector
    m = Matrix.column_vector(m)
    r = self * m
    return r.column(0)
  when Matrix
    Matrix.Raise ErrDimensionMismatch if column_size != m.row_size

    rows = Array.new(row_size) {|i|
      Array.new(m.column_size) {|j|
        (0 ... column_size).inject(0) do |vij, k|
          vij + self[i, k] * m[k, j]
        end
      }
    }
    return new_matrix rows, m.column_size
  else
    return apply_through_coercion(m, __method__)
  end
end

#**(other) ⇒ Object

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



970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
 
# File 'lib/matrix.rb', line 970

def ** (other)
  case other
  when Integer
    x = self
    if other <= 0
      x = self.inverse
      return Matrix.identity(self.column_size) if other == 0
      other = -other
    end
    z = nil
    loop do
      z = z ? z * x : x if other[0] == 1
      return z if (other >>= 1).zero?
      x *= x
    end
  when Numeric
    v, d, v_inv = eigensystem
    v * Matrix.diagonal(*d.each(:diagonal).map{|e| e ** other}) * v_inv
  else
    Matrix.Raise ErrOperationNotDefined, "**", self.class, other.class
  end
end

#+(m) ⇒ Object

Matrix addition.

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



836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
 
# File 'lib/matrix.rb', line 836

def +(m)
  case m
  when Numeric
    Matrix.Raise ErrOperationNotDefined, "+", self.class, m.class
  when Vector
    m = Matrix.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

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

#-(m) ⇒ Object

Matrix subtraction.

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



863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
 
# File 'lib/matrix.rb', line 863

def -(m)
  case m
  when Numeric
    Matrix.Raise ErrOperationNotDefined, "-", self.class, m.class
  when Vector
    m = Matrix.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

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

#/(other) ⇒ Object

Matrix division (multiplication by the inverse).

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



890
891
892
893
894
895
896
897
898
899
900
901
902
 
# File 'lib/matrix.rb', line 890

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

#==(other) ⇒ Object

Returns true if and only if the two matrices contain equal elements.



765
766
767
768
769
 
# File 'lib/matrix.rb', line 765

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

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

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



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

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

#clone ⇒ Object

Returns a clone of the matrix, so that the contents of each do not reference identical objects. There should be no good reason to do this since Matrices are immutable.



782
783
784
 
# File 'lib/matrix.rb', line 782

def clone
  new_matrix @rows.map(&:dup), column_size
end

#coerce(other) ⇒ Object

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.



1275
1276
1277
1278
1279
1280
1281
1282
 
# File 'lib/matrix.rb', line 1275

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

#collect(&block) ⇒ Object Also known as: map

Returns a matrix that is the result of iteration of the given block over all elements of the matrix.

Matrix[ [1,2], [3,4] ].collect { |e| e**2 }
  => 1  4
     9 16



380
381
382
383
384
 
# File 'lib/matrix.rb', line 380

def collect(&block) # :yield: e
  return to_enum(:collect) unless block_given?
  rows = @rows.collect{|row| row.collect(&block)}
  new_matrix rows, column_size
end

#column(j) ⇒ Object

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.



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'lib/matrix.rb', line 357

def column(j) # :yield: e
  if block_given?
    return self if j >= column_size || j < -column_size
    row_size.times do |i|
      yield @rows[i][j]
    end
    self
  else
    return nil if j >= column_size || j < -column_size
    col = Array.new(row_size) {|i|
      @rows[i][j]
    }
    Vector.elements(col, false)
  end
end

#column_vectors ⇒ Object

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



1296
1297
1298
1299
1300
 
# File 'lib/matrix.rb', line 1296

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

#conjugate ⇒ Object 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



1221
1222
1223
 
# File 'lib/matrix.rb', line 1221

def conjugate
  collect(&:conjugate)
end

#determinant ⇒ Object 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



1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
 
# File 'lib/matrix.rb', line 1007

def determinant
  Matrix.Raise ErrDimensionMismatch unless square?
  m = @rows
  case row_size
    # 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_e ⇒ Object Also known as: det_e

deprecated; use Matrix#determinant



1089
1090
1091
1092
 
# File 'lib/matrix.rb', line 1089

def determinant_e
  warn "#{caller(1)[0]}: warning: Matrix#determinant_e is deprecated; use #determinant"
  rank
end

#diagonal? ⇒ Boolean

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

Returns:

  • (Boolean) 


598
599
600
601
 
# File 'lib/matrix.rb', line 598

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

#each(which = :all) ⇒ Object

Yields all elements of the matrix, starting with those of the first row, 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

    Matrix[ [1,2], [3,4] ].each(:strict_lower).to_a # => [3]



403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/matrix.rb', line 403

def each(which = :all) # :yield: e
  return to_enum :each, which unless block_given?
  last = column_size - 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_size.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_size].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
    Matrix.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) ⇒ Object

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



464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
 
# File 'lib/matrix.rb', line 464

def each_with_index(which = :all) # :yield: e, row, column
  return to_enum :each_with_index, which unless block_given?
  last = column_size - 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_size.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_size].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
    Matrix.Raise ArgumentError, "expected #{which.inspect} to be one of :all, :diagonal, :off_diagonal, :lower, :strict_lower, :strict_upper or :upper"
  end
  self
end

#eigensystem ⇒ Object Also known as: eigen

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



1188
1189
1190
 
# File 'lib/matrix.rb', line 1188

def eigensystem
  EigenvalueDecomposition.new(self)
end

#elements_to_f ⇒ Object 



1309
1310
1311
1312
 
# File 'lib/matrix.rb', line 1309

def elements_to_f
  warn "#{caller(1)[0]}: warning: Matrix#elements_to_f is deprecated, use map(&:to_f)"
  map(&:to_f)
end

#elements_to_i ⇒ Object 



1314
1315
1316
1317
 
# File 'lib/matrix.rb', line 1314

def elements_to_i
  warn "#{caller(1)[0]}: warning: Matrix#elements_to_i is deprecated, use map(&:to_i)"
  map(&:to_i)
end

#elements_to_r ⇒ Object 



1319
1320
1321
1322
 
# File 'lib/matrix.rb', line 1319

def elements_to_r
  warn "#{caller(1)[0]}: warning: Matrix#elements_to_r is deprecated, use map(&:to_r)"
  map(&:to_r)
end

#empty? ⇒ Boolean

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

Returns:

  • (Boolean) 


607
608
609
 
# File 'lib/matrix.rb', line 607

def empty?
  column_size == 0 || row_size == 0
end

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


771
772
773
774
775
 
# File 'lib/matrix.rb', line 771

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

#hash ⇒ Object

Returns a hash-code for the matrix.



789
790
791
 
# File 'lib/matrix.rb', line 789

def hash
  @rows.hash
end

#hermitian? ⇒ Boolean

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

Returns:

  • (Boolean) 


615
616
617
618
619
620
 
# File 'lib/matrix.rb', line 615

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

#imaginary ⇒ Object 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



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

def imaginary
  collect(&:imaginary)
end

#index(*args) ⇒ Object Also known as: find_index

: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]

Raises:

  • (ArgumentError) 


527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
 
# File 'lib/matrix.rb', line 527

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

#inspect ⇒ Object

Overrides Object#inspect



1344
1345
1346
1347
1348
1349
1350
 
# File 'lib/matrix.rb', line 1344

def inspect
  if empty?
    "Matrix.empty(#{row_size}, #{column_size})"
  else
    "Matrix#{@rows.inspect}"
  end
end

#inverse ⇒ Object Also known as: inv

Returns the inverse of the matrix.

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



910
911
912
913
 
# File 'lib/matrix.rb', line 910

def inverse
  Matrix.Raise ErrDimensionMismatch unless square?
  Matrix.I(row_size).send(:inverse_from, self)
end

#lower_triangular? ⇒ Boolean

Returns true is this is a lower triangular matrix.

Returns:

  • (Boolean) 


625
626
627
 
# File 'lib/matrix.rb', line 625

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

#lup ⇒ Object Also known as: lup_decomposition

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 == a * p      # => true
a.lup.solve([2, 5]) # => Vector[(1/1), (1/2)]



1203
1204
1205
 
# File 'lib/matrix.rb', line 1203

def lup
  LUPDecomposition.new(self)
end

#minor(*param) ⇒ Object

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_size or column_size respectively.



557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
 
# File 'lib/matrix.rb', line 557

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
    to_row = row_range.end
    to_row += row_size 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
    to_col = col_range.end
    to_col += column_size 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
  else
    Matrix.Raise ArgumentError, param.inspect
  end

  return nil if from_row > row_size || from_col > column_size || 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, size_col].min
end

#normal? ⇒ Boolean

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

Returns:

  • (Boolean) 


633
634
635
636
637
638
639
640
641
642
643
644
645
 
# File 'lib/matrix.rb', line 633

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

#orthogonal? ⇒ Boolean

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

Returns:

  • (Boolean) 


651
652
653
654
655
656
657
658
659
660
661
662
663
 
# File 'lib/matrix.rb', line 651

def orthogonal?
  Matrix.Raise ErrDimensionMismatch unless square?
  rows.each_with_index do |row, i|
    column_size.times do |j|
      s = 0
      row_size.times do |k|
        s += row[k] * rows[k][j]
      end
      return false unless s == (i == j ? 1 : 0)
    end
  end
  true
end

#permutation? ⇒ Boolean

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

Returns:

  • (Boolean) 


669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
 
# File 'lib/matrix.rb', line 669

def permutation?
  Matrix.Raise ErrDimensionMismatch unless square?
  cols = Array.new(column_size)
  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

#rank ⇒ Object

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



1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
 
# File 'lib/matrix.rb', line 1104

def rank
  # 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
  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 ⇒ Object

deprecated; use Matrix#rank



1135
1136
1137
1138
 
# File 'lib/matrix.rb', line 1135

def rank_e
  warn "#{caller(1)[0]}: warning: Matrix#rank_e is deprecated; use #rank"
  rank
end

#real ⇒ Object

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



1249
1250
1251
 
# File 'lib/matrix.rb', line 1249

def real
  collect(&:real)
end

#real? ⇒ Boolean

Returns true if all entries of the matrix are real.

Returns:

  • (Boolean) 


690
691
692
 
# File 'lib/matrix.rb', line 690

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

#rect ⇒ Object 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



1259
1260
1261
 
# File 'lib/matrix.rb', line 1259

def rect
  [real, imag]
end

#regular? ⇒ Boolean

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

Returns:

  • (Boolean) 


697
698
699
 
# File 'lib/matrix.rb', line 697

def regular?
  not singular?
end

#round(ndigits = 0) ⇒ Object

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



1143
1144
1145
 
# File 'lib/matrix.rb', line 1143

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

#row(i, &block) ⇒ Object

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.



343
344
345
346
347
348
349
350
 
# File 'lib/matrix.rb', line 343

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_size ⇒ Object

Returns the number of rows.



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

def row_size
  @rows.size
end

#row_vectors ⇒ Object

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



1287
1288
1289
1290
1291
 
# File 'lib/matrix.rb', line 1287

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

#singular? ⇒ Boolean

Returns true is this is a singular matrix.

Returns:

  • (Boolean) 


704
705
706
 
# File 'lib/matrix.rb', line 704

def singular?
  determinant == 0
end

#square? ⇒ Boolean

Returns true is this is a square matrix.

Returns:

  • (Boolean) 


711
712
713
 
# File 'lib/matrix.rb', line 711

def square?
  column_size == row_size
end

#symmetric? ⇒ Boolean

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

Returns:

  • (Boolean) 


719
720
721
722
723
724
 
# File 'lib/matrix.rb', line 719

def symmetric?
  Matrix.Raise ErrDimensionMismatch unless square?
  each_with_index(:strict_upper).all? do |e, row, col|
    e == rows[col][row]
  end
end

#to_a ⇒ Object

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



1305
1306
1307
 
# File 'lib/matrix.rb', line 1305

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

#to_s ⇒ Object

Overrides Object#to_s



1331
1332
1333
1334
1335
1336
1337
1338
1339
 
# File 'lib/matrix.rb', line 1331

def to_s
  if empty?
    "Matrix.empty(#{row_size}, #{column_size})"
  else
    "Matrix[" + @rows.collect{|row|
      "[" + row.collect{|e| e.to_s}.join(", ") + "]"
    }.join(", ")+"]"
  end
end

#trace ⇒ Object Also known as: tr

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

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



1152
1153
1154
1155
1156
1157
 
# File 'lib/matrix.rb', line 1152

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

#transpose ⇒ Object 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



1170
1171
1172
1173
 
# File 'lib/matrix.rb', line 1170

def transpose
  return Matrix.empty(column_size, 0) if row_size.zero?
  new_matrix @rows.transpose, row_size
end

#unitary? ⇒ Boolean

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

Returns:

  • (Boolean) 


730
731
732
733
734
735
736
737
738
739
740
741
742
 
# File 'lib/matrix.rb', line 730

def unitary?
  Matrix.Raise ErrDimensionMismatch unless square?
  rows.each_with_index do |row, i|
    column_size.times do |j|
      s = 0
      row_size.times do |k|
        s += row[k].conj * rows[k][j]
      end
      return false unless s == (i == j ? 1 : 0)
    end
  end
  true
end

#upper_triangular? ⇒ Boolean

Returns true is this is an upper triangular matrix.

Returns:

  • (Boolean) 


747
748
749
 
# File 'lib/matrix.rb', line 747

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

#zero? ⇒ Boolean

Returns true is this is a matrix with only zero elements

Returns:

  • (Boolean) 


754
755
756
 
# File 'lib/matrix.rb', line 754

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