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 jth 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 Aij of matrix A, that is the element in the ith row and jth 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 ith 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 AB. 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

  • 3x + 2yz = 1
  • 2x − 2y + 4z = −2
  • x + ½yz = 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).