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

  • Matrix.[](*rows)

  • Matrix.rows(rows, copy = true)

  • Matrix.columns(columns)

  • Matrix.build(row_count, column_count, &block)

  • Matrix.diagonal(*values)

  • Matrix.scalar(n, value)

  • Matrix.identity(n)

  • Matrix.unit(n)

  • Matrix.I(n)

  • Matrix.zero(n)

  • Matrix.row_vector(row)

  • Matrix.column_vector(column)

  • Matrix.empty(row_count, column_count)

  • Matrix.hstack(*matrices)

  • Matrix.vstack(*matrices)

To access Matrix elements/columns/rows/submatrices/properties:

  • #[](i, j)

  • #row_count (row_size)

  • #column_count (column_size)

  • #row(i)

  • #column(j)

  • #collect

  • #map

  • #each

  • #each_with_index

  • #find_index

  • #minor(*param)

  • #first_minor(row, column)

  • #cofactor(row, column)

  • #adjugate

  • #laplace_expansion(row_or_column: num)

  • #cofactor_expansion(row_or_column: num)

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

  • #hstack(*matrices)

  • #rank

  • #round

  • #trace

  • #tr

  • #transpose

  • #t

  • #vstack(*matrices)

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_count = rows[0].size) ⇒ Matrix

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



357
358
359
360
361
362
363
# File 'lib/matrix.rb', line 357

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

Instance Attribute Details

#column_countObject (readonly) Also known as: column_size

Returns the number of columns.



397
398
399
# File 'lib/matrix.rb', line 397

def column_count
  @column_count
end

Class Method Details

.[](*rows) ⇒ Object

Creates a matrix where each argument is a row.

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


153
154
155
# File 'lib/matrix.rb', line 153

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

.build(row_count, column_count = row_count) ⇒ Object

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)


198
199
200
201
202
203
204
205
206
207
208
209
# File 'lib/matrix.rb', line 198

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) ⇒ 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


284
285
286
287
# File 'lib/matrix.rb', line 284

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


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

def Matrix.columns(columns)
  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


218
219
220
221
222
223
224
225
226
227
# File 'lib/matrix.rb', line 218

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

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)


302
303
304
305
306
307
# File 'lib/matrix.rb', line 302

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

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

Raises:

  • (TypeError)


337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
# File 'lib/matrix.rb', line 337

def Matrix.hstack(x, *matrices)
  raise TypeError, "Expected a Matrix, got a #{x.class}" unless x.is_a?(Matrix)
  result = x.send(:rows).map(&:dup)
  total_column_count = x.column_count
  matrices.each do |m|
    raise TypeError, "Expected a Matrix, got a #{m.class}" unless m.is_a?(Matrix)
    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

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

Creates an n by n identity matrix.

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


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

def Matrix.identity(n)
  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


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

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


165
166
167
168
169
170
171
172
173
174
175
# File 'lib/matrix.rb', line 165

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

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

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


236
237
238
# File 'lib/matrix.rb', line 236

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

.vstack(x, *matrices) ⇒ Object

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

Raises:

  • (TypeError)


316
317
318
319
320
321
322
323
324
325
326
327
# File 'lib/matrix.rb', line 316

def Matrix.vstack(x, *matrices)
  raise TypeError, "Expected a Matrix, got a #{x.class}" unless x.is_a?(Matrix)
  result = x.send(:rows).map(&:dup)
  matrices.each do |m|
    raise TypeError, "Expected a Matrix, got a #{m.class}" unless m.is_a?(Matrix)
    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) ⇒ Object

Creates a zero matrix.

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


260
261
262
263
# File 'lib/matrix.rb', line 260

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 Method Details

#*(m) ⇒ Object

Matrix multiplication.

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


954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
# File 'lib/matrix.rb', line 954

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_count
  when Vector
    m = self.class.column_vector(m)
    r = self * m
    return r.column(0)
  when Matrix
    Matrix.Raise ErrDimensionMismatch if column_count != m.row_count

    rows = Array.new(row_count) {|i|
      Array.new(m.column_count) {|j|
        (0 ... column_count).inject(0) do |vij, k|
          vij + self[i, k] * m[k, j]
        end
      }
    }
    return new_matrix rows, m.column_count
  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


1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
# File 'lib/matrix.rb', line 1121

def ** (other)
  case other
  when Integer
    x = self
    if other <= 0
      x = self.inverse
      return self.class.identity(self.column_count) 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 * self.class.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


987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
# File 'lib/matrix.rb', line 987

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

  Matrix.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

#+@Object



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

def +@
  self
end

