/Ruby 3

# class Matrix

Parent:
Object
Included modules:
Enumerable, ExceptionForMatrix

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.

SELECTORS
VERSION

### Attributes

column_count[R]

Returns the number of columns.

column_size[R]

Returns the number of columns.

rows[R]

instance creations

### Public Class Methods

I(n)
Alias for: identity
[](*rows) Show source
```# File lib/matrix.rb, line 78
def Matrix.[](*rows)
rows(rows, false)
end```

Creates a matrix where each argument is a row.

```Matrix[ [25, 93], [-1, 66] ]
#   =>  25 93
#       -1 66
```
build(row_count, column_count = row_count) { |i, j| ... } Show source
```# 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
rows = Array.new(row_count) do |i|
Array.new(column_count) do |j|
yield i, j
end
end
new rows, column_count
end```

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
```
column_vector(column) Show source
```# File lib/matrix.rb, line 209
def Matrix.column_vector(column)
column = convert_to_array(column)
new [column].transpose, 1
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
```
columns(columns) Show source
```# File lib/matrix.rb, line 108
def Matrix.columns(columns)
rows(columns, false).transpose
end```

Creates a matrix using `columns` as an array of column vectors.

```Matrix.columns([[25, 93], [-1, 66]])
#   =>  25 -1
#       93 66
```
combine(*matrices) { |*elements| ... } Show source
```# File lib/matrix.rb, line 288
def Matrix.combine(*matrices)

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

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]]
```
diagonal(*values) Show source
```# 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```

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
```
empty(row_count = 0, column_count = 0) Show source
```# 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```

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]]
```
hstack(x, *matrices) Show source
```# 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```

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]]
```
identity(n) Show source
```# File lib/matrix.rb, line 171
def Matrix.identity(n)
scalar(n, 1)
end```

Creates an `n` by `n` identity matrix.

```Matrix.identity(2)
#  => 1 0
#     0 1
```
Also aliased as: unit, I
new(rows, column_count = rows[0].size) Show source
```# 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```

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

row_vector(row) Show source
```# File lib/matrix.rb, line 196
def Matrix.row_vector(row)
row = convert_to_array(row)
new [row]
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
```
rows(rows, copy = true) Show source
```# 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```

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
```
scalar(n, value) Show source
```# File lib/matrix.rb, line 161
def Matrix.scalar(n, value)
diagonal(*Array.new(n, value))
end```

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

```Matrix.scalar(2, 5)
#  => 5 0
#     0 5
```
unit(n)
Alias for: identity
vstack(x, *matrices) Show source
```# 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```

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]]
```
zero(row_count, column_count = row_count) Show source
```# 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```

Creates a zero matrix.

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

### Public Instance Methods

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

`Matrix` multiplication.

```Matrix[[2,4], [6,8]] * Matrix.identity(2)
#  => 2 4
#     6 8
```
**(exp) Show source
```# 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```

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

`Matrix` addition.

```Matrix.scalar(2,5) + Matrix[[1,0], [-4,7]]
#  =>  6  0
#     -4 12
```
```# File lib/matrix.rb, line 1283
def [email protected]
self
end```
```# 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```

`Matrix` subtraction.

```Matrix[[1,5], [4,2]] - Matrix[[9,3], [-4,1]]
#  => -8  2
#      8  1
```
```# File lib/matrix.rb, line 1292
def [email protected]
collect {|e| -e }
end```

Unary matrix negation.

```-Matrix[[1,5], [4,2]]
# => -1 -5
#    -4 -2
```
/(other) Show source
```# 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```

`Matrix` division (multiplication by the inverse).

```Matrix[[7,6], [3,9]] / Matrix[[2,9], [3,1]]
#  => -7  1
#     -3 -6
```
==(other) Show source
```# 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```

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

[](i, j) Show source
```# File lib/matrix.rb, line 337
def [](i, j)
@rows.fetch(i){return nil}[j]
end```

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

Also aliased as: element, component
matrix[range, range] = matrix/element Show source
matrix[range, integer] = vector/column_matrix/element
matrix[integer, range] = vector/row_matrix/element
matrix[integer, integer] = element
```# 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```

`Set` element or elements of matrix.

Also aliased as: set_element, set_component
abs() Show source
```# File lib/matrix.rb, line 1299
def abs
collect(&:abs)
end```

Returns the absolute value elementwise

```# File lib/matrix.rb, line 1566
conjugate.transpose
end```

Returns the adjoint of the matrix.

```Matrix[ [i,1],[2,-i] ].adjoint
#  => -i 2
#      1 i
```
```# File lib/matrix.rb, line 793
raise ErrDimensionMismatch unless square?
Matrix.build(row_count, column_count) do |row, column|
cofactor(column, row)
end
end```

