## Class: Matrix

Sylvester version: 0.1.0 onwards

Class methods:
`create`

,
`Diagonal`

,
`I`

,
`Random`

,
`Rotation`

,
`RotationX`

,
`RotationY`

,
`RotationZ`

,
`Zero`

Instance methods:
`add`

,
`augment`

,
`canMultiplyFromLeft`

,
`col`

,
`cols`

,
`det`

,
`determinant`

,
`diagonal`

,
`dimensions`

,
`dup`

,
`e`

,
`eql`

,
`indexOf`

,
`inspect`

,
`inv`

,
`inverse`

,
`isSameSizeAs`

,
`isSingular`

,
`isSquare`

,
`map`

,
`max`

,
`minor`

,
`multiply`

,
`rank`

,
`rk`

,
`round`

,
`row`

,
`rows`

,
`setElements`

,
`snapTo`

,
`subtract`

,
`toRightTriangular`

,
`toUpperTriangular`

,
`tr`

,
`trace`

,
`transpose`

,
`x`

Instance variables:

`elements`

– a nested array containing the matrix’s elements

### Overview

The `Matrix`

class is designed to model real matrices in any
number of dimensions. All the elements in a matrix must be real numbers.

### Class methods

### Matrix.create(elements) 0.1.0

Creates and returns a new `Matrix`

instance from the array
`elements`

. `elements`

should be a nested array: the
top level array is the rows, and each row is an array of elements. This
means you write out a matrix in code in the same orientation you would on
paper.

```
var M = $M([
[8,3,9],
[2,0,7],
[1,9,3]
]);
```

Every row must have the same number of elements, otherwise the method will
return `null`

.

This method is aliased as `$M`

.

### Matrix.Diagonal(elements) 0.1.0

Returns a square matrix whose leading-diagonal elements are the values in
the array `elements`

, and whose off-diagonal elements are zero.

```
var D = Matrix.Diagonal([4,3,7,1]);
// D is the matrix
// 4 0 0 0
// 0 3 0 0
// 0 0 7 0
// 0 0 0 1
```

### Matrix.I(n) 0.1.0

Returns the `n`

×`n`

identity matrix.

### Matrix.Random(n, m) 0.1.0

Returns a matrix with `n`

rows and `m`

columns, all
the elements of which are random numbers between 0 and 1.

### Matrix.Rotation(angle [, axis]) 0.1.0

If called with only one argument, returns the 2×2 matrix for an
anticlockwise rotation of `angle`

radians about the origin. That
is, vectors are rotated anticlockwise with respect to the coordinate system,
not the other way round.

If called with two arguments, returns the 3×3 matrix for a
right-handed rotation of `angle`

radians about the axis given by
the 3-vector `axis`

, keeping the origin fixed.

### Matrix.RotationX(angle), Matrix.RotationY(angle), Matrix.RotationZ(angle) 0.1.0

Each of these return the 3×3 matrix representing a right-handed
rotation of points in 3-dimensional space relative to the coordinate system
through an angle of `angle`

radians about the x, y and z axes respectively. They are used as a foundation for
the more general `Matrix.Rotation`

.

### Matrix.Zero(n, m) 0.1.0

Returns a matrix with `n`

rows and `m`

columns, all
the elements of which are zero.

### Instance methods

### add(matrix) 0.1.0

Returns the matrix sum of the receiver and `matrix`

. Thus,
`A.add(B)`

is equivalent to **A** +
**B**. Returns `null`

if the matrices are different
sizes.

### augment(matrix) 0.1.0

Returns the result of augmenting the receiver with `matrix`

,
that is, appending `matrix`

to the right hand side of the
receiver. Both matrices must have the same number of rows for this to
work.

```
var M = $M([
[8,3,0],
[4,4,2],
[9,1,5]
]).augment(Matrix.I(3));
// M is the matrix
// 8 3 0 1 0 0
// 4 4 2 0 1 0
// 9 1 5 0 0 1
```

`matrix`

can also be a
`Vector`

, as long as it has the
same number of elements as the receiver has rows. It will be appended to the
receiver as an extra column on the right hand side.

### canMultiplyFromLeft(matrix) 0.1.0

`A.canMultiplyFromLeft(B)`

returns `true`

iff
**AB** is a mathematically valid expression. This is the
case iff **A** has the same number of columns as **B** has rows. `matrix`

can also be a
`Vector`

, as long as it has the
same number of elements as the receiver has rows.

### col(j) 0.1.0

Returns the `j`

th column of the receiver as a
`Vector`

.

### cols() 0.1.0

Returns the number of columns the receiver has.

### det() 0.1.0

Alias for determinant.

### determinant() 0.1.0

If the receiver is square, returns its determinant, otherwise returns
`null`

. Note that if the receiver is singular, this method will
return exactly zero, with no rounding errors.

### diagonal() 0.1.0

If the receiver is square, returns its leading-diagonal elements as a
`Vector`

. Otherwise, returns
`null`

.

### dimensions() 0.1.0

Returns an object containing the receiver’s dimensions.

```
var dims = Matrix.Zero(4,3).dimensions();
// dims is {rows: 4, cols: 3}
```

### dup() 0.1.0

Returns a copy of the receiver.

### e(i, j) 0.1.0

`A.e(i,j)`

returns the element *A _{ij}* of matrix

**A**, that is the element in the

`i`

th row and `j`

th column.
Indexes begin at 1, in agreement with mathematical notation.### eql(matrix) 0.1.0

Returns `true`

iff `matrix`

has all its elements
equal to those of the receiver.

### indexOf(x) 0.1.0

