Class: Matrix

Inherits:
Object
  • Object
show all
Extended by:
ConversionHelper
Includes:
Enumerable, ExceptionForMatrix, CoercionHelper
Defined in:
lib/matrix.rb,
lib/matrix/version.rb,
lib/matrix/lup_decomposition.rb,
lib/matrix/eigenvalue_decomposition.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.

Defined Under Namespace

Modules: CoercionHelper, ConversionHelper Classes: EigenvalueDecomposition, LUPDecomposition, Scalar

Constant Summary collapse

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CoercionHelper

check_int, check_range, coerce_to, coerce_to_int, coerce_to_matrix

Constructor Details

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

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


322
323
324
325
326
327
328
# 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

Instance Attribute Details

#column_countObject (readonly) Also known as: column_size

Returns the number of columns.


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

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

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

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)

123
124
125
126
127
128
129
130
131
132
133
134
# 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) ⇒ 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

209
210
211
212
# File 'lib/matrix.rb', line 209

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

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

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

.combine(*matrices) ⇒ Object

:call-seq:

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

288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
# 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) ⇒ 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

143
144
145
146
147
148
149
150
151
152
# 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) ⇒ 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)

227
228
229
230
231
232
# 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) ⇒ 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]]

262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
# 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

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

Creates an n by n identity matrix.

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

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

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

196
197
198
199
# File 'lib/matrix.rb', line 196

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

90
91
92
93
94
95
96
97
98
99
100
# 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) ⇒ Object

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

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

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

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

241
242
243
244
245
246
247
248
249
250
251
252
# 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) ⇒ Object

Creates a zero matrix.

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

185
186
187
188
# 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 Method Details

#*(m) ⇒ Object

Matrix multiplication.

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

1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
# 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) ⇒ 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

1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
# File 'lib/matrix.rb', line 1237

def **(exp)
  case exp
  when Integer
    case
    when exp == 0
      _make_sure_it_is_invertible = inverse
      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) ⇒ Object

Matrix addition.

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

1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
# 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

#[email protected]Object


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

def [email protected]
  self
end

#-(m) ⇒ Object

Matrix subtraction.

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

1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
# 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

#[email protected]Object

Unary matrix negation.

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

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

def [email protected]
  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

1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
# 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) ⇒ Object

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


1021
1022
1023
1024
1025
# 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) ⇒ Object Also known as: element, component

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


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

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

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

:call-seq:

matrix[range, range] = matrix/element
matrix[range, integer] = vector/column_matrix/element
matrix[integer, range] = vector/row_matrix/element
matrix[integer, integer] = element

Set element or elements of matrix.

Raises:

  • (FrozenError)

351
352
353
354
355
356
357
358
359
360
361
362
363
364
# 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

#absObject

Returns the absolute value elementwise


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

def abs
  collect(&:abs)
end

#adjointObject

Returns the adjoint of the matrix.

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

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

def adjoint
  conjugate.transpose
end

#adjugateObject

Returns the adjugate of the matrix.

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

793
794
795
796
797
798
# 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

#antisymmetric?Boolean Also known as: skew_symmetric?

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

Returns:

  • (Boolean)

Raises:


973
974
975
976
977
978
979
# 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

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


1619
1620
1621
1622
1623
1624
1625
1626
# File 'lib/matrix.rb', line 1619

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)

778
779
780
781
782
783
784
# 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

#collect(which = :all, &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. 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


508
509
510
511
# 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) ⇒ Object 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)

526
527
528
529
530
# 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) ⇒ 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.


477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
# 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_vectorsObject

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


1640
1641
1642
1643
1644
# File 'lib/matrix.rb', line 1640

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

#combine(*matrices, &block) ⇒ Object

:call-seq:

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

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

def combine(*matrices, &block)
  Matrix.combine(self, *matrices, &block)
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

1554
1555
1556
# File 'lib/matrix.rb', line 1554

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

1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
# 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_eObject Also known as: det_e

deprecated; use Matrix#determinant


1398
1399
1400
1401
# File 'lib/matrix.rb', line 1398

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

#diagonal?Boolean

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

Returns:

  • (Boolean)

Raises:


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

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

#each(which = :all, &block) ⇒ 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]
    

556
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
589
590
591
592
593
594
595
596
597
598
599
600
601
602
# 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) ⇒ 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

616
617
618
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
651
652
653
654
655
656
657
658
659
660
661
662
663
664
# 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