Returns the adjugate of the matrix.

```Matrix[ [7,6],[3,9] ].adjugate
#  => 9 -6
#     -3 7
```
antisymmetric?() Show source
```# 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```

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

Also aliased as: skew_symmetric?
coerce(other) Show source
```# 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```

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

cofactor(row, column) Show source
```# 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```

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
```
cofactor_expansion(row: nil, column: nil)
Alias for: laplace_expansion
collect(which = :all) { |e| ... } Show source
```# File lib/matrix.rb, line 508
def collect(which = :all, &block) # :yield: e
dup.collect!(which, &block)
end```

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

Also aliased as: map
collect!(which = :all) { |e| ... } Show source
```# File lib/matrix.rb, line 526
def collect!(which = :all)
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```

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

Also aliased as: map!
column(j) { |e| ... } Show source
```# 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```

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.

column_vectors() Show source
```# File lib/matrix.rb, line 1640
def column_vectors
Array.new(column_count) {|i|
column(i)
}
end```

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

combine(*other_matrices) { |*elements| ... } Show source
```# File lib/matrix.rb, line 315
def combine(*matrices, &block)
Matrix.combine(self, *matrices, &block)
end```

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]]
```
component(i, j)
Alias for: []
conj()
Alias for: conjugate
conjugate() Show source
```# File lib/matrix.rb, line 1554
def conjugate
collect(&:conjugate)
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
```
Also aliased as: conj
det()
Alias for: determinant
det_e()
Alias for: determinant_e
determinant() Show source
```# 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```

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
```
Also aliased as: det
determinant_e() Show source
```# File lib/matrix.rb, line 1398
def determinant_e
warn "Matrix#determinant_e is deprecated; use #determinant", uplevel: 1
determinant
end```

deprecated; use `Matrix#determinant`

Also aliased as: det_e
diagonal?() Show source
```# File lib/matrix.rb, line 839
def diagonal?
raise ErrDimensionMismatch unless square?
each(:off_diagonal).all?(&:zero?)
end```

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

each(which = :all) { |e| ... } Show source
```# File lib/matrix.rb, line 556
def each(which = :all, &block) # :yield: e
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```

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]
```
each_with_index(which = :all) { |e, row, column| ... } Show source
```# File lib/matrix.rb, line 616
def each_with_index(which = :all) # :yield: e, row, column
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```

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
```
eigen()
Alias for: eigensystem
eigensystem() Show source
```# File lib/matrix.rb, line 1521
def eigensystem
EigenvalueDecomposition.new(self)
end```

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
```
Also aliased as: eigen
element(i, j)
Alias for: []
elements_to_f() Show source
```# 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```

Deprecated.

Use `map(&:to_f)`

elements_to_i() Show source
```# 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```

Deprecated.

Use `map(&:to_i)`

elements_to_r() Show source
```# 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```

Deprecated.

Use `map(&:to_r)`

empty?() Show source
```# File lib/matrix.rb, line 848
def empty?
column_count == 0 || row_count == 0
end```

Returns `true` if this is an empty matrix, i.e. if the number of rows or the number of columns is 0.

entrywise_product(m)
eql?(other) Show source
```# 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```
Alias for: index
first_minor(row, column) Show source
```# 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```

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
```
freeze() Show source
```# File lib/matrix.rb, line 534
def freeze
@rows.each(&:freeze).freeze

super
end```
Calls superclass method `Object#freeze`
```# File lib/matrix.rb, line 1167
combine(m){|a, b| a * b}
end```

```Matrix[[1,2], [3,4]].hadamard_product(Matrix[[1,2], [3,2]])
#  => 1  4
#     9  8
```
Also aliased as: entrywise_product
hash() Show source
```# File lib/matrix.rb, line 1044
def hash
@rows.hash
end```

Returns a hash-code for the matrix.

hermitian?() Show source
```# 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```

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

hstack(*matrices) Show source
```# File lib/matrix.rb, line 1412
def hstack(*matrices)
self.class.hstack(self, *matrices)
end```

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]]
```
imag()
Alias for: imaginary
imaginary() Show source
```# File lib/matrix.rb, line 1579
def imaginary
collect(&:imaginary)
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
```
Also aliased as: imag
index(value, selector = :all) → [row, column] Show source
index(selector = :all){ block } → [row, column]
index(selector = :all) → an_enumerator
```# 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
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```

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]
```
Also aliased as: find_index
inspect() Show source
```# File lib/matrix.rb, line 1704
def inspect
if empty?
"#{self.class}.empty(#{row_count}, #{column_count})"
else
"#{self.class}#{@rows.inspect}"
end
end```

