[Molby Document Home] [Contents]

Class: | LAMatrix
Parent: | Object

### Description

The class LAMatrix represents a matrix with methods implementing linear algebra.

#### Note about the Order of Indices

LAMatrix methods always handles indices in "column, row" order. This is opposite from the mathematical convention, but consistent with representation of multidimensional array. Be careful when you write code to represent mathematical transformation by LAMatrix.

For example, when `a = LAMatrix.new(1,3)` and `b = LAMatrix.new(3,5)`, `a * b` causes exception because the dimensions do not match (you are trying to multiply two matrices of size (3,1) and (5,3)). `b * a` goes without error to give a row vector (which has the same dimension with `LAMatrix.new(1,5)`).

#### Relationship between LAMatrix, Vector3D and Transform

In Molby, Vector3D and Transform class also represents matrix-like objects. For convenience, these classes can be used interconvertibly.

- An LAMatrix object can be converted to a Vector3D object, when the former is either a (n,1) or (1,n) matrix and n >= 3 (see Vector3D.new and Vector3D.[]).
- An LAMatrix object can be converted to a Transform object, when the former has row dimension >= 3 and column dimension >= 4 (see Transform.new and Transform.[]).
- A Vector3D or Transform object can be converted to LAMatrix.[]. Note that Vector3D[x, y, z] is converted to LAMatrix[[x, y, z, 1.0]], and Transform[[a11, a21, a31], ..., [a14, a24, a34]] is converted to LAMatrix[[a11, a21, a31, 0.0], ..., [a14, a24, a34, 1.0]].
- When Vector3D or Transform object is used as an argument of LAMatrix method, it can also be converted to a (3, 1) vector or a (3, 3) matrix.

### Public Class methods

LAMatrix[f1, f2, ..., fn] → (new) LAMatrix
LAMatrix[a1, a2, ..., an] → (new) LAMatrix
LAMatrix[obj] → (new) LAMatrix

Create a new matrix. In the first form, f1...fn must be numbers, and a (n, 1) matrix (a column vector) is created. In the second form, a1...an must be array-like objects, and a (m, n) matrix (m is the maximum dimension of a1...an) is created. In the third form, obj must be either an array, a Vector3D, a Transform, or an LAMatrix.

diagonal(Array) → (new) LAMatrix
diagonal(size, element) → (new) LAMatrix

Create a diagonal matrix. In the first form, the diagonal elements are taken from the array argument. In the second form, a diagonal matrix of the specified size with all the diagonal component `element`.

from_columns(c1, ...) → (new) LAMatrix

Create a new LAMatrix built from column vectors. This is equivalent to `LAMatrix.new([c1, ...])`.

from_rows(r1, ...) → (new) LAMatrix

Create a new LAMatrix built from row vectors.

identity(size) → (new) LAMatrix

Create an identity transform of size `size`.

multiply(arg1, arg2, ...) → (new) LAMatrix

Multiply the arguments. The arguments are interpreted as in LAMatrix.multiply!.

new(column, row) → (new) LAMatrix
new(array) → (new) LAMatrix
new(matrix) → (new) LAMatrix

Create a new LAMatrix object.

- In the first form, a zero LAMatrix of given size is returned. Note the order of the arguments; they are opposite to the mathematical convention.
- In the second form, the array must be either of an array (the column vector), or an array of arrays (a set of column vectors).
- In the third form, a new transform is built from a matrix. The argument `matrix` must respond to a method call `matrix[col, row]`, `row_size` and `column_size`.

zero(column[, row]) → (new) LAMatrix

Create a zero matrix of the specified size.

### Public Instance methods

self + val → (new) LAMatrix

Perform the matrix addition. Both arguments must have the same dimensions.

self - val → (new) LAMatrix

Perform the matrix subtraction. Both arguments must have the same dimensions.

self * numeric → (new) LAMatrix
self * matrix → (new) LAMatrix

Perform the matrix multiplication. In the first form, a new matrix with scaled elements is returned. In the second, the multiple of the two matrices is returned.

self / numeric → (new) LAMatrix
self / matrix → (new) LAMatrix

Perform the matrix multiplication. In the first form, a new matrix with scaled elements is returned. In the second, `self * matrix.inverse` is returned.

self == val → bool

Returns `true` if and only if the dimensions are the same and all the corresponding elements of both arguments are equal. Usual caution about the comparison of floating-point numbers should be paid.

self[i, j] → Float

Get the element (`i`,`j`) of the matrix, i.e. column `i`, row `j`. Be careful about the order of the arguments. It follows convention of multi-dimensional arrays rather than mathematical notation.

self[i, j] = val

Set the element (`i`,`j`) of the matrix, i.e. column `i`, row `j`. Be careful about the order of the arguments. It follows convention of multi-dimensional arrays rather than mathematical notation.

add!(val) → self

Add a value to self.

column(index) → (new) LAMatrix

Returns the index-th column as a (n,1) matrix.

column_size → Integer

Returns the column size.

determinant → Float

Returns the determinant of the matrix.

eigenvalues → [eigenvalues, eigenvectors]

Calculate the eigenvalues and eigenvectors. The matrix must be symmetric. The eigenvalues are given as a column matrix, and the eigenvectors are given as an orthogonal matrix (whose column vectors are the eigenvectors).

fnorm → Float
fnorm2 → Float

Calculate the Frobenius norm (the Hilbert–Schmidt norm). `fnorm2` returns the square of the norm.

inspect → String

Convert a matrix to a string like "LAMatrix[[a11,a21,...],[a12,a22,...],...,[a1N,a2N,...]]".

inverse → (new) LAMatrix
inverse! → self

Calculate the inverse matrix as a new object. If the matrix is not regular, an exception is raised. `inverse!` changes the object destructively and returns self.

multiply!(arg1, arg2, ...) → self

Multiply the arguments to self.

- If `argN` is a string "t", then the subsequent matrix is transposed (the object is not modified; it is just transposed during calculation).
- If `argN` is a string "i", then the subsequent matrix is inverted (the object is not modified).
- The "t" and "i" can be combined as "ti" or "it".
- If `argN` is a number, then scalar multiplication is performed.
- Otherwise, `argN` must be a matrix, which has the same row-size as the column-size of the last result.

row(index) → (new) LAMatrix

Returns the index-th row vector as a (1, N) matrix.

row_size → Integer

Returns the row size.

sub!(val) → self

Subtract a value from self.

submatrix(column_pos, row_pos, column_size, row_size) → (new) LAMatrix

Extract a submatrix beginning from `(row_pos, column_pos)` and size `(row_size, column_size)`. If `row_size` or `column_size` are given as -1, then all the elements to the end of the row/column are used. Note the order of the arguments; they are opposite to the mathematical convention.

svd → [left_matrix, singular_values, right_matrix]

Perform the singular value decomposition (SVD) of the given matrix. Decompose the given `(m,n)` matrix to a product of three matrices, `U`, `S`, `V`. `U` is a `(m,m)` orthogonal matrix, `S` is a `(m,n)` matrix which is zero except for `min(m,n)` diagonal elements, and `V` is a `(n,n)` orthogonal matrix. (Usually SVD is defined as `M = U*S*transpose(V)`, but this methods returns `transpose(V)` rather than `V`.) The singular_values is a `min(m,n)` dimension column vector.

to_a → Array

Convert a transform to an array of arrays representing the column vectors.

to_s → String

Alias for inspect

trace → Float

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

transpose → (new) LAMatrix
transpose! → self

Calculate the transpose matrix. `transpose!` changes the object destructively and returns self.