Object
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).
To create a matrix:
Matrix.[](*rows)
Matrix.rows(rows, copy = true)
Matrix.build(row_size, column_size, &block)
Matrix.scalar(n, value)
Matrix.I(n)
To access Matrix elements/columns/rows/submatrices/properties:
Properties of a matrix:
Matrix arithmetic:
Matrix functions:
Complex arithmetic:
conj
conjugate
imag
imaginary
real
rect
rectangular
Conversion to other data types:
String representations:
Creates a matrix where each argument is a row.
Matrix[ [25, 93], [-1, 66] ] => 25 93 -1 66
# File matrix.rb, line 119
def Matrix.[](*rows)
Matrix.rows(rows, false)
end
Creates a matrix of size row_size x column_size. It fills the values by calling the given block, passing the current row and column. Returns an enumerator if no block is given.
m = Matrix.build(2, 4) {|row, col| col - row } => Matrix[[0, 1, 2, 3], [-1, 0, 1, 2]] m = Matrix.build(3) { rand } => a 3x3 matrix with random elements
# File matrix.rb, line 164
def Matrix.build(row_size, column_size = row_size)
row_size = CoercionHelper.coerce_to_int(row_size)
column_size = CoercionHelper.coerce_to_int(column_size)
raise ArgumentError if row_size < 0 || column_size < 0
return to_enum :build, row_size, column_size unless block_given?
rows = Array.new(row_size) do |i|
Array.new(column_size) do |j|
yield i, j
end
end
new rows, column_size
end
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
# File matrix.rb, line 248
def Matrix.column_vector(column)
column = convert_to_array(column)
new [column].transpose, 1
end
Creates a matrix using columns as an array of column vectors.
Matrix.columns([[25, 93], [-1, 66]]) => 25 -1 93 66
# File matrix.rb, line 149
def Matrix.columns(columns)
Matrix.rows(columns, false).transpose
end
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
# File matrix.rb, line 184
def Matrix.diagonal(*values)
size = values.size
rows = Array.new(size) {|j|
row = Array.new(size, 0)
row[j] = values[j]
row
}
new rows
end
Creates a empty matrix of row_size x column_size. At least one of row_size or column_size must be 0.
m = Matrix.empty(2, 0) m == Matrix[ [], [] ] => true n = Matrix.empty(0, 3) n == Matrix.columns([ [], [], [] ]) => true m * n => Matrix[[0, 0, 0], [0, 0, 0]]
# File matrix.rb, line 266
def Matrix.empty(row_size = 0, column_size = 0)
Matrix.Raise ArgumentError, "One size must be 0" if column_size != 0 && row_size != 0
Matrix.Raise ArgumentError, "Negative size" if column_size < 0 || row_size < 0
new([[]]*row_size, column_size)
end
Creates an n by n identity matrix.
Matrix.identity(2) => 1 0 0 1
# File matrix.rb, line 211
def Matrix.identity(n)
Matrix.scalar(n, 1)
end
Matrix.new is private; use Matrix.rows, columns, [], etc... to create.
# File matrix.rb, line 276
def initialize(rows, column_size = rows[0].size)
# No checking is done at this point. rows must be an Array of Arrays.
# column_size must be the size of the first row, if there is one,
# otherwise it *must* be specified and can be any integer >= 0
@rows = rows
@column_size = column_size
end
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
# File matrix.rb, line 235
def Matrix.row_vector(row)
row = convert_to_array(row)
new [row]
end
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
# File matrix.rb, line 131
def Matrix.rows(rows, copy = true)
rows = convert_to_array(rows)
rows.map! do |row|
convert_to_array(row, copy)
end
size = (rows[0] || []).size
rows.each do |row|
Matrix.Raise ErrDimensionMismatch, "row size differs (#{row.size} should be #{size})" unless row.size == size
end
new rows, size
end
Matrix multiplication.
Matrix[[2,4], [6,8]] * Matrix.identity(2) => 2 4 6 8
# File matrix.rb, line 532
def *(m) # m is matrix or vector or number
case(m)
when Numeric
rows = @rows.collect {|row|
row.collect {|e| e * m }
}
return new_matrix rows, column_size
when Vector
m = Matrix.column_vector(m)
r = self * m
return r.column(0)
when Matrix
Matrix.Raise ErrDimensionMismatch if column_size != m.row_size
rows = Array.new(row_size) {|i|
Array.new(m.column_size) {|j|
(0 ... column_size).inject(0) do |vij, k|
vij + self[i, k] * m[k, j]
end
}
}
return new_matrix rows, m.column_size
else
return apply_through_coercion(m, __method__)
end
end
Matrix exponentiation. Currently implemented for integer powers only. Equivalent to multiplying the matrix by itself N times.
Matrix[[7,6], [3,9]] ** 2 => 67 96 48 99
# File matrix.rb, line 697
def ** (other)
case other
when Integer
x = self
if other <= 0
x = self.inverse
return Matrix.identity(self.column_size) if other == 0
other = -other
end
z = nil
loop do
z = z ? z * x : x if other[0] == 1
return z if (other >>= 1).zero?
x *= x
end
when Float, Rational
Matrix.Raise ErrOperationNotImplemented, "**", self.class, other.class
else
Matrix.Raise ErrOperationNotDefined, "**", self.class, other.class
end
end
Matrix addition.
Matrix.scalar(2,5) + Matrix[[1,0], [-4,7]] => 6 0 -4 12
# File matrix.rb, line 565
def +(m)
case m
when Numeric
Matrix.Raise ErrOperationNotDefined, "+", self.class, m.class
when Vector
m = Matrix.column_vector(m)
when Matrix
else
return apply_through_coercion(m, __method__)
end
Matrix.Raise ErrDimensionMismatch unless row_size == m.row_size and column_size == m.column_size
rows = Array.new(row_size) {|i|
Array.new(column_size) {|j|
self[i, j] + m[i, j]
}
}
new_matrix rows, column_size
end
Matrix subtraction.
Matrix[[1,5], [4,2]] - Matrix[[9,3], [-4,1]] => -8 2 8 1
# File matrix.rb, line 592
def -(m)
case m
when Numeric
Matrix.Raise ErrOperationNotDefined, "-", self.class, m.class
when Vector
m = Matrix.column_vector(m)
when Matrix
else
return apply_through_coercion(m, __method__)
end
Matrix.Raise ErrDimensionMismatch unless row_size == m.row_size and column_size == m.column_size
rows = Array.new(row_size) {|i|
Array.new(column_size) {|j|
self[i, j] - m[i, j]
}
}
new_matrix rows, column_size
end
Matrix division (multiplication by the inverse).
Matrix[[7,6], [3,9]] / Matrix[[2,9], [3,1]] => -7 1 -3 -6
# File matrix.rb, line 619
def /(other)
case other
when Numeric
rows = @rows.collect {|row|
row.collect {|e| e / other }
}
return new_matrix rows, column_size
when Matrix
return self * other.inverse
else
return apply_through_coercion(other, __method__)
end
end
Returns true if and only if the two matrices contain equal elements.
# File matrix.rb, line 494
def ==(other)
return false unless Matrix === other &&
column_size == other.column_size # necessary for empty matrices
rows == other.rows
end
Returns element (i,j) of the matrix. That is: row i, column j.
# File matrix.rb, line 292
def [](i, j)
@rows.fetch(i){return nil}[j]
end
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.
# File matrix.rb, line 511
def clone
new_matrix @rows.map(&:dup), column_size
end
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.
# File matrix.rb, line 964
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
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
# File matrix.rb, line 358
def collect(&block) # :yield: e
return to_enum(:collect) unless block_given?
rows = @rows.collect{|row| row.collect(&block)}
new_matrix rows, column_size
end
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.
# File matrix.rb, line 335
def column(j) # :yield: e
if block_given?
return self if j >= column_size || j < -column_size
row_size.times do |i|
yield @rows[i][j]
end
self
else
return nil if j >= column_size || j < -column_size
col = Array.new(row_size) {|i|
@rows[i][j]
}
Vector.elements(col, false)
end
end
Returns an array of the column vectors of the matrix. See Vector.
# File matrix.rb, line 985
def column_vectors
Array.new(column_size) {|i|
column(i)
}
end
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
# File matrix.rb, line 910
def conjugate
collect(&:conjugate)
end
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
# File matrix.rb, line 733
def determinant
Matrix.Raise ErrDimensionMismatch unless square?
m = @rows
case row_size
# Up to 4x4, give result using Laplacian expansion by minors.
# This will typically be faster, as well as giving good results
# in case of Floats
when 0
+1
when 1
+ m[0][0]
when 2
+ m[0][0] * m[1][1] - m[0][1] * m[1][0]
when 3
m0, m1, m2 = m
+ m0[0] * m1[1] * m2[2] - m0[0] * m1[2] * m2[1] - m0[1] * m1[0] * m2[2] + m0[1] * m1[2] * m2[0] + m0[2] * m1[0] * m2[1] - m0[2] * m1[1] * m2[0]
when 4
m0, m1, m2, m3 = m
+ m0[0] * m1[1] * m2[2] * m3[3] - m0[0] * m1[1] * m2[3] * m3[2] - m0[0] * m1[2] * m2[1] * m3[3] + m0[0] * m1[2] * m2[3] * m3[1] + m0[0] * m1[3] * m2[1] * m3[2] - m0[0] * m1[3] * m2[2] * m3[1] - m0[1] * m1[0] * m2[2] * m3[3] + m0[1] * m1[0] * m2[3] * m3[2] + m0[1] * m1[2] * m2[0] * m3[3] - m0[1] * m1[2] * m2[3] * m3[0] - m0[1] * m1[3] * m2[0] * m3[2] + m0[1] * m1[3] * m2[2] * m3[0] + m0[2] * m1[0] * m2[1] * m3[3] - m0[2] * m1[0] * m2[3] * m3[1] - m0[2] * m1[1] * m2[0] * m3[3] + m0[2] * m1[1] * m2[3] * m3[0] + m0[2] * m1[3] * m2[0] * m3[1] - m0[2] * m1[3] * m2[1] * m3[0] - m0[3] * m1[0] * m2[1] * m3[2] + m0[3] * m1[0] * m2[2] * m3[1] + m0[3] * m1[1] * m2[0] * m3[2] - m0[3] * m1[1] * m2[2] * m3[0] - m0[3] * m1[2] * m2[0] * m3[1] + m0[3] * m1[2] * m2[1] * m3[0]
else
# For bigger matrices, use an efficient and general algorithm.
# Currently, we use the Gauss-Bareiss algorithm
determinant_bareiss
end
end
deprecated; use Matrix#determinant
# File matrix.rb, line 815
def determinant_e
warn "#{caller(1)[0]}: warning: Matrix#determinant_e is deprecated; use #determinant"
rank
end
Yields all elements of the matrix, starting with those of the first row, or returns an Enumerator is no block given
Matrix[ [1,2], [3,4] ].each { |e| puts e } # => prints the numbers 1 to 4
# File matrix.rb, line 371
def each(&block) # :yield: e
return to_enum(:each) unless block_given?
@rows.each do |row|
row.each(&block)
end
self
end
Yields all elements of the matrix, starting with those of the first row, along with the row index and column index, or returns an Enumerator is no block given
Matrix[ [1,2], [3,4] ].each_with_index do |e, row, col| puts "#{e} at #{row}, #{col}" end # => 1 at 0, 0 # => 2 at 0, 1 # => 3 at 1, 0 # => 4 at 1, 1
# File matrix.rb, line 391
def each_with_index(&block) # :yield: e, row, column
return to_enum(:each_with_index) unless block_given?
@rows.each_with_index do |row, row_index|
row.each_with_index do |e, col_index|
yield e, row_index, col_index
end
end
self
end
# File matrix.rb, line 998
def elements_to_f
warn "#{caller(1)[0]}: warning: Matrix#elements_to_f is deprecated, use map(&:to_f)"
map(&:to_f)
end
# File matrix.rb, line 1003
def elements_to_i
warn "#{caller(1)[0]}: warning: Matrix#elements_to_i is deprecated, use map(&:to_i)"
map(&:to_i)
end
# File matrix.rb, line 1008
def elements_to_r
warn "#{caller(1)[0]}: warning: Matrix#elements_to_r is deprecated, use map(&:to_r)"
map(&:to_r)
end
Returns true if this is an empty matrix, i.e. if the number of rows or the number of columns is 0.
# File matrix.rb, line 455
def empty?
column_size == 0 || row_size == 0
end
# File matrix.rb, line 500
def eql?(other)
return false unless Matrix === other &&
column_size == other.column_size # necessary for empty matrices
rows.eql? other.rows
end
Returns a hash-code for the matrix.
# File matrix.rb, line 518
def hash
@rows.hash
end
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
# File matrix.rb, line 924
def imaginary
collect(&:imaginary)
end
Overrides Object#inspect
# File matrix.rb, line 1033
def inspect
if empty?
"Matrix.empty(#{row_size}, #{column_size})"
else
"Matrix#{@rows.inspect}"
end
end
Returns the inverse of the matrix.
Matrix[[-1, -1], [0, -1]].inverse => -1 1 0 -1
# File matrix.rb, line 639
def inverse
Matrix.Raise ErrDimensionMismatch unless square?
Matrix.I(row_size).send(:inverse_from, self)
end
Returns a section of the matrix. The parameters are either:
start_row, nrows, start_col, ncols; OR
row_range, col_range
Matrix.diagonal(9, 5, -3).minor(0..1, 0..2) => 9 0 0 0 5 0
Like Array#[], negative indices count backward from the end of the row or column (-1 is the last element). Returns nil if the starting row or column is greater than row_size or column_size respectively.
# File matrix.rb, line 414
def minor(*param)
case param.size
when 2
row_range, col_range = param
from_row = row_range.first
from_row += row_size if from_row < 0
to_row = row_range.end
to_row += row_size if to_row < 0
to_row += 1 unless row_range.exclude_end?
size_row = to_row - from_row
from_col = col_range.first
from_col += column_size if from_col < 0
to_col = col_range.end
to_col += column_size if to_col < 0
to_col += 1 unless col_range.exclude_end?
size_col = to_col - from_col
when 4
from_row, size_row, from_col, size_col = param
return nil if size_row < 0 || size_col < 0
from_row += row_size if from_row < 0
from_col += column_size if from_col < 0
else
Matrix.Raise ArgumentError, param.inspect
end
return nil if from_row > row_size || from_col > column_size || from_row < 0 || from_col < 0
rows = @rows[from_row, size_row].collect{|row|
row[from_col, size_col]
}
new_matrix rows, [column_size - from_col, size_col].min
end
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
# File matrix.rb, line 830
def rank
# We currently use Bareiss' multistep integer-preserving gaussian elimination
# (see comments on determinant)
a = to_a
last_column = column_size - 1
last_row = row_size - 1
rank = 0
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
deprecated; use Matrix#rank
# File matrix.rb, line 862
def rank_e
warn "#{caller(1)[0]}: warning: Matrix#rank_e is deprecated; use #rank"
rank
end
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
# File matrix.rb, line 938
def real
collect(&:real)
end
Returns true if all entries of the matrix are real.
# File matrix.rb, line 462
def real?
all?(&:real?)
end
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
# File matrix.rb, line 948
def rect
[real, imag]
end
Returns true if this is a regular (i.e. non-singular) matrix.
# File matrix.rb, line 469
def regular?
not singular?
end
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.
# File matrix.rb, line 321
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
Returns the number of rows.
# File matrix.rb, line 308
def row_size
@rows.size
end
Returns an array of the row vectors of the matrix. See Vector.
# File matrix.rb, line 976
def row_vectors
Array.new(row_size) {|i|
row(i)
}
end
Returns true is this is a singular matrix.
# File matrix.rb, line 476
def singular?
determinant == 0
end
Returns true is this is a square matrix.
# File matrix.rb, line 483
def square?
column_size == row_size
end
Returns an array of arrays that describe the rows of the matrix.
# File matrix.rb, line 994
def to_a
@rows.collect(&:dup)
end
Overrides Object#to_s
# File matrix.rb, line 1020
def to_s
if empty?
"Matrix.empty(#{row_size}, #{column_size})"
else
"Matrix[" + @rows.collect{|row|
"[" + row.collect{|e| e.to_s}.join(", ") + "]"
}.join(", ")+"]"
end
end
Returns the trace (sum of diagonal elements) of the matrix.
Matrix[[7,6], [3,9]].trace => 16
# File matrix.rb, line 873
def trace
Matrix.Raise ErrDimensionMismatch unless square?
(0...column_size).inject(0) do |tr, i|
tr + @rows[i][i]
end
end
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
# File matrix.rb, line 891
def transpose
return Matrix.empty(column_size, 0) if row_size.zero?
new_matrix @rows.transpose, row_size
end