Overrides `Object#inspect`

inv()
Alias for: inverse
inverse() Show source
```# File lib/matrix.rb, line 1178
def inverse
raise ErrDimensionMismatch unless square?
self.class.I(row_count).send(:inverse_from, self)
end```

Returns the inverse of the matrix.

```Matrix[[-1, -1], [0, -1]].inverse
#  => -1  1
#      0 -1
```
Also aliased as: inv
laplace_expansion(row: nil, column: nil) Show source
```# 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```

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]
```
Also aliased as: cofactor_expansion
lower_triangular?() Show source
```# File lib/matrix.rb, line 866
def lower_triangular?
each(:strict_upper).all?(&:zero?)
end```

Returns `true` if this is a lower triangular matrix.

lup() Show source
```# File lib/matrix.rb, line 1536
def lup
LUPDecomposition.new(self)
end```

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)]
```
Also aliased as: lup_decomposition
lup_decomposition()
Alias for: lup
map(which = :all)
Alias for: collect
map!(which = :all)
Alias for: collect!
minor(*param) Show source
```# 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```

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.

normal?() Show source
```# 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```

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

orthogonal?() Show source
```# 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```

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

permutation?() Show source
```# 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```

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

rank() Show source
```# File lib/matrix.rb, line 1425
def rank
# We currently use Bareiss' multistep integer-preserving gaussian elimination
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```

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
```
rank_e() Show source
```# File lib/matrix.rb, line 1456
def rank_e
warn "Matrix#rank_e is deprecated; use #rank", uplevel: 1
rank
end```

deprecated; use `Matrix#rank`

real() Show source
```# File lib/matrix.rb, line 1593
def real
collect(&:real)
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
```
real?() Show source
```# File lib/matrix.rb, line 932
def real?
all?(&:real?)
end```

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

rect() Show source
```# File lib/matrix.rb, line 1603
def rect
[real, imag]
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
```
Also aliased as: rectangular
rectangular()
Alias for: rect
regular?() Show source
```# File lib/matrix.rb, line 939
def regular?
not singular?
end```

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

round(ndigits=0) Show source
```# File lib/matrix.rb, line 1464
def round(ndigits=0)
map{|e| e.round(ndigits)}
end```

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

row(i) { |e| ... } Show source
```# 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```

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.

row_count() Show source
```# File lib/matrix.rb, line 448
def row_count
@rows.size
end```

Returns the number of rows.

Also aliased as: row_size
row_size()
Alias for: row_count
row_vectors() Show source
```# File lib/matrix.rb, line 1631
def row_vectors
Array.new(row_count) {|i|
row(i)
}
end```

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

singular?() Show source
```# File lib/matrix.rb, line 946
def singular?
determinant == 0
end```

Returns `true` if this is a singular matrix.

skew_symmetric?()
Alias for: antisymmetric?
square?() Show source
```# File lib/matrix.rb, line 953
def square?
column_count == row_count
end```

Returns `true` if this is a square matrix.

symmetric?() Show source
```# 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```

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

t()
Alias for: transpose
to_a() Show source
```# File lib/matrix.rb, line 1656
def to_a
@rows.collect(&:dup)
end```

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

to_matrix() Show source
```# File lib/matrix.rb, line 1649
def to_matrix
self
end```

Explicit conversion to a `Matrix`. Returns self

to_s() Show source
```# 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```

Overrides `Object#to_s`

tr()
Alias for: trace
trace() Show source
```# 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```

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

```Matrix[[7,6], [3,9]].trace
#  => 16
```
Also aliased as: tr
transpose() Show source
```# 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```

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
```
Also aliased as: t
unitary?() Show source
```# 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```

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

upper_triangular?() Show source
```# File lib/matrix.rb, line 1003
def upper_triangular?
each(:strict_lower).all?(&:zero?)
end```

Returns `true` if this is an upper triangular matrix.

