Matrix

A matrix must be initialised with an element type. This type has to conform to the FullMathValue protocol. This means it must support all basic functions like +, -, /, ** (power operator), Equatable, Comparable. See the Math page for more info on additional protocols.

Init

There are several ways to initialise a Matrix. The most common way is to initialise from an Array.

// 2x3 matrix of inferred type Int
let A = Matrix([[1, 2, 3], [4, 5, 6]])

// 2x3 matrix of type Double, both ways give the same result
let B = Matrix([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
-- or --
let B = Matrix<Double>([[1, 2, 3], [4, 5, 6]])

Matrices can also be initialised by using an array literal, but the type of the variable must be known to be Matrix.

var A: Matrix<Int> = [[1, 2, 3], [4, 5, 6]]
// A is now known to be of type Matrix<Int>
A = [[7, 8], [9, 10]]

You can construct an empty matrix of a certain type like this:

let A: Matrix<Double> = Matrix()
-- or --
let A = Matrix<Double>()

init(dimensions: Dimensions, generator: (Index) -> T)

Initialises the matrix with the given dimensions using a generator function. The generator function accepts an Index and returns an appropriate value. The index's rows and columns start with 0. The type can be explicitly set or can be inferred from the generator's return type. See the Dimensions page to learn more about how to initialise Dimensions.

// 2x3 matrix of inferred type Int, since the type of Index.row and Index.column are Int
let A = Matrix(dimensions: Dimensions(2, 3), generator: { $0.row * $0.column })
// 0  0  0
// 0  1  2

Note that the generator is the final parameter, so a trailing closure can be used as well.

init(size: Int, generator: (Index) -> T)

Initialises a square matrix using a generator function. The generator function accepts an Index and returns an appropriate value. The index's rows and columns start with 0. The type can be explicitly set or can be inferred from the generator's return type.

// 2x2 matrix of inferred type Int, since the type of Index.row and Index.column are Int
let A = Matrix(size: 2, generator: { $0.row * $0.column })
// 0  0
// 0  1

Note that the generator is the final parameter, so a trailing closure can be used as well.

init(symmetrical elements: [T])

Initialises a symmetrical matrix with the given elements. The size of the matrix equals (elements.count + 1)/2, so the number of elements should be odd, otherwise the last element won't be used. The type can be explicitly set or can be inferred from the elements type.

let A = Matrix(symmetrical: [1, 2, 3])
// 1  2
// 2  3

init(filledWith element: T, dimensions: Dimensions)

Initialises a matrix with the given dimensions filled with the given element. The type can be explicitly set or can be inferred from the element type. See the Dimensions page to learn more about how to initialise Dimensions.

let A = Matrix(filledWith: 3, dimensions: Dimensions(3, 2))
// 3  3
// 3  3
// 3  3

init(filledWith element: T, size: Int)

Initialises a matrix with the given size filled with the given element. The type can be explicitly set or can be inferred from the element type.

let A = Matrix(filledWith: 3, size: 2)
// 3  3
// 3  3

init(identityOfSize size: Int)

Initialises an identity matrix of the given size. This is a matrix filled with 0, but with 1 on the main diagonal. The type should be explicitly set.

let A = Matrix<Int>(identityOfSize: 3)
// 1  0  0
// 0  1  0
// 0  0  1

init(diagonal: [T])

Initialises a square matrix with the given diagonal elements. The type can be explicitly set or can be inferred from the diagonal elements. The size of the matrix equals the length of the given diagonal Array.

let A = Matrix(diagonal: [1, 2, 3])
// 1  0  0
// 0  2  0
// 0  0  3

Element Manipulation

Element manipulation is possible through subscript syntax and through more specific functions.

Subscript

Get and set elements

var A = Matrix([[1, 2, 3], [4, 5, 6]])
let x = A[0, 2] // x = 3
A[0, 2] = 7
// Now A equals
// 1  2  7
// 4  5  6

Get and set rows

To get and set rows you have to work with Vector.

var A = Matrix([[1, 2, 3], [4, 5, 6]])
let x = A[1] // x = Vector([4, 5, 6])
A[1] = Vector([7, 8, 9])
// Now A equals
// 1  2  3
// 7  8  9

Note there is no subscript method for getting and setting columns, this will have to be done by using the explicit methods.

Get and set subvectors

To get and set subvectors you have to work with Vector. You will have to use a combination of an Int and an Range to define the subvector. [Int, Range] defines a subvector where the Int represent the row and the Range the included columns.

var A = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
let x = A[1, 1...2] // x = Vector([5, 6])
let y = A[0...1, 2] // y = Vector([3, 6])
A[1, 1...2] = Vector([10, 11])
// Now A equals
// 1  2  3
// 4  10 11
// 7  8  9
A[0...1, 2] = Vector([12, 13])
// Now A equals
// 1  2  12
// 4  10 13
// 7  8  9

Get and set submatrices

To get and set submatrices you have to use Matrix.

var A = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
let x = A[0...1, 1..2]
// x equals
// 2  3
// 5  6
A[0...1, 1...2] = Matrix([[10, 11], [12, 13]])
// Now A equals
// 1  10 11
// 4  12 13
// 7  8  9

Explicit Methods

element(row: Int, _ column: Int) -> T

Returns the element at the given row and column. This method will raise an exception if the row and/or column are out of bounds.

setElement(atRow row: Int, atColumn: column Int, toElement element: T) {

Replaces the element at the given row and column with the given element. This method will raise an exception if the row and/or column are out of bounds.

setElement(atIndex index: (Int, Int), toElement element: T)

Replaces the element at the given row and column with the given element. This method will raise an exception if the row and/or column are out of bounds.

row(index: Int) -> Vector

Returns the row at the given index as a Vector.

setRow(atIndex index: Int, toRow newRow: Vector)

Replaces the row at the given index with the given row vector.

Factorisations / Decompositions

LU Decomposition

LUDecomposition: (Matrix, Matrix, Matrix)

Returns the LU Decomposition as (L, U, P) so that Pself = LU where L is a lower triangular matrix with 1 on it's diagonal, U is an upper triangular matrix and P is a permutation matrix. The Decomposition uses optimal pivoting.

LUDecomposition(pivoting: Bool = true, optimalPivoting: Bool = true)

Returns the LU Decomposition as (L, U, P) so that Pself = LU where L is a lower triangular matrix with 1 on it's diagonal, U is an upper triangular matrix and P is a permutation matrix. If pivoting is true, the rows will be swapped if the pivot elements become 0. If optimalPivoting is true, the rows will be swapped so that the biggest element becomes the pivot element to increase stability.