# matrix v0.3.2 Matrix

*Matrix* is a linear algebra library for manipulating dense matrices. Its
primary design goal is ease of use. It is desirable that the *Matrix* package
interact with standard Elixir language constructs and other packages. The
underlying storage mechanism is, therefore, Elixir lists.

A secondary design consideration is for the module to be reasonably efficient
in terms of both memory usage and computations. Unfortunately there is a
trade off between memory efficiency and computational efficiency. Where these
requirements conflict *Matrix* will use the more computationally efficient
algorithm.

Each matrix is represented as a “list of lists” whereby a 3x4 matrix is represented by a list of three items, with each item a list of 4 values. Constructors are provided for several common matrix configurations including zero filled, one filled, random filled the identity matrix, etc.

## Examples

```
iex> Matrix.new(3, 4)
[[0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]]
iex> Matrix.ident(4)
[[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]
```

# Summary

## Functions

Returns a new matrix whose elements are the sum of the elements of the provided matrices. If the matrices are of differing sizes, the returned matrix will be the size and dimensions of the “overlap” between them. For instance, the sum of a 3x3 matrix with a 2x2 matrix will be 2x2. The sum of a 3x1 matrix with a 1x3 matrix will be 1x1

Compares two matrices as being (approximately) equal. Since floating point
numbers have slightly different representations and accuracies on different
architectures it is generally not a good idea to compare them directly.
Rather numbers are considered equal if they are within an “epsilon” of each
other. *almost_equal* compares all elements of two matrices, returning true
if all elements are within the provided epsilon

Code borrowed from the ExMath library and duplicated here to reduce dependencies. ExMath is copyright © 2015 Ookami Kenrou ookamikenrou@gmail.com

Returns a new square “diagonal” matrix whose elements are zero except for the diagonal. The diagonal elements will be composed of the supplied list

Returns the value of the specified element (row and column) of the given
matrix (x). The row and column indices are zero-based. Returns `default`

if either row or col are out of bounds

Returns a new matrix whose elements are the element-by-element multiply of the elements of the provided matrices. Note that this is not the linear algebra matrix multiply. If the matrices are of differing sizes, the returned matrix will be the size and dimensions of the “overlap” between them. For instance, the element multiply of a 3x3 matrix with a 2x2 matrix will be 2x2, for a 3x1 matrix with a 1x3 matrix will be 1x1

Returns a new “identity” matrix of the specified size. The identity is defined as a square matrix with ones on the diagonal and zeros in all off-diagonal elements. Since the matrix is square only a single size parameter is required

Returns a new matrix which is the (linear algebra) inverse of the supplied matrix. If the supplied matrix is “x” then, by definition,

` x * inv(x) = I`

where I is the identity matrix. This function uses a brute force Gaussian elimination so it is not expected to be terribly fast

Returns the Kronecker tensor product of two matrices A and B. If A is an
MxN and B is PxQ, then the returned matrix is an (M*P)x(N*Q) matrix formed
by taking all possible products between the elements of A and the matrix B

Returns a new matrix which is the linear algebra matrix multiply
of the provided matrices. It is required that the number of columns
of the first matrix (x) be equal to the number of rows of the second
matrix (y). If x is an NxM and y is an MxP, the returned matrix product
xy is NxP. If the number of columns of x does not equal the number of
rows of y an `ArgumentError`

exception is thrown with the message “sizes
incompatible”

Returns a new matrix of the specified size (number of rows and columns). All elements of the matrix are filled with the supplied value “val” (default 0)

Returns a new matrix of the specified size (number of rows and columns). All elements of the matrix are filled with the ones

Returns a new matrix whose elements are identical to the supplied matrix x but with the supplied value appended to the end of each row

Returns a new matrix whose elements are identical to the supplied matrix x but with the supplied value appended to the beginning of each row

Returns a string which is a “pretty” representation of the supplied matrix

Returns a new matrix of the specified size (number of rows and columns). All elements of the matrix are filled with uniformly distributed random numbers between 0 and 1

Returns a new matrix whose elements are the elements of matrix x multiplied by the scale factor “s”

Returns a new matrix of the specified size (number of rows and columns) whose elements are sequential starting at 1 and increasing across the row

Returns a matrix that is a copy of the supplied matrix (x) with the specified element (row and column) set to the specified value (val). The row and column indices are zero-based. Negative indices indicate an offset from the end of the row or column. If an index is out of bounds, the original matrix is returned

Returns the size (dimensions) of the supplied matrix. The return value is a tuple of the dimensions of the matrix as {rows,cols}

Returns a new matrix whose elements are the difference (subtraction) of the elements of the provided matrices. If the matrices are of differing sizes, the returned matrix will be the size and dimensions of the “overlap” between them. For instance, the difference of a 3x3 matrix with a 2x2 matrix will be 2x2. The difference of a 3x1 matrix with a 1x3 matrix will be 1x1

