matrix-ts

fp-ts style mathematics library featuring: linear algebra, numerical methods, polynomials, and statistics

Table of Contents

• Install
  • Yarn
  • NPM
• Typescript Compatibility
• Documentation
• Possible future additions
• Data types
• Typeclasses
• Examples
  • Add fractions
  • Vector dot product
  • Vector cross product
  • Multiplies two Integer Polynomials
• Advanced Examples
  • Gaussian Elimination with Partial Pivoting (LUP)
  • Least Squares of an overdetermined system using QR Decomposition
  • Covariance matrix of a multivariate sample
  • Automorphisms of polynomials
  • Automorphisms of matricies
  • Quaternion automorphisms

Install

Uses fp-ts as a peer dependency. Read more about peer dependencies at nodejs.org.

Yarn

1yarn add fp-ts @jacob-alford/matrix-ts

NPM

1npm install fp-ts @jacob-alford/matrix-ts

Typescript Compatibility

This library depends on fp-ts version ^2.9.6 (or major versions above 2.9.6, and below 3.0.0), and thus requires typescript version 3.5+.

Documentation

• Docs
• fp-ts

Possible future additions

• Add Cholesky Decomposition
• Add QR Decomposition (Added in 1.1.0)
• Add SVD Decomposition
• Add linear interpolation
• Add regression / multi-regression
• Add PCA
• Add factor analysis
• Add CCA

Data types

• integer.ts – An integral data type with typeclass instances
• rational.ts – A fractional data type with typeclass instances
• number.ts – Typeclass instances for number
• complex.ts – Complex data type with typeclass instances
• quaternion.ts – Quaternion data type with typeclass instances
• Computation.ts – Either with logging
• Matrix.ts – A type-level constrained matrix type
• Decomposition.ts – Numerical Linear algebra
• Polynomial.ts – An array without trailing zeros
• Vector.ts – A type-level constrained vector type
• infix.ts – A constructor for polish/reverse polish and infix notation for particular typeclasses
• Multivariate.ts – Means / covariances / correlations of multivariable sampling
• Univariate.ts – Means variance / covariance / correlation of univariate and bivariate sampling

Typeclasses

• Iso.ts – Generic isomorphisms with composition
• Automorphism.ts – Generic automorphisms with composition
• AbelianGroup – Commutative group
• CommutativeRing – A commutative ring
• LeftModule – Left scalar multiplication
• RightModule – Right scalar multiplation
• Bimodule – Left and Right scalar multiplication

Examples

Add fractions

src/__tests__/examples.test.ts

1import * as O from 'fp-ts/Option'
2import * as Q from '@jacob-alford/matrix-ts/rational'
3import * as Int from '@jacob-alford/matrix-ts/integer'
4
5it('adds fractions', () => {
6  const { _ } = Q
7
8  const a = Q.of(Int.fromNumber(1), Int.fromNumber(2))
9  const b = Q.of(Int.fromNumber(1), Int.fromNumber(3))
10
11  const c = pipe(
12    O.Do,
13    O.apS('a', a),
14    O.apS('b', b),
15    O.map(({ a, b }) => _(a, '+', b))
16  )
17
18  const expected = Q.of(Int.fromNumber(5), Int.fromNumber(6))
19
20  expect(c).toStrictEqual(expected)
21})

Vector dot product

src/__tests__/examples.test.ts

1import * as N from '@jacob-alford/matrix-ts/number'
2import * as V from '@jacob-alford/matrix-ts/Vector'
3
4it('dots two vectors', () => {
5  const a = V.fromTuple([1, 2, 3, 4, 5, 6])
6  const b = V.fromTuple([4, 5, 6, 7, 8, 9])
7  expect(N.dot(a, b)).toBe(154)
8})

Vector cross product

src/__tests__/examples.test.ts

1import * as N from '@jacob-alford/matrix-ts/number'
2import * as V from '@jacob-alford/matrix-ts/Vector'
3
4it('crosses two vectors', () => {
5  const a = V.fromTuple([0, 2, 1])
6  const b = V.fromTuple([3, -1, 0])
7  expect(N.cross(a, b)).toStrictEqual(V.fromTuple([1, 3, -6]))
8})

