Axiom — Matrix Module

The @matrix module contains a single class @matrix, for doing matrix math. A matrix is a 2D collection of numbers with a variety of practical applications: representing systems of linear equations, representing the parameters of a neural network, and projecting 3D coordinates onto 2D space for computer graphics. Note that in matrix notation, rows come before columns. So a RxC matrix has R rows and C columns, and the position (r,c) is row r and column c.

Using the @matrix class has several advantages over using arrays of numbers. First, common matrix operations are implemented. Second, the matrix class is more efficient for several reasons: The matrix class operates on 32-bit floating point numbers instead of 64-bit numbers/arbitrary variants. The matrix class is copy-on-modify, meaning that copying or slicing a matrix does not copy the underlying data until it is modified. Lastly, the matrix class will use the GPU to accelerate large matrix multiplications. This requires GLSL, which is supported by default on Windows, MacOS, and Android, and is supported on Linux if X11 is installed.

Methods

:new(array) #
:new(string)
:new(rows,cols,fill)

Create a new matrix.

Parameters

array — a 1D or 2D array of numbers
string — a string of the form "[ n n n, n n n, ...]" where the n's are numbers, commas separate rows, and whitespace separates columns
rows — the number of rows
cols — the number of columns
fill — the number used to fill this matrix (optional, default is 0)

Return

a new matrix

Notes

If array is a 1D array, a matrix of size Rx1 is created, where R is the length of the array. If array is a 2D array, a matrix of size RxC is created, where R is the length of the array, and C is the length of each sub-array. It is assumed that all sub-arrays have the same length as the first sub-array.

If no parameters are specified, null is returned.

Example

#create the same matrix two different ways
m = matrix('[ 1 2 3, 4 5 6, 7 8 9]')
m = matrix([[1,2,3],[4,5,6],[7,8,9]])

:rows() #

Get the number of rows in this matrix.

Return

the number of rows in this matrix

:cols() #

Get the number of columns in this matrix.

Return

the number of columns in this matrix

:size() #

Get the number of elements (rows*cols) in this matrix.

Return

the number of elements in this matrix

:shape() #

Get the shape of this matrix.

Return

an array like [rows,cols]

:string(newlines) #

Convert this matrix into a string.

Parameters

newlines — whether or not to separate rows with newlines (optional, default is false)

Return

a string like "[ n n n, n n n, ...]" where the n's are numbers, commas separate rows, and whitespace separates columns

Notes

This is the same format taken by constructor.

:array() #

Convert this matrix into an array.

Return

a 1D or 2D array of numbers

Notes

If this is an RxC matrix, a 2D array is returned with length R, where each sub-array has length C. If this is an Rx1 matrix, a 1D array is returned with length R. This is the same format taken by constructor.

:slice(i,rows,j,cols) #

Slice this matrix.

Parameters

i — the start row
rows — the number of rows to include
j — the start column
cols — the number of columns to include

Return

a new matrix corresponding to this matrix sliced accordingly

Notes

Either rows or cols can be 0 to include all rows after i or j, respectively.

Slicing a matrix is efficient because the underlying data is not copied until it is modified.

Example

m = matrix('[ 1 2 3, 4 5 6, 7 8 9]')
print m.slice(1,2,1,2) #[ 5 6,  8 9 ]

:row(i) #

Get the ith row.

Parameters

i — the row index

Return

a new matrix corresponding to the ith row

Notes

Uses :slice() under the hood.

Example

m = matrix('[ 1 2 3, 4 5 6, 7 8 9]')
print m.row(1) #[ 4 5 6 ]

:col(j) #

Get the jth column.

Parameters

j — the column index

Return

a new matrix corresponding to the jth column

Notes

Uses :slice() under the hood.

Example

m = matrix('[ 1 2 3, 4 5 6, 7 8 9]')
print m.col(1) #[ 2,  5,  8 ]

:get(i,j) #

Get the value at row i column j.

Parameters

i — the row index
j — the column index

Return

a number corresponding to the value at i,j

:set(i,j,f) #

Set the value at row i column j to value f.

Parameters

i — the row index
j — the column index
f — the value

:add(other) #

Add this matrix to other.

Parameters

other — another matrix or a scalar

Return

a new matrix corresponding to the added matrices or every element in this matrix plus the scalar

Notes

Matrices of different sizes are processed in the following way:

If this dimension is smaller, other is truncated.
If this other is smaller, it is repeated to match size of this.

:sub(other) #

Subtract other from this matrix.

Parameters

other — another matrix or a scalar

Return

a new matrix corresponding to the subtracted matrices or every element in this matrix minus the scalar

Notes

Matrices of different sizes are processed in the following way:

If this dimension is smaller, other is truncated.
If this other is smaller, it is repeated to match size of this.

:dot(other) #

Dot product this with other.

Parameters

other — another matrix

Return

a new matrix corresponding to the dot product of the matrices

Notes

Matrices of different sizes are processed in the following way:

If this dimension is smaller, other is truncated.
If this other is smaller, it is repeated to match size of this.

To multiply by a scalar, use :mul().