Returns a new matrix whose elements are the transpose of the supplied matrix. The transpose essentially swaps rows for columns - that is, the first row becomes the first column, the second row becomes the second column, etc

Returns a new matrix of the specified size (number of rows and columns). All elements of the matrix are filled with the zeros

# Types

# Functions

Returns a new matrix whose elements are the sum of the elements of the provided matrices. If the matrices are of differing sizes, the returned matrix will be the size and dimensions of the “overlap” between them. For instance, the sum of a 3x3 matrix with a 2x2 matrix will be 2x2. The sum of a 3x1 matrix with a 1x3 matrix will be 1x1.

#### See also

#### Examples

```
iex> Matrix.add( Matrix.ident(3), Matrix.ident(3) )
[[2, 0, 0], [0, 2, 0], [0, 0, 2]]
iex> Matrix.add( Matrix.ones(3,3), Matrix.ones(2,2) )
[[2, 2], [2, 2]]
iex> Matrix.add( Matrix.ones(3,1), Matrix.ones(1,3) )
[[2]]
```

Compares two matrices as being (approximately) equal. Since floating point
numbers have slightly different representations and accuracies on different
architectures it is generally not a good idea to compare them directly.
Rather numbers are considered equal if they are within an “epsilon” of each
other. *almost_equal* compares all elements of two matrices, returning true
if all elements are within the provided epsilon.

#### Examples

```
iex> Matrix.almost_equal( [[1, 0], [0, 1]], [[1,0], [0,1+1.0e-12]] )
false
iex> Matrix.almost_equal( [[1, 0], [0, 1]], [[1,0], [0,1+0.5e-12]] )
true
```

close_enough?(number, number, number, non_neg_integer) :: boolean

Code borrowed from the ExMath library and duplicated here to reduce dependencies. ExMath is copyright © 2015 Ookami Kenrou ookamikenrou@gmail.com

Equality comparison for floating point numbers, based on this blog post by Bruce Dawson.

Returns a new square “diagonal” matrix whose elements are zero except for the diagonal. The diagonal elements will be composed of the supplied list

#### See also

#### Examples

```
iex> Matrix.diag([1,2,3])
[[1, 0, 0], [0, 2, 0], [0, 0, 3]]
```

Returns the value of the specified element (row and column) of the given
matrix (x). The row and column indices are zero-based. Returns `default`

if either row or col are out of bounds.

#### See also

#### Examples

```
iex> Matrix.elem( Matrix.ident(3), 0,0 )
1
```

Returns a new matrix whose elements are the element-by-element multiply of the elements of the provided matrices. Note that this is not the linear algebra matrix multiply. If the matrices are of differing sizes, the returned matrix will be the size and dimensions of the “overlap” between them. For instance, the element multiply of a 3x3 matrix with a 2x2 matrix will be 2x2, for a 3x1 matrix with a 1x3 matrix will be 1x1.

#### See also

#### Examples

```
iex> Matrix.emult( Matrix.new(3,3,2), Matrix.new(3,3,-2) )
[[-4, -4, -4], [-4, -4, -4], [-4, -4, -4]]
iex> Matrix.emult( Matrix.ones(3,3), Matrix.ones(2,2) )
[[1, 1], [1, 1]]
iex> Matrix.emult( Matrix.ones(3,1), Matrix.ones(1,3) )
[[1]]
```

Returns a new “identity” matrix of the specified size. The identity is defined as a square matrix with ones on the diagonal and zeros in all off-diagonal elements. Since the matrix is square only a single size parameter is required.

#### See also

#### Examples

```
iex> Matrix.ident(3)
[[1, 0, 0], [0, 1, 0], [0, 0, 1]]
```

Returns a new matrix which is the (linear algebra) inverse of the supplied matrix. If the supplied matrix is “x” then, by definition,

` x * inv(x) = I`

where I is the identity matrix. This function uses a brute force Gaussian elimination so it is not expected to be terribly fast.

#### Examples

iex> x = Matrix.rand(5,5) iex> res = Matrix.mult( x, Matrix.inv(x) ) iex> Matrix.almost_equal(res,[[1,0,0],[0,1,0],[0,0,1]]) true

Returns the Kronecker tensor product of two matrices A and B. If A is an
MxN and B is PxQ, then the returned matrix is an (M*P)x(N*Q) matrix formed
by taking all possible products between the elements of A and the matrix B.

A = |1000| B = | 1 -1| |0100| | -1 1| |0010| |0001|then

kron(A,B) = | 1 -1 0 0 0 0 0 0| | -1 1 0 0 0 0 0 0| | 0 0 1 -1 0 0 0 0| | 0 0 -1 1 0 0 0 0| | 0 0 0 0 1 -1 0 0| | 0 0 0 0 -1 1 0 0| | 0 0 0 0 0 0 1 -1| | 0 0 0 0 0 0 -1 1|