Multiplies two Integer Polynomials

src/__tests__examples.test.ts

1import * as Poly from '@jacob-alford/matrix-ts/Polynomial'
2import * as Int from '@jacob-alford/matrix-ts/integer'
3
4it('multiples two polynomials', () => {
5  const fromArr = Poly.fromCoefficientArray(Int.Eq, Int.EuclideanRing)
6  const mul = Poly.mul(Int.Eq, Int.EuclideanRing)
7  const _ = Int.fromNumber
8  const { show } = Poly.getShow('x')(
9    Int.Show,
10    a => a === 0,
11    a => a === 1
12  )
13
14  // x + x^2
15  const p1 = fromArr([_(0), _(1), _(1)])
16  // 1 + x^4
17  const p2 = fromArr([_(1), _(0), _(0), _(0), _(1)])
18
19  // Expected: x + x^2 + x^5 + x^6
20  const result = mul(p1, p2)
21
22  expect(show(result)).toBe('x + x^2 + x^5 + x^6')
23})

Advanced Examples

Gaussian Elimination with Partial Pivoting (LUP)

src/__tests__/Decomposition.test.ts

1import * as D from '@jacob-alford/matrix-ts/Decomposition'
2import * as M from '@jacob-alford/matrix-ts/Matrix'
3import * as V from '@jacob-alford/matrix-ts/Vector'
4
5it('solves a system of equations', () => {
6  const A = M.fromNestedTuples([
7    [2, 10, 8, 8, 6],
8    [1, 4, -2, 4, -1],
9    [0, 2, 3, 2, 1],
10    [3, 8, 3, 10, 9],
11    [1, 4, 1, 2, 1],
12  ])
13
14  const [output] = D.LUP(A)
15
16  if (E.isLeft(output)) {
17    throw new Error('Unexpected result')
18  }
19
20  const { solve } = output.right
21
22  const b = V.fromTuple([52, 14, 12, 51, 15])
23  const c = V.fromTuple([50, 4, 12, 48, 12])
24  const x_b = solve(b)
25  const x_c = solve(c)
26
27  const expectedX_b = V.fromTuple([1, 2, 1, 2, 1])
28  const expectedX_c = V.fromTuple([2, 1, 2, 1, 2])
29
30  // ... assertions
31})
32it('returns a factorized matrix', () => {
33  const [output] = D.LUP(A)
34
35  if (E.isLeft(output)) {
36    throw new Error('Unexpected result')
37  }
38
39  const {
40    result: [L, U, P],
41  } = output.right
42
43  const expectedL = M.fromNestedTuples([
44    [1, 0, 0, 0, 0],
45    [2 / 3, 1, 0, 0, 0],
46    [1 / 3, 2 / 7, 1, 0, 0],
47    [1 / 3, 2 / 7, 4 / 11, 1, 0],
48    [0, 3 / 7, -1 / 11, -4 / 5, 1],
49  ])
50  const expectedU = M.fromNestedTuples([
51    [3, 8, 3, 10, 9],
52    [0, 14 / 3, 6, 4 / 3, 0],
53    [0, 0, -33 / 7, 2 / 7, -4],
54    [0, 0, 0, -20 / 11, -6 / 11],
55    [0, 0, 0, 0, 1 / 5],
56  ])
57
58  // ... assertions
59})

Least Squares of an overdetermined system using QR Decomposition

src/__tests__/Decomposition.test.ts

1it('solves a least squares problem', () => {
2    const A_ = M.fromNestedReadonlyArrays(
3      7,
4      3
5    )([
6      [1, -1, 1],
7      [1, -0.75, 0.75 ** 2],
8      [1, -0.5, 0.25],
9      [1, 0, 0],
10      [1, 0.25, 0.125],
11      [1, 0.5, 0.25],
12      [1, 0.75, 0.75 ** 2],
13    ])
14
15    const A = pipe(
16      A_,
17      C.fromOption(() => 'Unexpected result'),
18      C.getOrThrowS
19    )
20
21    const { solve } = C.getOrThrowS(QR(A))
22
23    const [, x] = C.getOrThrowS(
24      solve(V.fromTuple([1, 0.8125, 0.75, 1, 1.3125, 1.75, 2.3125]))
25    )
26
27    const e = V.fromTuple([1, 1, 1])
28
29    // ... assertions
30  })