#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

1521
1522
1523
# File 'lib/matrix.rb', line 1521

def eigensystem
  EigenvalueDecomposition.new(self)
end

#elements_to_fObject

Deprecated.

Use map(&:to_f)


1663
1664
1665
1666
# File 'lib/matrix.rb', line 1663

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

#elements_to_iObject

Deprecated.

Use map(&:to_i)


1671
1672
1673
1674
# File 'lib/matrix.rb', line 1671

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

#elements_to_rObject

Deprecated.

Use map(&:to_r)


1679
1680
1681
1682
# File 'lib/matrix.rb', line 1679

def elements_to_r
  warn "Matrix#elements_to_r is deprecated, use map(&:to_r)", uplevel: 1
  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)

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

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

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean)

1027
1028
1029
1030
1031
# 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

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

751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
# 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

#freezeObject


534
535
536
537
538
# File 'lib/matrix.rb', line 534

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

  super
end

#hadamard_product(m) ⇒ Object Also known as: entrywise_product

Hadamard product

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

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

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

#hashObject

Returns a hash-code for the matrix.


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

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)

Raises:


856
857
858
859
860
861
# 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

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

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

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

1579
1580
1581
# File 'lib/matrix.rb', line 1579

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)

679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
# 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

#inspectObject

Overrides Object#inspect


1704
1705
1706
1707
1708
1709
1710
# File 'lib/matrix.rb', line 1704

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

1178
1179
1180
1181
# File 'lib/matrix.rb', line 1178

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

810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
# 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

#lower_triangular?Boolean

Returns true if this is a lower triangular matrix.

Returns:

  • (Boolean)

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

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

1536
1537
1538
# File 'lib/matrix.rb', line 1536

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.


710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
# 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

#normal?Boolean

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

Returns:

  • (Boolean)

Raises:


874
875
876
877
878
879
880
881
882
883
884
885
886
# 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

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

Returns:

  • (Boolean)

Raises:


892
893
894
895
896
897
898
899
900
901
902
903
904
905
# 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

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

Returns:

  • (Boolean)

Raises:


911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
# 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

#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

1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
# 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_eObject

deprecated; use Matrix#rank


1456
1457
1458
1459
# File 'lib/matrix.rb', line 1456

def rank_e
  warn "Matrix#rank_e is deprecated; use #rank", uplevel: 1
  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

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

def real
  collect(&:real)
end

#real?Boolean

Returns true if all entries of the matrix are real.

Returns:

  • (Boolean)

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

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

1603
1604
1605
# File 'lib/matrix.rb', line 1603

def rect
  [real, imag]
end

#regular?Boolean

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

Returns:

  • (Boolean)

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

def regular?
  not singular?
end

#round(ndigits = 0) ⇒ Object

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


1464
1465
1466
# File 'lib/matrix.rb', line 1464

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.


463
464
465
466
467
468
469
470
# 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_countObject Also known as: row_size

Returns the number of rows.


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

def row_count
  @rows.size
end

#row_vectorsObject

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


1631
1632
1633
1634
1635
# File 'lib/matrix.rb', line 1631

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

#singular?Boolean

Returns true if this is a singular matrix.

Returns:

  • (Boolean)

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

def singular?
  determinant == 0
end

#square?Boolean

Returns true if this is a square matrix.

Returns:

  • (Boolean)

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

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)

Raises:


961
962
963
964
965
966
967
# 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

#to_aObject

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


1656
1657
1658
# File 'lib/matrix.rb', line 1656

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

#to_matrixObject

Explicit conversion to a Matrix. Returns self


1649
1650
1651
# File 'lib/matrix.rb', line 1649

def to_matrix
  self
end

#to_sObject

Overrides Object#to_s


1691
1692
1693
1694
1695
1696
1697
1698
1699
# File 'lib/matrix.rb', line 1691

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

1473
1474
1475
1476
1477
1478
# File 'lib/matrix.rb', line 1473

def trace
  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

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

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)

Raises:


986
987
988
989
990
991
992
993
994
995
996
997
998
# 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

Returns true if this is an upper triangular matrix.

Returns:

  • (Boolean)

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

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

1505
1506
1507
# File 'lib/matrix.rb', line 1505

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

#zero?Boolean

Returns true if this is a matrix with only zero elements

Returns:

  • (Boolean)

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

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