Class: Matrix

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

Constants included from Exception2MessageMapper

Exception2MessageMapper::E2MM

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CoercionHelper

coerce_to, coerce_to_int, coerce_to_matrix

Methods included from Exception2MessageMapper

#Fail, Raise, #Raise, #bind, def_e2message, #def_e2message, #def_exception, def_exception, e2mm_message, extend_object, #fail

Methods included from Enumerable

#each_async, #to_json, #to_set

Constructor Details

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

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



284
285
286
287
288
289
290
 
# File 'opal/stdlib/matrix.rb', line 284

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_count ⇒ Object (readonly) Also known as: column_size

Returns the number of columns.



324
325
326
 
# File 'opal/stdlib/matrix.rb', line 324

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



51
52
53
 
# File 'opal/stdlib/matrix.rb', line 51

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) 


96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'opal/stdlib/matrix.rb', line 96

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



182
183
184
185
 
# File 'opal/stdlib/matrix.rb', line 182

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



81
82
83
 
# File 'opal/stdlib/matrix.rb', line 81

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

.combine(*matrices) ⇒ Object

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



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'opal/stdlib/matrix.rb', line 259

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



116
117
118
119
120
121
122
123
124
125
 
# File 'opal/stdlib/matrix.rb', line 116

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) 


200
201
202
203
204
205
 
# File 'opal/stdlib/matrix.rb', line 200

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



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'opal/stdlib/matrix.rb', line 235

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



144
145
146
 
# File 'opal/stdlib/matrix.rb', line 144

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



169
170
171
172
 
# File 'opal/stdlib/matrix.rb', line 169

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



63
64
65
66
67
68
69
70
71
72
73
 
# File 'opal/stdlib/matrix.rb', line 63

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



134
135
136
 
# File 'opal/stdlib/matrix.rb', line 134

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



214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'opal/stdlib/matrix.rb', line 214

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



158
159
160
161
 
# File 'opal/stdlib/matrix.rb', line 158

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



893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
 
# File 'opal/stdlib/matrix.rb', line 893

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



1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
 
# File 'opal/stdlib/matrix.rb', line 1071

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



926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
 
# File 'opal/stdlib/matrix.rb', line 926

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 



1094
1095
1096
 
# File 'opal/stdlib/matrix.rb', line 1094

def +@
  self
end

#-(m) ⇒ Object

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



953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
 
# File 'opal/stdlib/matrix.rb', line 953

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 



1098
1099
1100
 
# File 'opal/stdlib/matrix.rb', line 1098

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



980
981
982
983
984
985
986
987
988
989
990
991
992
 
# File 'opal/stdlib/matrix.rb', line 980

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.



855
856
857
858
859
 
# File 'opal/stdlib/matrix.rb', line 855

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



300
301
302
 
# File 'opal/stdlib/matrix.rb', line 300

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

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



306
307
308
 
# File 'opal/stdlib/matrix.rb', line 306

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

#adjugate ⇒ Object

Returns the adjugate of the matrix.

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



629
630
631
632
633
634
 
# File 'opal/stdlib/matrix.rb', line 629

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

#antisymmetric? ⇒ Boolean

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

Returns:



808
809
810
811
812
813
814
 
# File 'opal/stdlib/matrix.rb', line 808

def antisymmetric?
  Matrix.Raise ErrDimensionMismatch unless square?
  each_with_index(:upper) do |e, row, col|
    return false unless e == -rows[col][row]
  end
  true
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.



872
873
874
 
# File 'opal/stdlib/matrix.rb', line 872

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.



1408
1409
1410
1411
1412
1413
1414
1415
 
# File 'opal/stdlib/matrix.rb', line 1408

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) 


614
615
616
617
618
619
620
 
# File 'opal/stdlib/matrix.rb', line 614

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



368
369
370
371
372
 
# File 'opal/stdlib/matrix.rb', line 368

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.



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'opal/stdlib/matrix.rb', line 345

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

#column_vectors ⇒ Object

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



1429
1430
1431
1432
1433
 
# File 'opal/stdlib/matrix.rb', line 1429

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

#combine(*matrices, &block) ⇒ Object 



277
278
279
 
# File 'opal/stdlib/matrix.rb', line 277

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



1354
1355
1356
 
# File 'opal/stdlib/matrix.rb', line 1354

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



1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
 
# File 'opal/stdlib/matrix.rb', line 1116

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_e ⇒ Object Also known as: det_e

deprecated; use Matrix#determinant



1198
1199
1200
1201
 
# File 'opal/stdlib/matrix.rb', line 1198

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:



675
676
677
678
 
# File 'opal/stdlib/matrix.rb', line 675

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]



391
392
393
394
395
396
397
398
399
400
401
402
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
 
# File 'opal/stdlib/matrix.rb', line 391

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



452
453
454
455
456
457
458
459
460
461
462
463
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
 
# File 'opal/stdlib/matrix.rb', line 452

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

#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



1321
1322
1323
 
# File 'opal/stdlib/matrix.rb', line 1321

def eigensystem
  EigenvalueDecomposition.new(self)
end

#elements_to_f ⇒ Object

Deprecated.

Use map(&:to_f)



1452
1453
1454
1455
 
# File 'opal/stdlib/matrix.rb', line 1452

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

#elements_to_i ⇒ Object

Deprecated.

Use map(&:to_i)



1460
1461
1462
1463
 
# File 'opal/stdlib/matrix.rb', line 1460

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

#elements_to_r ⇒ Object

Deprecated.