Covariance matrix of a multivariate sample

src/__tests__/Multivariate.test.ts

1import * as RNEA from 'fp-ts/ReadonlyNonEmptyArray'
2import * as V from '@jacob-alford/matrix-ts/Vector'
3import * as Stat from '@jacob-alford/matrix-ts/Multivariate'
4
5it('calculates a covariance matrix', () => {
6  const sample: Stat.MultivariateSample<3> = [
7    V.fromTuple([1, 2, 5]),
8    V.fromTuple([4, 1, 6]),
9    V.fromTuple([4, 0, 4]),
10  ]
11
12  const cov = Stat.covariance(sample)
13
14  expect(cov).toStrictEqual([
15    [3, -3 / 2, 0],
16    [-3 / 2, 1, 1 / 2],
17    [0, 1 / 2, 1],
18  ])
19})

Automorphisms of polynomials

src/__tests__/examples.test.ts

1import * as Poly from '@jacob-alford/matrix-ts/Polynomial'
2import * as N from '@jacob-alford/matrix-ts/number'
3
4it('differentiates and integrates polynomials', () => {
5  const { equals } = Poly.getPolynomialEq<number>(N.Eq)
6
7  const L = N.getDifferentialAutomorphism(1)
8
9  const thereAndBack = flow(L.get, L.reverseGet)
10  const hereAndThere = flow(L.reverseGet, L.get)
11
12  const a = Poly.fromCoefficientArray(N.Eq, N.Field)([1, 2, 3])
13
14  expect(equals(thereAndBack(a), a)).toBe(true)
15  expect(equals(hereAndThere(a), a)).toBe(true)
16})

Automorphisms of matricies

src/__tests__/examples.test.ts

1import * as Auto from '@jacob-alford/matrix-ts/Automorphism'
2import * as N from '@jacob-alford/matrix-ts/number'
3import * as V from '@jacob-alford/matrix-ts/Vector'
4
5it('rotates a 2d vector and back 270 degrees', () => {
6  const rotate90Degrees = N.get2dRotation(Math.PI / 2)
7  const rotate180Degres = N.get2dRotation(Math.PI)
8
9  const T = Auto.compose(rotate90Degrees, rotate180Degres)
10
11  const initial = V.fromTuple([1, 0])
12  const rotated = T.get(initial)
13  const expected = V.fromTuple([0, -1])
14  const reversed = T.reverseGet(rotated)
15
16  // ... assertions
17})
18it('rotates a 3d vector and back along three axies', () => {
19  const rotateX45 = N.get3dXRotation(Math.PI / 4)
20  const rotateY180 = N.get3dYRotation(Math.PI)
21  const rotateZ90 = N.get3dZRotation(Math.PI / 2)
22
23  const T = Auto.compose(rotateX45, Auto.compose(rotateY180, rotateZ90))
24
25  const initial = V.fromTuple([0, 0, 1])
26  const rotated = T.get(initial)
27  const reversed = T.reverseGet(rotated)
28  const expected = V.fromTuple([1 / Math.sqrt(2), 0, -1 / Math.sqrt(2)])
29
30  // ... assertions
31})

Quaternion automorphisms

src/__tests__/examples.test.ts

1import * as H from '@jacob-alford/matrix-ts/quaternion'
2import * as V from '@jacob-alford/matrix-ts/Vector'
3
4it('rotates a 3d vector using quaternions', () => {
5  const T = H.getRotationAutomorphism(
6    // Around axis:
7    V.fromTuple([1, 1, 1]),
8    // By angle:
9    (2 * Math.PI) / 3
10  )
11
12  const initial = V.fromTuple([1, 0, 0])
13  const rotated = T.get(initial)
14  const reversed = T.reverseGet(rotated)
15  const expected = V.fromTuple([0, 1, 0])
16
17  // ... assertions
18})