Reads the receiver’s elements row by row from left to right and
returns an object containing the indeces of the first exact match. Returns
`null`

if no match is found.

```
var foo = $M([
[0,9,4],
[9,5,8],
[1,5,3]
]).indexOf(9);
// foo is {row: 1, col: 2}
```

### inspect() 0.1.0

Returns a string representation of the receiver, useful for debugging.

```
alert(Matrix.I(4).inspect());
// alerts:
// [1, 0, 0, 0]
// [0, 1, 0, 0]
// [0, 0, 1, 0]
// [0, 0, 0, 1]
```

### inv() 0.1.0

Alias for inverse.

### inverse() 0.1.0

Returns the matrix inverse of the receiver, if one exists. If the matrix is
singular or not square, then `null`

is returned. The inverse is
computed using
Gauss-Jordan
elimination.

### isSameSizeAs(matrix) 0.1.0

Returns `true`

iff `matrix`

has the same number of
rows and columns as the receiver. `matrix`

can also be a
`Vector`

, as long as it has the
same number of elements as the receiver has rows.

### isSingular() 0.1.0

Returns `true`

iff the receiver is square and has zero
determinant.

### isSquare() 0.1.0

Returns `true`

iff the receiver is square.

### map(iterator) 0.1.0

Maps the receiver to another matrix by calling `iterator`

on
each element of the receiver in turn. `iterator`

receives the row
and column index of each element as second and third arguments. Some
examples:

```
// Square all the elements of a matrix:
var A_sq = A.map(function(x) { return x * x; });
// Determine whether a matrix is symmetric:
var is_sym = (A.map(
function(x, i, j) { return (A.e(i,j) == A.e(j,i)) ? 1 : 0; }
).indexOf(0) === null);
```

### max() 0.1.0

Returns the value of the element of the receiver with the largest absolute value.

### minor(i, j, n, m) 0.1.0

This method returns a matrix formed from a subset of the receiver’s
elements. It selects elements beginning at row `i`

and column
`j`

of the receiver, and returns a matrix with `n`

rows and `m`

columns. The selection wraps to the other side of
the receiver if `n`

or `m`

is large enough. This is
best illustrated by example:

```
var M = $M([
[9,2,6,5],
[0,1,7,4],
[4,2,6,7],
[1,8,5,3]
]);
var A = M.minor(2,1,2,3);
// 0 1 7
// 4 2 6
var B = M.minor(1,4,3,3);
// 5 9 2
// 4 0 1
// 7 4 2
// Augment M with itself
var C = M.minor(1,1,4,8);
// 9 2 6 5 9 2 6 5
// 0 1 7 4 0 1 7 4
// 4 2 6 7 4 2 6 7
// 1 8 5 3 1 8 5 3
```

### multiply(object) 0.1.0

If `object`

is a matrix, then this method returns the result of
multiplying the receiver by `object`

in that order:
`A.multiply(B)`

means **AB**. If
`object`

is a `Vector`

,
then it is converted to a column matrix, multiplied by the receiver, and the
result is returned as a `Vector`

(this saves you having to call `col(1)`

on the result). If
`object`

is a scalar, then the method returns a copy of the
receiver with all its elements multiplied by `object`

.

This method is aliased as `x`

.

### rank() 0.1.0

Returns the receiver’s rank, which is the number of linearly independent rows/columns it contains.

### rk() 0.1.0

Alias for `rank`

.

### round() 0.1.0

Returns a copy of the receiver with all its elements rounded to the nearest integer.

### row(i) 0.1.0

Returns the `i`

th row of the receiver as a
`Vector`

.

### rows() 0.1.0

Returns the number of rows the receiver has.

### setElements(elements) 0.1.0

Sets the receiver’s elements from the array `elements`

.
The element array’ top-level elements should be the rows, and each row
is an array of values reading from left to right across the columns. See
`Matrix.create`

.

### snapTo(x) 0.1.0

Returns a copy of the receiver in which any elements that differ from
`x`

by less than the value of `Sylvester.precision`

are set exactly equal to `x`

.

### subtract(matrix) 0.1.0

Returns the result of subtracting `matrix`

from the receiver.
Thus, `A.subtract(B)`

is equivalent to **A**
− **B**. Returns `null`

if the matrices are
different sizes.

### toRightTriangular() 0.1.0

Returns a copy of the receiver converted to right triangular form. The conversion is done only by adding multiples of rows to other rows, so the determinant (if the matrix is square) is unchanged. This method can be used on non-square matrices, which lets you use it to solve sets of simultaneous equations. For example: solving the system of linear equations

- 3
*x*+ 2*y*−*z*= 1 - 2
*x*− 2*y*+ 4*z*= −2 - −
*x*+ ½*y*−*z*= 0

would be written as:

```
var equations = $M([
[ 3, 2, -1, 1],
[ 2, -2, 4, -2],
[-1, 0.5, -1, 0]
]);
var eqns = equations.toRightTriangular();
var sol_z = eqns.e(3,4) / eqns.e(3,3);
var sol_y = (eqns.e(2,4) - eqns.e(2,3)*sol_z) / eqns.e(2,2);
var sol_x = (eqns.e(1,4) - eqns.e(1,3)*sol_z - eqns.e(1,2)*sol_y) / eqns.e(1,1);
```

### toUpperTriangular() 0.1.0

Alias for `toRightTriangular`

.

### tr() 0.1.0

Alias for `trace`

.

### trace() 0.1.0

Returns the trace for square matrices, which is the sum of their leading-diagonal elements.

### transpose() 0.1.0

Returns the matrix transpose of the receiver.

### x(k) 0.1.0

Alias for `multiply(k)`

.