Use map(&:to_r)



1468
1469
1470
1471
 
# File 'opal/stdlib/matrix.rb', line 1468

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:



684
685
686
 
# File 'opal/stdlib/matrix.rb', line 684

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

#eql?(other) ⇒ Boolean

Returns:



861
862
863
864
865
 
# File 'opal/stdlib/matrix.rb', line 861

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) 


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

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

#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



1000
1001
1002
 
# File 'opal/stdlib/matrix.rb', line 1000

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

#hash ⇒ Object

Returns a hash-code for the matrix.



879
880
881
 
# File 'opal/stdlib/matrix.rb', line 879

def hash
  @rows.hash
end

#hermitian? ⇒ Boolean

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

Returns:



692
693
694
695
696
697
 
# File 'opal/stdlib/matrix.rb', line 692

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



1212
1213
1214
 
# File 'opal/stdlib/matrix.rb', line 1212

def hstack(*matrices)
  self.class.hstack(self, *matrices)
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



1368
1369
1370
 
# File 'opal/stdlib/matrix.rb', line 1368

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) 


515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
 
# File 'opal/stdlib/matrix.rb', line 515

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



1493
1494
1495
1496
1497
1498
1499
 
# File 'opal/stdlib/matrix.rb', line 1493

def inspect
  if empty?
    "#{self.class}.empty(#{row_count}, #{column_count})"
  else
    "#{self.class}#{@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



1011
1012
1013
1014
 
# File 'opal/stdlib/matrix.rb', line 1011

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) 


646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
 
# File 'opal/stdlib/matrix.rb', line 646

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:



702
703
704
 
# File 'opal/stdlib/matrix.rb', line 702

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



1336
1337
1338
 
# File 'opal/stdlib/matrix.rb', line 1336

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.



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
574
575
576
577
 
# File 'opal/stdlib/matrix.rb', line 546

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:



710
711
712
713
714
715
716
717
718
719
720
721
722
 
# File 'opal/stdlib/matrix.rb', line 710

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:



728
729
730
731
732
733
734
735
736
737
738
739
740
 
# File 'opal/stdlib/matrix.rb', line 728

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:



746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
 
# File 'opal/stdlib/matrix.rb', line 746

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

#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



1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
 
# File 'opal/stdlib/matrix.rb', line 1225

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

#rank_e ⇒ Object

deprecated; use Matrix#rank



1256
1257
1258
1259
 
# File 'opal/stdlib/matrix.rb', line 1256

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



1382
1383
1384
 
# File 'opal/stdlib/matrix.rb', line 1382

def real
  collect(&:real)
end

#real? ⇒ Boolean

Returns +true+ if all entries of the matrix are real.

Returns:



767
768
769
 
# File 'opal/stdlib/matrix.rb', line 767

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



1392
1393
1394
 
# File 'opal/stdlib/matrix.rb', line 1392

def rect
  [real, imag]
end

#regular? ⇒ Boolean

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

Returns:



774
775
776
 
# File 'opal/stdlib/matrix.rb', line 774

def regular?
  not singular?
end

#round(ndigits = 0) ⇒ Object

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



1264
1265
1266
 
# File 'opal/stdlib/matrix.rb', line 1264

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.



331
332
333
334
335
336
337
338
 
# File 'opal/stdlib/matrix.rb', line 331

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

#row_count ⇒ Object Also known as: row_size

Returns the number of rows.



316
317
318
 
# File 'opal/stdlib/matrix.rb', line 316

def row_count
  @rows.size
end

#row_vectors ⇒ Object

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



1420
1421
1422
1423
1424
 
# File 'opal/stdlib/matrix.rb', line 1420

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

#singular? ⇒ Boolean

Returns +true+ if this is a singular matrix.

Returns:



781
782
783
 
# File 'opal/stdlib/matrix.rb', line 781

def singular?
  determinant == 0
end

#square? ⇒ Boolean

Returns +true+ if this is a square matrix.

Returns:



788
789
790
 
# File 'opal/stdlib/matrix.rb', line 788

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:



796
797
798
799
800
801
802
 
# File 'opal/stdlib/matrix.rb', line 796

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

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



1445
1446
1447
 
# File 'opal/stdlib/matrix.rb', line 1445

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

#to_matrix ⇒ Object

Explicit conversion to a Matrix. Returns self



1438
1439
1440
 
# File 'opal/stdlib/matrix.rb', line 1438

def to_matrix
  self
end

#to_s ⇒ Object

Overrides Object#to_s



1480
1481
1482
1483
1484
1485
1486
1487
1488
 
# File 'opal/stdlib/matrix.rb', line 1480

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

#trace ⇒ Object Also known as: tr

Returns the trace (sum of diagonal elements) of the matrix. Matrix[[7,6], [3,9]].trace => 16



1273
1274
1275
1276
1277
1278
 
# File 'opal/stdlib/matrix.rb', line 1273

def trace
  Matrix.Raise ErrDimensionMismatch unless square?
  (0...column_count).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



1291
1292
1293
1294
 
# File 'opal/stdlib/matrix.rb', line 1291

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:



820
821
822
823
824
825
826
827
828
829
830
831
832
 
# File 'opal/stdlib/matrix.rb', line 820

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:



837
838
839
 
# File 'opal/stdlib/matrix.rb', line 837

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



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

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

#zero? ⇒ Boolean

Returns +true+ if this is a matrix with only zero elements

Returns:



844
845
846
 
# File 'opal/stdlib/matrix.rb', line 844

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