vstack(*matrices) Show source
```# File lib/matrix.rb, line 1505
def vstack(*matrices)
self.class.vstack(self, *matrices)
end```

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]]
```
zero?() Show source
```# File lib/matrix.rb, line 1010
def zero?
all?(&:zero?)
end```

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

### Protected Instance Methods

power_int(exp) Show source
```# File lib/matrix.rb, line 1257
def power_int(exp)
# assumes `exp` is an Integer > 0
#
# Previous algorithm:
#   build M**2, M**4 = (M**2)**2, M**8, ... and multiplying those you need
#   e.g. M**0b1011 = M**11 = M * M**2 * M**8
#                              ^  ^
#   (highlighted the 2 out of 5 multiplications involving `M * x`)
#
# Current algorithm has same number of multiplications but with lower exponents:
#    M**11 = M * (M * M**4)**2
#              ^    ^  ^
#   (highlighted the 3 out of 5 multiplications involving `M * x`)
#
# This should be faster for all (non nil-potent) matrices.
case
when exp == 1
self
when exp.odd?
self * power_int(exp - 1)
else
sqrt = power_int(exp / 2)
sqrt * sqrt
end
end```

### Private Instance Methods

check_int(val, direction) Show source
```# File lib/matrix.rb, line 376
def check_int(val, direction)
count = direction == :row ? row_count : column_count
CoercionHelper.check_int(val, count, direction)
end```
check_range(val, direction) Show source
```# File lib/matrix.rb, line 370
def check_range(val, direction)
return unless val.is_a?(Range)
count = direction == :row ? row_count : column_count
CoercionHelper.check_range(val, count, direction)
end```

Returns range or nil

determinant_bareiss() Show source
```# File lib/matrix.rb, line 1368
def determinant_bareiss
size = row_count
last = size - 1
a = to_a
no_pivot = Proc.new{ return 0 }
sign = +1
pivot = 1
size.times do |k|
previous_pivot = pivot
if (pivot = a[k][k]) == 0
switch = (k+1 ... size).find(no_pivot) {|row|
a[row][k] != 0
}
a[switch], a[k] = a[k], a[switch]
pivot = a[k][k]
sign = -sign
end
(k+1).upto(last) do |i|
ai = a[i]
(k+1).upto(last) do |j|
ai[j] =  (pivot * ai[j] - ai[k] * a[k][j]) / previous_pivot
end
end
end
sign * pivot
end```

Private. Use `Matrix#determinant`

Returns the determinant of the matrix, using Bareiss' multistep integer-preserving gaussian elimination. It has the same computational cost order O(n^3) as standard Gaussian elimination. Intermediate results are fraction free and of lower complexity. A matrix of Integers will have thus intermediate results that are also Integers, with smaller bignums (if any), while a matrix of `Float` will usually have intermediate results with better precision.

initialize_copy(m) Show source
```# File lib/matrix.rb, line 1036
def initialize_copy(m)
super
@rows = @rows.map(&:dup) unless frozen?
end```

Called for dup & clone.

Calls superclass method
set_col_range(row, col_range, value) Show source
```# File lib/matrix.rb, line 432
def set_col_range(row, col_range, value)
value = if value.is_a?(Vector)
value.to_a
elsif value.is_a?(Matrix)
raise ErrDimensionMismatch unless value.row_count == 1
value.row(0).to_a
else
Array.new(col_range.size, value)
end
raise ErrDimensionMismatch unless col_range.size == value.size
@rows[row][col_range] = value
end```
set_column_vector(row_range, col, value) Show source
```# File lib/matrix.rb, line 425
def set_column_vector(row_range, col, value)
value.each_with_index do |e, index|
r = row_range.begin + index
@rows[r][col] = e
end
end```
Alias for: []=
Alias for: []=
set_row_and_col_range(row_range, col_range, value) Show source
```# File lib/matrix.rb, line 387
def set_row_and_col_range(row_range, col_range, value)
if value.is_a?(Matrix)
if row_range.size != value.row_count || col_range.size != value.column_count
raise ErrDimensionMismatch, [
'Expected a Matrix of dimensions',
"#{row_range.size}x#{col_range.size}",
'got',
"#{value.row_count}x#{value.column_count}",
].join(' ')
end
source = value.instance_variable_get :@rows
row_range.each_with_index do |row, i|
@rows[row][col_range] = source[i]
end
elsif value.is_a?(Vector)
raise ErrDimensionMismatch, 'Expected a Matrix or a value, got a Vector'
else
value_to_set = Array.new(col_range.size, value)
row_range.each do |i|
@rows[i][col_range] = value_to_set
end
end
end```
set_row_range(row_range, col, value) Show source
```# File lib/matrix.rb, line 411
def set_row_range(row_range, col, value)
if value.is_a?(Vector)
raise ErrDimensionMismatch unless row_range.size == value.size
set_column_vector(row_range, col, value)
elsif value.is_a?(Matrix)
raise ErrDimensionMismatch unless value.column_count == 1
value = value.column(0)
raise ErrDimensionMismatch unless row_range.size == value.size
set_column_vector(row_range, col, value)
else
@rows[row_range].each{|e| e[col] = value }
end
end```
set_value(row, col, value) Show source
```# File lib/matrix.rb, line 381
def set_value(row, col, value)
raise ErrDimensionMismatch, "Expected a a value, got a #{value.class}" if value.respond_to?(:to_matrix)

@rows[row][col] = value
end```

Ruby Core © 1993–2020 Yukihiro Matsumoto