#-(m) ⇒ Object

Matrix subtraction.

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


1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
# File 'lib/matrix.rb', line 1014

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

  Matrix.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

#-@Object



1148
1149
1150
# File 'lib/matrix.rb', line 1148

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

#/(other) ⇒ Object

Matrix division (multiplication by the inverse).

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


1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
# File 'lib/matrix.rb', line 1041

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

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



916
917
918
919
920
# File 'lib/matrix.rb', line 916

def ==(other)
  return false unless Matrix === other &&
                      column_count == other.column_count # 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.



373
374
375
# File 'lib/matrix.rb', line 373

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

#[]=(i, j, v) ⇒ Object Also known as: set_element, set_component



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

def []=(i, j, v)
  @rows[i][j] = v
end

#adjugateObject

Returns the adjugate of the matrix.

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


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

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

#cloneObject

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.



933
934
935
# File 'lib/matrix.rb', line 933

def clone
  new_matrix @rows.map(&:dup), column_count
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.



1458
1459
1460
1461
1462
1463
1464
1465
# File 'lib/matrix.rb', line 1458

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

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)


687
688
689
690
691
692
693
# File 'lib/matrix.rb', line 687

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

  det_of_minor = first_minor(row, column).determinant
  det_of_minor * (-1) ** (row + column)
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


441
442
443
444
445
# File 'lib/matrix.rb', line 441

def collect(&block) # :yield: e
  return to_enum(:collect) unless block_given?
  rows = @rows.collect{|row| row.collect(&block)}
  new_matrix rows, column_count
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.



418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
# File 'lib/matrix.rb', line 418

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_vectorsObject

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



1479
1480
1481
1482
1483
# File 'lib/matrix.rb', line 1479

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

#conjugateObject 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


1404
1405
1406
# File 'lib/matrix.rb', line 1404

def conjugate
  collect(&:conjugate)
end

#determinantObject 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


1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
# File 'lib/matrix.rb', line 1166

def determinant
  Matrix.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_eObject Also known as: det_e

deprecated; use Matrix#determinant



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

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

#diagonal?Boolean

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

Returns:

  • (Boolean)


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

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



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
# File 'lib/matrix.rb', line 464

def each(which = :all) # :yield: e
  return to_enum :each, which unless block_given?
  last = column_count - 1
  case which
  when :all
    block = Proc.new
    @rows.each do |row|
      row.each(&block)
    end
  when :diagonal
    @rows.each_with_index do |row, row_index|
      yield row.fetch(row_index){return self}
    end
  when :off_diagonal
    @rows.each_with_index do |row, row_index|
      column_count.times do |col_index|
        yield row[col_index] unless row_index == col_index
      end
    end
  when :lower
    @rows.each_with_index do |row, row_index|
      0.upto([row_index, last].min) do |col_index|
        yield row[col_index]
      end
    end
  when :strict_lower
    @rows.each_with_index do |row, row_index|
      [row_index, column_count].min.times do |col_index|
        yield row[col_index]
      end
    end
  when :strict_upper
    @rows.each_with_index do |row, row_index|
      (row_index+1).upto(last) do |col_index|
        yield row[col_index]
      end
    end
  when :upper
    @rows.each_with_index do |row, row_index|
      row_index.upto(last) do |col_index|
        yield row[col_index]
      end
    end
  else
    raise ArgumentError, "expected #{which.inspect} to be one of :all, :diagonal, :off_diagonal, :lower, :strict_lower, :strict_upper or :upper"
  end
  self
end

#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


525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
# File 'lib/matrix.rb', line 525

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

#eigensystemObject 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


1371
1372
1373
# File 'lib/matrix.rb', line 1371

def eigensystem
  EigenvalueDecomposition.new(self)
end

#elements_to_fObject



1492
1493
1494
1495
# File 'lib/matrix.rb', line 1492

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_iObject



1497
1498
1499
1500
# File 'lib/matrix.rb', line 1497

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_rObject



1502
1503
1504
1505
# File 'lib/matrix.rb', line 1502

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)


757
758
759
# File 'lib/matrix.rb', line 757

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

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean)


922
923
924
925
926
# File 'lib/matrix.rb', line 922

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

#first_minor(row, column) ⇒ Object

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)


660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
# File 'lib/matrix.rb', line 660

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

#hashObject

Returns a hash-code for the matrix.



940
941
942
# File 'lib/matrix.rb', line 940

def hash
  @rows.hash
end

#hermitian?Boolean

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

Returns:

  • (Boolean)


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

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

#hstack(*matrices) ⇒ Object

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