:div(other) #

Divide the elements of this with the elements of other.

Parameters

other — another matrix or a scalar

Return

a new matrix corresponding to the divided matrices or every element in this matrix divided by the scalar

Notes

Matrices of different sizes are processed in the following way:

If this dimension is smaller, other is truncated.
If this other is smaller, it is repeated to match size of this.

:fill(f) #

Fill this matrix with f.

Parameters

f — the number with which to fill this matrix

Return

a new matrix corresponding to this matrix where all the elements are f

:transpose() #

Transpose this matrix.

Return

a new matrix corresponding to the transpose (flipped along diagonal) of this matrix

:mul(other) #

Multiply this matrix with other.

Parameters

other — another matrix or a scalar

Return

a new matrix corresponding to the multiplied matrices or every element in this matrix multiplied by the scalar

Notes

It is an error to multiply two matrices where this.cols() != other.rows(). See Matrix multiplication on Wikipedia for details.

This will call :mul_cpu() or :mul_gpu() under the hood depending on the size of the matrices. In general, it is more efficient to multiply large matrices on the GPU and small matrices on the CPU.

:mul_cpu(other) #

Explicitly multiply this matrix with other on the CPU.

Parameters

other — another matrix

Return

a new matrix corresponding to the multiplied matrices

Notes

Can be used for benchmarks against :mul_gpu().

:mul_gpu(other) #

Explicitly multiply this matrix with other on the GPU.

Parameters

other — another matrix

Return

a new matrix corresponding to the multiplied matrices

Notes

Can be used for benchmarks against :mul_cpu().

Example

if matrix.gpu(true)
	p = matrix.random(1000,1000)
	q = matrix.random(1000,1000)

	t = os.ticks()
	s = p.mul_gpu(q)
	print 'mul_gpu():',(os.ticks()-t),'ms'

	t = os.ticks()
	r = p.mul_cpu(q)
	print 'mul_cpu():',(os.ticks()-t),'ms'

	print 'verification:',r.eq(s)

else
	print 'GPU not supported!'

##
on Intel Macbook:
GL_VENDOR    = Intel Inc.
GL_RENDERER  = Intel(R) UHD Graphics 617
GL_VERSION   = 2.1 INTEL-12.10.22
GLSL_VERSION = 1.20
mul_gpu(): 437 ms
mul_cpu(): 1308 ms
verification: true
##

:eq(other,tolerance) #

description

Parameters

other — another matrix
tolerance — the value absolute value from 0 under which a value is rounded to 0 (optional, default is 0.0005)

Return

true if the matrices are equal (the differences between each element are within tolerance)

Notes

Floating-point mathematics is not perfectly precise, and so you may need to adjust tolerance to suit your needs.

:solve(tolerance) #

Solve the system of linear equations represented by this matrix by using Gauss-Jordan elimination to turn this matrix into reduced row-echelon form.

Parameters

tolerance — the value absolute value from 0 under which a value is rounded to 0 (optional, default is 0.0005)

Return

a new matrix corresponding to this matrix in reduced row-echelon form

Notes

Floating-point mathematics is not perfectly precise, and so you may need to adjust tolerance to suit your needs.

:inverse(tolerance) #

Find the inverse of this matrix, if any.

Parameters

tolerance — the value absolute value from 0 under which a value is rounded to 0 (optional, default is 0.0005)

Return

the inverse of this matrix if found, otherwise null

Notes

Floating-point mathematics is not perfectly precise, and so you may need to adjust tolerance to suit your needs.

:append(other) #

Append other to the bottom of this matrix.

Parameters

other — another matrix

Return

a new matrix corresponding to this matrix with other appended to the bottom

:adjoin(other) #

Adjoin other to the right side of this matrix.

Parameters

other — another matrix

Return

a new matrix corresponding to this matrix with other adjoined to the right

:standardize() #

Standardize the elements of this matrix such that for each column, the mean is 0 and the standard deviation is 1.

Return

a new matrix corresponding to this matrix where all the elements are standardized by column

:normalize() #

Normalize the elements of this matrix such that all values are within range [0,1). This is accomplished by finding the min/max values for each column, and scaling each value f to become (f-min)/(max-min).

Return

a new matrix corresponding to this matrix where all the elements are normalized by column

:log_scale() #

Logarithmically scale all elements of this matrix.

Return

a new matrix corresponding to this matrix where all the elements are logarithmically scaled

Notes

This applies the following function to all elements of the array:

if x>0: ln(1+x)
if x<0: -ln(1-x)
if x==0: x

Compared to simply doing a logarithm of each element, this technique can handle values less than 1.

:apply(fn) #

Apply the function fn to all elements of this matrix.

Parameters

fn — the function to apply

Return

a new matrix where each element x is now fn(x)

Example

:abs(f)
	return f.abs()
m = matrix('[ 1, -1, 2, -2]')
print m.apply(abs)
#[ 1,  1,  2,  2 ]

:sum() #

Sum the values in each column.

Return

a new matrix with 1 row and this.cols() columns, containing the sums of the elements in each column

