a multidimensional array with a type-level shape

>>> :set -XDataKinds
>>> [1..24] :: Array '[2,3,4] Int
[[[1, 2, 3, 4],
  [5, 6, 7, 8],
  [9, 10, 11, 12]],
 [[13, 14, 15, 16],
  [17, 18, 19, 20],
  [21, 22, 23, 24]]]

>>> [1,2,3] :: Array '[2,2] Int
*** Exception: NumHaskException {errorMessage = "shape mismatch"}
[[

Use a dynamic array in a fixed context.

>>> import qualified NumHask.Array.Dynamic as D
>>> with (D.fromFlatList [2,3,4] [1..24]) (selects (Proxy :: Proxy '[0,1]) [1,1] :: Array '[2,3,4] Int -> Array '[4] Int)
[17, 18, 19, 20]

Get shape of an Array as a value.

>>> shape a
[2,3,4]

convert to a dynamic array with shape at the value level.

Takes the top-most elements according to the new dimension.

>>> takes a :: Array '[2,2,3] Int
[[[1, 2, 3],
  [5, 6, 7]],
 [[13, 14, 15],
  [17, 18, 19]]]

Reshape an array (with the same number of elements).

>>> reshape a :: Array '[4,3,2] Int
[[[1, 2],
  [3, 4],
  [5, 6]],
 [[7, 8],
  [9, 10],
  [11, 12]],
 [[13, 14],
  [15, 16],
  [17, 18]],
 [[19, 20],
  [21, 22],
  [23, 24]]]

Reverse indices eg transposes the element Aijk to Akji.

>>> index (transpose a) [1,0,0] == index a [0,0,1]
True

Indices of an Array.

>>> indices :: Array '[3,3] [Int]
[[[0,0], [0,1], [0,2]],
 [[1,0], [1,1], [1,2]],
 [[2,0], [2,1], [2,2]]]

The identity array.

>>> ident :: Array '[3,2] Int
[[1, 0],
 [0, 1],
 [0, 0]]

An array of sequential Ints

>>> sequent :: Array '[3] Int
[0, 1, 2]

>>> sequent :: Array '[3,3] Int
[[0, 0, 0],
 [0, 1, 0],
 [0, 0, 2]]

Extract the diagonal of an array.

>>> diag (ident :: Array '[3,2] Int)
[1, 1]

Expand the array to form a diagonal array

>>> undiag ([1,1] :: Array '[2] Int)
[[1, 0],
 [0, 1]]

Create an array composed of a single value.

>>> singleton one :: Array '[3,2] Int
[[1, 1],
 [1, 1],
 [1, 1]]

Select an array along dimensions.

>>> let s = selects (Proxy :: Proxy '[0,1]) [1,1] a
>>> :t s
s :: Array '[4] Int

>>> s
[17, 18, 19, 20]

Select an index except along specified dimensions.

>>> let s = selectsExcept (Proxy :: Proxy '[2]) [1,1] a
>>> :t s
s :: Array '[4] Int

>>> s
[17, 18, 19, 20]

Fold along specified dimensions.

>>> folds sum (Proxy :: Proxy '[1]) a
[68, 100, 132]

Extracts dimensions to an outer layer.

>>> let e = extracts (Proxy :: Proxy '[1,2]) a
>>> :t e
e :: Array [3, 4] (Array '[2] Int)

Extracts except dimensions to an outer layer.

>>> let e = extractsExcept (Proxy :: Proxy '[1,2]) a
>>> :t e
e :: Array '[2] (Array [3, 4] Int)

Join inner and outer dimension layers.

>>> let e = extracts (Proxy :: Proxy '[1,0]) a

>>> :t e
e :: Array [3, 2] (Array '[4] Int)

>>> let j = joins (Proxy :: Proxy '[1,0]) e

>>> :t j
j :: Array [2, 3, 4] Int

>>> a == j
True

Maps a function along specified dimensions.

>>> :t maps (transpose) (Proxy :: Proxy '[1]) a
maps (transpose) (Proxy :: Proxy '[1]) a :: Array [4, 3, 2] Int

Concatenate along a dimension.

>>> :t concatenate (Proxy :: Proxy 1) a a
concatenate (Proxy :: Proxy 1) a a :: Array [2, 6, 4] Int

Insert along a dimension at a position.

>>> insert (Proxy :: Proxy 2) (Proxy :: Proxy 0) a ([100..105])
[[[100, 1, 2, 3, 4],
  [101, 5, 6, 7, 8],
  [102, 9, 10, 11, 12]],
 [[103, 13, 14, 15, 16],
  [104, 17, 18, 19, 20],
  [105, 21, 22, 23, 24]]]

Insert along a dimension at the end.

>>> :t append (Proxy :: Proxy 0) a
append (Proxy :: Proxy 0) a
  :: Array [3, 4] Int -> Array [3, 3, 4] Int

Change the order of dimensions.

>>> let r = reorder (Proxy :: Proxy '[2,0,1]) a
>>> :t r
r :: Array [4, 2, 3] Int

Product two arrays using the supplied binary function.

For context, if the function is multiply, and the arrays are tensors, then this can be interpreted as a tensor product.

https://en.wikipedia.org/wiki/Tensor_product

The concept of a tensor product is a dense crossroad, and a complete treatment is elsewhere. To quote:

... the tensor product can be extended to other categories of mathematical objects in addition to vector spaces, such as to matrices, tensors, algebras, topological vector spaces, and modules. In each such case the tensor product is characterized by a similar universal property: it is the freest bilinear operation. The general concept of a "tensor product" is captured by monoidal categories; that is, the class of all things that have a tensor product is a monoidal category.

>>> expand (*) v v
[[1, 2, 3],
 [2, 4, 6],
 [3, 6, 9]]

Alternatively, expand can be understood as representing the permutation of element pairs of two arrays, so like the Applicative List instance.

>>> i2 = indices :: Array '[2,2] [Int]
>>> expand (,) i2 i2
[[[[([0,0],[0,0]), ([0,0],[0,1])],
   [([0,0],[1,0]), ([0,0],[1,1])]],
  [[([0,1],[0,0]), ([0,1],[0,1])],
   [([0,1],[1,0]), ([0,1],[1,1])]]],
 [[[([1,0],[0,0]), ([1,0],[0,1])],
   [([1,0],[1,0]), ([1,0],[1,1])]],
  [[([1,1],[0,0]), ([1,1],[0,1])],
   [([1,1],[1,0]), ([1,1],[1,1])]]]]

Like expand, but permutes the first array first, rather than the second.

>>> expand (,) v (v |+ 3)
[[(1,4), (1,5), (1,6)],
 [(2,4), (2,5), (2,6)],
 [(3,4), (3,5), (3,6)]]

>>> expandr (,) v (v |+ 3)
[[(1,4), (2,4), (3,4)],
 [(1,5), (2,5), (3,5)],
 [(1,6), (2,6), (3,6)]]

Apply an array of functions to each array of values.

This is in the spirit of the applicative functor operation (<*>).

expand f a b == apply (fmap f a) b

>>> apply ((*) <$> v) v
[[1, 2, 3],
 [2, 4, 6],
 [3, 6, 9]]

Fixed Arrays can't be applicative functors because the changes in shape are reflected in the types.

:t apply
apply
  :: (HasShape s, HasShape s', HasShape (s ++ s')) =>
     Array s (a -> b) -> Array s' a -> Array (s ++ s') b
:t (<*>)
(<*>) :: Applicative f => f (a -> b) -> f a -> f b

>>> let b = [1..6] :: Array '[2,3] Int
>>> contract sum (Proxy :: Proxy '[1,2]) (apply (fmap (*) b) (transpose b))
[[14, 32],
 [32, 77]]

Contract an array by applying the supplied (folding) function on diagonal elements of the dimensions.

This generalises a tensor contraction by allowing the number of contracting diagonals to be other than 2, and allowing a binary operator other than multiplication.

>>> let b = [1..6] :: Array '[2,3] Int
>>> contract sum (Proxy :: Proxy '[1,2]) (expand (*) b (transpose b))
[[14, 32],
 [32, 77]]

A generalisation of a dot operation, which is a multiplicative expansion of two arrays and sum contraction along the middle two dimensions.

matrix multiplication

>>> let b = [1..6] :: Array '[2,3] Int
>>> dot sum (*) b (transpose b)
[[14, 32],
 [32, 77]]

inner product

>>> let v = [1..3] :: Array '[3] Int
>>> :t dot sum (*) v v
dot sum (*) v v :: Array '[] Int

>>> dot sum (*) v v
14

matrix-vector multiplication (Note how the vector doesn't need to be converted to a row or column vector)

>>> dot sum (*) v b
[9, 12, 15]

>>> dot sum (*) b v
[14, 32]

Array elements don't have to be numbers:

>>> x1 = (show <$> [1..4]) :: Array '[2,2] String
>>> x2 = (show <$> [5..8]) :: Array '[2,2] String
>>> x1
[["1", "2"],
 ["3", "4"]]

>>> x2
[["5", "6"],
 ["7", "8"]]

>>> import Data.List (intercalate)
>>> dot (intercalate "+" . toList) (\a b -> a <> "*" <> b) x1 x2
[["1*5+2*7", "1*6+2*8"],
 ["3*5+4*7", "3*6+4*8"]]

dot allows operation on mis-shaped matrices. The algorithm ignores excess positions within the contracting dimension(s):

>>> let m23 = [1..6] :: Array '[2,3] Int
>>> let m12 = [1,2] :: Array '[1,2] Int
>>> shape $ dot sum (*) m23 m12
[2,2]

Find instances of a vector in a matrix

>>> let cs = fromList ("abacbaab" :: [Char]) :: Array '[4,2] Char
>>> let v = fromList ("ab" :: [Char]) :: Vector 2 Char
>>> dot (all id) (==) cs v
[True, False, False, True]

Array multiplication.

matrix multiplication

>>> let b = [1..6] :: Array '[2,3] Int
>>> mult b (transpose b)
[[14, 32],
 [32, 77]]

inner product

>>> let v = [1..3] :: Array '[3] Int
>>> :t mult v v
mult v v :: Array '[] Int

>>> mult v v
14

matrix-vector multiplication

>>> mult v b
[9, 12, 15]

>>> mult b v
[14, 32]

Select elements along positions in every dimension.

>>> let s = slice (Proxy :: Proxy '[[0,1],[0,2],[1,2]]) a
>>> :t s
s :: Array [2, 2, 2] Int

>>> s
[[[2, 3],
  [10, 11]],
 [[14, 15],
  [22, 23]]]

>>> let s = squeeze $ slice (Proxy :: Proxy '[ '[0], '[0], '[0]]) a
>>> :t s
s :: Array '[] Int

>>> s
1

Remove single dimensions.

>>> let a = [1..24] :: Array '[2,1,3,4,1] Int
>>> a
[[[[[1],
    [2],
    [3],
    [4]],
   [[5],
    [6],
    [7],
    [8]],
   [[9],
    [10],
    [11],
    [12]]]],
 [[[[13],
    [14],
    [15],
    [16]],
   [[17],
    [18],
    [19],
    [20]],
   [[21],
    [22],
    [23],
    [24]]]]]
>>> squeeze a
[[[1, 2, 3, 4],
  [5, 6, 7, 8],
  [9, 10, 11, 12]],
 [[13, 14, 15, 16],
  [17, 18, 19, 20],
  [21, 22, 23, 24]]]

>>> squeeze ([1] :: Array '[1,1] Double)
1.0

Unwrapping scalars is probably a performance bottleneck.

>>> let s = [3] :: Array ('[] :: [Nat]) Int
>>> fromScalar s
3

Convert a number to a scalar.

>>> :t toScalar 2
toScalar 2 :: FromInteger a => Array '[] a

Wiki Vector

Vector specialisation of sequent

Wiki Matrix

Extract specialised to a matrix.

>>> col 1 m
[1, 5, 9]

Extract specialised to a matrix.

>>> row 1 m
[4, 5, 6, 7]

Column extraction checked at type level.

>>> safeCol (Proxy :: Proxy 1) m
[1, 5, 9]

>>> safeCol (Proxy :: Proxy 4) m
...
... index outside range
...

Row extraction checked at type level.

>>> safeRow (Proxy :: Proxy 1) m
[4, 5, 6, 7]

>>> safeRow (Proxy :: Proxy 3) m
...
... index outside range
...

Matrix multiplication.

This is dot sum (*) specialised to matrices

>>> let a = [1, 2, 3, 4] :: Array '[2, 2] Int
>>> let b = [5, 6, 7, 8] :: Array '[2, 2] Int
>>> a
[[1, 2],
 [3, 4]]

>>> b
[[5, 6],
 [7, 8]]

>>> mmult a b
[[19, 22],
 [43, 50]]

cholesky decomposition

Uses the Cholesky-Crout algorithm.

Inverse of a triangular matrix.