1262
1263
1264
# File 'lib/matrix.rb', line 1262

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

#imaginaryObject 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


1418
1419
1420
# File 'lib/matrix.rb', line 1418

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)


588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
# File 'lib/matrix.rb', line 588

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

#inspectObject

Overrides Object#inspect



1527
1528
1529
1530
1531
1532
1533
# File 'lib/matrix.rb', line 1527

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

#inverseObject Also known as: inv

Returns the inverse of the matrix.

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


1061
1062
1063
1064
# File 'lib/matrix.rb', line 1061

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

#laplace_expansion(row: nil, column: nil) ⇒ Object 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:

  • (RuntimeError)


719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
# File 'lib/matrix.rb', line 719

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

  Matrix.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

#lower_triangular?Boolean

Returns true if this is a lower triangular matrix.

Returns:

  • (Boolean)


775
776
777
# File 'lib/matrix.rb', line 775

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

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


1386
1387
1388
# File 'lib/matrix.rb', line 1386

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



619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
# File 'lib/matrix.rb', line 619

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

#normal?Boolean

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

Returns:

  • (Boolean)


783
784
785
786
787
788
789
790
791
792
793
794
795
# File 'lib/matrix.rb', line 783

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 if this is an orthogonal matrix Raises an error if matrix is not square.

Returns:

  • (Boolean)


801
802
803
804
805
806
807
808
809
810
811
812
813
# File 'lib/matrix.rb', line 801

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

#permutation?Boolean

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

Returns:

  • (Boolean)


819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
# File 'lib/matrix.rb', line 819

def permutation?
  Matrix.Raise ErrDimensionMismatch unless square?
  cols = Array.new(column_count)
  rows.each_with_index do |row, i|
    found = false
    row.each_with_index do |e, j|
      if e == 1
        return false if found || cols[j]
        found = cols[j] = true
      elsif e != 0
        return false
      end
    end
    return false unless found
  end
  true
end

#rankObject

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


1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
# File 'lib/matrix.rb', line 1275

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_eObject

deprecated; use Matrix#rank



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

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

#realObject

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


1432
1433
1434
# File 'lib/matrix.rb', line 1432

def real
  collect(&:real)
end

#real?Boolean

Returns true if all entries of the matrix are real.

Returns:

  • (Boolean)


840
841
842
# File 'lib/matrix.rb', line 840

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

#rectObject 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



1442
1443
1444
# File 'lib/matrix.rb', line 1442

def rect
  [real, imag]
end

#regular?Boolean

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

Returns:

  • (Boolean)


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

def regular?
  not singular?
end

#round(ndigits = 0) ⇒ Object

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



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

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.



404
405
406
407
408
409
410
411
# File 'lib/matrix.rb', line 404

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_countObject Also known as: row_size

Returns the number of rows.



389
390
391
# File 'lib/matrix.rb', line 389

def row_count
  @rows.size
end

#row_vectorsObject

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



1470
1471
1472
1473
1474
# File 'lib/matrix.rb', line 1470

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

#singular?Boolean

Returns true if this is a singular matrix.

Returns:

  • (Boolean)


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

def singular?
  determinant == 0
end

#square?Boolean

Returns true if this is a square matrix.

Returns:

  • (Boolean)


861
862
863
# File 'lib/matrix.rb', line 861

def square?
  column_count == row_count
end

#symmetric?Boolean

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

Returns:

  • (Boolean)


869
870
871
872
873
874
875
# File 'lib/matrix.rb', line 869

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

#to_aObject

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



1488
1489
1490
# File 'lib/matrix.rb', line 1488

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

#to_sObject

Overrides Object#to_s



1514
1515
1516
1517
1518
1519
1520
1521
1522
# File 'lib/matrix.rb', line 1514

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

#traceObject Also known as: tr

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

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


1323
1324
1325
1326
1327
1328
# File 'lib/matrix.rb', line 1323

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

#transposeObject 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


1341
1342
1343
1344
# File 'lib/matrix.rb', line 1341

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

#unitary?Boolean

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

Returns:

  • (Boolean)


881
882
883
884
885
886
887
888
889
890
891
892
893
# File 'lib/matrix.rb', line 881

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

#upper_triangular?Boolean

Returns true if this is an upper triangular matrix.

Returns:

  • (Boolean)


898
899
900
# File 'lib/matrix.rb', line 898

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

#vstack(*matrices) ⇒ Object

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


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

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

#zero?Boolean

Returns true if this is a matrix with only zero elements

Returns:

  • (Boolean)


905
906
907
# File 'lib/matrix.rb', line 905

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