:cov() #

Get the covariance matrix between columns of this matrix.

Return

a square matrix with side length this.cols(), where element (r,c) is the covariance between this.col(r) and this.col(c) (the diagonal is the variance)

:cor() #

Get the correlation matrix between columns of this matrix.

Return

a square matrix with side length this.cols(), where element (r,c) is the correlation between this.col(r) and this.col(c) (the diagonal is always 1)

:stats(col) #

Get statistics for a certain column.

Parameters

col — the column index

Return

an object containing the statistics for column col; see notes for details

Notes

The returned object has the following fields:

avg — the average (mean) of the column values
dev — the standard deviation (square root of variance) of the column values
var — the variance of the column of values
min — the minimum of the column values
max — the maximum of the column values

Example

print matrix('[1, 2, 3]').stats()
##
{
  "avg" : 2,
  "dev" : 1,
  "var" : 1,
  "min" : 1,
  "max" : 3
}
##

:bias() #

Adjoin a column of 1's to the left side of this matrix.

Return

a new matrix corresponding to a column of 1's adjoined to this matrix

Notes

This is useful for certain mathematical calculations.

:fit(labels,tolerance) #

Fit this matrix to labels, assuming this matrix a matrix of samples, one per row. Specifically, solve the linear equation Xb*W = Y, where Xb is this.bias(), Y is labels, and W is an unknown matrix of weights.

Parameters

labels — a matrix of of labels (labels.rows() should equal this.rows())
tolerance — the value absolute value from 0 under which a value is rounded to 0 (optional, default is 0.0005)

Return

the matrix of weights W, which will have this.cols()+1 rows and labels.cols() columns

Notes

This performs linear regression by linear least squares using the ordinary least squares method. For underdetermined systems, the pseudo-inverse formula is used.

:run(weights) #

Run this matrix using the weights from :fit(), assuming this matrix a matrix of samples, one per row. Specifically, run the linear equation Xb*W = P, where Xb is this.bias(), W is weights, and P is a matrix of predictions.

Parameters

weights — a matrix of weights

Return

the matrix of predictions P, which will have this.rows() rows and weights.col() columns

Notes

If this matrix is the same matrix called with :fit(), then the matrix P is a prediction of the labels Y, and Y-P is the prediction error.

Example

#simple linear regression
x = matrix([ 1, 2, 3, 4])
y = matrix([ 3.1, 4.9, 7.1, 8.9]) #y = 2x+1 with some deviation
w = x.fit(y)
print w #[ 1.1,  1.96 ] (close to [1, 2])
print x.run(w) #[ 3.06,  5.02,  6.98,  8.94 ] (close to y)

:save(path) #

Save this matrix to path in a binary format.

Parameters

path — the file path

Return

true if successful, otherwise false

Notes

The binary format is:

all the elements of this matrix as 32-bit floats
the number of rows in this matrix as a 32-bit integer
the number of columns in this matrix as a 32-bit integer

The binary format is designed to be portable and easy to load in other languages, like C++. The reason the row/column sizes appear at the end of the file is to discourage using them for buffer allocation; doing so would be a security risk (buffer underflow/overflow) when parsing a malformed file. Instead, parsers should first read the elements and then verify that the element count maches the given row/column sizes.

Functions

:load(path) #

Load a matrix from a binary file generated by :save().

Parameters

path — the file path

Return

a new matrix corresponding to the values loaded from the file at path

:gpu(show_info) #

Whether or not a GPU is available.

Parameters

show_info — whether or not to print information about the GPU to stdout (optional, default is false)

Return

true if a GPU is available and supports all the features needed to multiply matrices; otherwise false

Notes

If show_info is true, information about the GPU is printed to stdout, which is useful for debugging GPU support. See example for details.

Example

print matrix.gpu(true)
##
GL_VENDOR    = Intel Inc.
GL_RENDERER  = Intel(R) UHD Graphics 617
GL_VERSION   = 2.1 INTEL-12.10.22
GLSL_VERSION = 1.20
true
##

:vstack(a) #

Vertically stack matrices.

Parameters

a — an array of matrices

Return

a new matrix corresponding to all the matrices stacked vertically

Notes

Every matrix in a should have the same number of columns, otherwise it is an error.

:hstack(a) #

Horizontally stack matrices.

Parameters

a — an array of matrices

Return

a new matrix corresponding to all the matrices stacked horizontally

Notes

Every matrix in a should have the same number of rows, otherwise it is an error.

:identity(size) #

Create an identity matrix.

Parameters

size — the size of the matrix (number of both rows and columns)

Return

a new identity matrix corresponding to size

Notes

An identity matrix identity matrix is just a square matrix where the diagonal is 1's and the rest of the elements are 0's.

:random(rows,cols) #

Create a matrix of random values in range [0,1).

Parameters

rows — the number of rows
cols — the number of columns

Return

a new matrix of random values

:randstd(rows,cols) #

Create a matrix of random values from a standard normal distribution.

Parameters

rows — the number of rows
cols — the number of columns

Return

a new matrix of random values