Returns a new matrix which is the linear algebra matrix multiply
of the provided matrices. It is required that the number of columns
of the first matrix (x) be equal to the number of rows of the second
matrix (y). If x is an NxM and y is an MxP, the returned matrix product
xy is NxP. If the number of columns of x does not equal the number of
rows of y an `ArgumentError`

exception is thrown with the message “sizes
incompatible”

#### See also

#### Examples

```
iex> Matrix.mult( Matrix.seq(2,2), Matrix.seq(2,2) )
[[7, 10], [15, 22]]
iex> Matrix.mult( Matrix.ones(3,2), Matrix.ones(2,3) )
[[2, 2, 2], [2, 2, 2], [2, 2, 2]]
iex> Matrix.mult( Matrix.ones(3,2), Matrix.ones(3,2) )
** (ArgumentError) sizes incompatible
```

Returns a new matrix of the specified size (number of rows and columns). All elements of the matrix are filled with the supplied value “val” (default 0).

#### See also

#### Examples

```
iex> Matrix.new(3, 4)
[[0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]]
iex> Matrix.new(2, 3, -10)
[[-10, -10, -10], [-10, -10, -10]]
```

Returns a new matrix of the specified size (number of rows and columns). All elements of the matrix are filled with the ones.

#### See also

#### Examples

```
iex> Matrix.ones(3, 4)
[[1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1]]
```

Returns a new matrix whose elements are identical to the supplied matrix x but with the supplied value appended to the end of each row.

#### See also

#### Examples

```
iex> Matrix.postfix_rows( Matrix.seq(2,2), 10 )
[[1, 2, 10], [3, 4, 10]]
```

Returns a new matrix whose elements are identical to the supplied matrix x but with the supplied value appended to the beginning of each row.

#### See also

#### Examples

```
iex> Matrix.prefix_rows( Matrix.seq(2,2), 10 )
[[10, 1, 2], [10, 3, 4]]
```

Returns a string which is a “pretty” representation of the supplied matrix.

Returns a new matrix of the specified size (number of rows and columns). All elements of the matrix are filled with uniformly distributed random numbers between 0 and 1.

#### Examples

```
iex> _ = :rand.seed(:exs1024, {123, 123534, 345345})
iex> Matrix.rand(3,3)
[[0.5820506340260994, 0.6739535732076178, 0.9178030245386003],
[0.7402049520743949, 0.5589108995145826, 0.8687305849540213],
[0.8851580858928109, 0.988438251464987, 0.18105169154176423]]
```

#### See also

Returns a new matrix whose elements are the elements of matrix x multiplied by the scale factor “s”.

#### Examples

```
iex> Matrix.scale( Matrix.ident(3), 2 )
[[2,0,0], [0,2,0], [0,0,2]]
iex> Matrix.scale( Matrix.ones(3,4), -2 )
[[-2, -2, -2, -2], [-2, -2, -2, -2], [-2, -2, -2, -2]]
```

Returns a new matrix of the specified size (number of rows and columns) whose elements are sequential starting at 1 and increasing across the row.

#### See also

new/3, ones/2, rand/2, zeros/2

#### Examples

```
iex> Matrix.seq(3,2)
[[1, 2], [3, 4], [5, 6]]
```

Returns a matrix that is a copy of the supplied matrix (x) with the specified element (row and column) set to the specified value (val). The row and column indices are zero-based. Negative indices indicate an offset from the end of the row or column. If an index is out of bounds, the original matrix is returned.

#### See also

#### Examples

```
iex> Matrix.set( Matrix.ident(3), 0,0, -1)
[[-1, 0, 0], [0, 1, 0], [0, 0, 1]]
```

Returns the size (dimensions) of the supplied matrix. The return value is a tuple of the dimensions of the matrix as {rows,cols}.

#### See also

#### Examples

```
iex> Matrix.size( Matrix.new(3,4) )
{3, 4}
```

Returns a new matrix whose elements are the difference (subtraction) of the elements of the provided matrices. If the matrices are of differing sizes, the returned matrix will be the size and dimensions of the “overlap” between them. For instance, the difference of a 3x3 matrix with a 2x2 matrix will be 2x2. The difference of a 3x1 matrix with a 1x3 matrix will be 1x1.

#### See also

#### Examples

```
iex> Matrix.sub( Matrix.ident(3), Matrix.ones(3,3) )
[[0, -1, -1], [-1, 0, -1], [-1, -1, 0]]
iex> Matrix.sub( Matrix.ones(3,3), Matrix.ones(2,2) )
[[0, 0], [0, 0]]
iex> Matrix.sub( Matrix.ones(3,1), Matrix.ones(1,3) )
[[0]]
```

Returns a new matrix whose elements are the transpose of the supplied matrix. The transpose essentially swaps rows for columns - that is, the first row becomes the first column, the second row becomes the second column, etc.

#### Examples

iex> Matrix.transpose( Matrix.seq(3,2) ) [[1, 3, 5], [2, 4, 6]]