Extended maintenance of Ruby versions 1.8.7 and 1.9.2 ended on July 31, 2014. Read more
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)
Matrix.rows(rows, copy = true)
Matrix.columns(columns)
Matrix.build(row_size, column_size, &block)
Matrix.diagonal(*values)
Matrix.scalar(n, value)
Matrix.identity(n)
Matrix.unit(n)
Matrix.I(n)
Matrix.zero(n)
Matrix.row_vector(row)
Matrix.column_vector(column)
To access Matrix elements/columns/rows/submatrices/properties:
[](i, j)
#row_size
#column_size
#row(i)
#column(j)
#collect
#map
#each
#each_with_index
#minor(*param)
Properties of a matrix:
#empty?
#real?
#regular?
#singular?
#square?
Matrix arithmetic:
*(m)
+(m)
-(m)
#/(m)
#inverse
#inv
**
Matrix functions:
#determinant
#det
#rank
#trace
#tr
#transpose
#t
Complex arithmetic:
conj
conjugate
imag
imaginary
real
rect
rectangular
Conversion to other data types:
#coerce(other)
#row_vectors
#column_vectors
#to_a
String representations:
#to_s
#inspect
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
::new is private; use ::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 #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 #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