A hyperrectangular (or multidimensional) array with a type-level shape.

>>> array @Vec.Vector @[2,3,4] @Int [1..24]
[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24]
>>> array [1..24] :: Array Vec.Vector '[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]
>>> pretty (array @Vec.Vector @[2,3,4] @Int [1..24])
[[[1,2,3,4],
  [5,6,7,8],
  [9,10,11,12]],
 [[13,14,15,16],
  [17,18,19,20],
  [21,22,23,24]]]

>>> array [1,2,3] :: Array Vec.Vector '[2,2] Int
*** Exception: Shape Mismatch
...

In many situations, the use of TypeApplication can lead to a clean coding style.

>>> array @Vec.Vector @[2,3] @Int [1..6]
[1,2,3,4,5,6]

The main computational entry and exit points are often via index and tabulate with arrays indexed by Fins:

>>> index a (S.UnsafeFins [1,2,3])
23

>>> :t tabulate id :: Array Vec.Vector [2,3] (Fins [2,3])
tabulate id :: Array Vec.Vector [2,3] (Fins [2,3])
  :: Array Vec.Vector [2, 3] (Fins [2, 3])
>>> pretty (tabulate id :: Array Vec.Vector [2,3] (Fins [2,3]))
[[[0,0],[0,1],[0,2]],
 [[1,0],[1,1],[1,2]]]

Construct an array without shape validation.

>>> unsafeArray [0..4] :: Array Vec.Vector [2,3] Int
[0,1,2,3,4]

Validate the size and shape of an array.

>>> validate (unsafeArray [0..4] :: Array Vec.Vector [2,3] Int)
False

Construct an Array, checking shape.

>>> (safeArray [0..23] :: Maybe (Array Vec.Vector [2,3,4] Int)) == Just a
True

Construct an Array, throwing an exception on a bad shape.

>>> array [0..22] :: Array Vec.Vector [2,3,4] Int
*** Exception: Shape Mismatch
...

Unsafely modify an array shape.

>>> pretty (unsafeModifyShape @Vec.Vector @[3,2] (array @Vec.Vector @[2,3] @Int [0..5]))
[[0,1],
 [2,3],
 [4,5]]

Unsafely modify an array vector.

pretty (unsafeModifyVector (Vec.map (+1)) (array [0..5] :: Array Vec.Vector [2,3] Int))

[1,2,3

,

4,5,6

]

Representation of an index into a shape (a type-level [Nat]). 'Dim @0' is commonly thought of as the row of an array.

Pattern synonym for a Dim

Representation of indexes into a shape (a type-level [Nat]). The indexes are dimensions of the shape.

Pattern synonym for a Dims

Conversion to and from a Vector

Note that conversion of an Array to a vector drops shape information, so that:

vectorAs . asVector == id
asVector . vectorAs == 'flat'

>>> asVector (range @Vec.Vector @[2,3]) :: Vec.Vector Int
[0,1,2,3,4,5]

vectorAs (VG.fromList [0..5]) :: Array Vec.Vector [2,3] Int

0,1,2,3,4,5

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

>>> toDynamic a
UnsafeArray [2,3,4] [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23]

Use a dynamic array in a fixed context.

>>> import Harpie.Array.Generic qualified as A
>>> with (A.range @Vec.Vector [2,3,4]) show
"[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23]"

This doesn't work for anything more complex where KnownNats need to be type computed:

:t with (A.range [2,3,4]) (pretty . F.takes (Dims @'[0]) (S.SNats @'[1]))

... • Could not deduce ‘S.KnownNats (Fcf.Data.List.Drop_ 1 s)’ ...

Get shape of an Array as a value.

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

Get rank of an Array as a value.

>>> rank a
3

Get size of an Array as a value.

>>> size a
24

Number of rows (first dimension size) in an Array. As a convention, a scalar value is still a single row.

>>> length a
2
>>> length (toScalar @Vec.Vector 0)
1

Is the Array empty (has zero number of elements).

>>> isNull (array [] :: Array Vec.Vector [2,0] ())
True
>>> isNull (array [4] :: Array Vec.Vector '[] Int)
False

Index into an array using Fins.

Extract an element at an index, unsafely.

>>> unsafeIndex a [1,2,3]
23

Extract an element at an index, unsafely.

>>> a ! [1,2,3]
23

Extract an element at an index, safely.

>>> a !? [1,2,3]
Just 23
>>> a !? [2,3,1]
Nothing

Tabulate an array from a function on Fins.

Tabulate unsafely.

>>> :t tabulate @Vec.Vector @[2,3] id
tabulate @Vec.Vector @[2,3] id
  :: Array Vec.Vector [2, 3] (Fins [2, 3])
>>> :t unsafeTabulate @[2,3] id :: Array Vec.Vector [2,3] [Int]
unsafeTabulate @[2,3] id :: Array Vec.Vector [2,3] [Int]
  :: Array Vec.Vector [2, 3] [Int]
>>> pretty (unsafeTabulate @[2,3] id :: Array Vec.Vector [2,3] [Int])
[[[0,0],[0,1],[0,2]],
 [[1,0],[1,1],[1,2]]]

backpermute is a tabulation where the contents of an array do not need to be accessed, and is thus a fulcrum for leveraging laziness and fusion via the rule:

backpermute f (backpermute f' a) == backpermute (f . f') a

Many functions in this module are examples of backpermute usage.

>>> pretty $ backpermute @Vec.Vector @[4,3,2] (UnsafeFins . List.reverse . fromFins) a
[[[0,12],
  [4,16],
  [8,20]],
 [[1,13],
  [5,17],
  [9,21]],
 [[2,14],
  [6,18],
  [10,22]],
 [[3,15],
  [7,19],
  [11,23]]]

Unsafe backpermute

>>> pretty $ unsafeBackpermute @Vec.Vector @[4,3,2] List.reverse a
[[[0,12],
  [4,16],
  [8,20]],
 [[1,13],
  [5,17],
  [9,21]],
 [[2,14],
  [6,18],
  [10,22]],
 [[3,15],
  [7,19],
  [11,23]]]

Unwrap a scalar.

>>> s = array @Vec.Vector @'[] @Int [3]
>>> :t fromScalar s
fromScalar s :: Int

Wrap a scalar.

>>> :t toScalar @Vec.Vector @Int 2
toScalar @Vec.Vector @Int 2 :: Array Vec.Vector '[] Int

Is an array a scalar?

>>> isScalar (toScalar @Vec.Vector (2::Int))
True

Convert a scalar to being a dimensioned array. Do nothing if not a scalar.

>>> asSingleton (toScalar @Vec.Vector 4)
[4]

Convert an array with shape [1] to being a scalar (Do nothing if not a shape [1] array).

>>> pretty (asScalar (singleton @Vec.Vector 3))
3

An array with no elements.

>>> toDynamic (empty @Vec.Vector @Int)
UnsafeArray [0] []

An enumeration of row-major or lexicographic order.

>>> pretty (range :: Array Vec.Vector [2,3] Int)
[[0,1,2],
 [3,4,5]]

An enumeration of col-major or colexicographic order.

>>> pretty (corange @Vec.Vector @[2,3,4])
[[[0,6,12,18],
  [2,8,14,20],
  [4,10,16,22]],
 [[1,7,13,19],
  [3,9,15,21],
  [5,11,17,23]]]

Indices of an array shape.

>>> pretty (indices @[3,3] :: Array Vec.Vector [3,3] [Int])
[[[0,0],[0,1],[0,2]],
 [[1,0],[1,1],[1,2]],
 [[2,0],[2,1],[2,2]]]

The identity array.

>>> pretty (ident @[3,3] :: Array Vec.Vector [3,3] Int)
[[1,0,0],
 [0,1,0],
 [0,0,1]]

Create an array composed of a single value.

>>> pretty (konst @[3,2] 1 :: Array Vec.Vector [3,2] Int)
[[1,1],
 [1,1],
 [1,1]]

Create an array of shape [1].

>>> pretty $ singleton @Vec.Vector 1
[1]

Extract the diagonal of an array.

>>> pretty $ diag (ident @[3,3] :: Array Vec.Vector [3,3] Int)
[1,1,1]

Expand an array to form a diagonal array

>>> pretty $ undiag (range @Vec.Vector @'[3])
[[0,0,0],
 [0,1,0],
 [0,0,2]]

Zip two arrays at an element level.

>>> zipWith (-) v v
[0,0,0]

Modify a single value at an index.

>>> pretty $ modify (S.UnsafeFins [0,0]) (const 100) (range @Vec.Vector @[3,2])
[[100,1],
 [2,3],
 [4,5]]

Maps an index function at element-level.

>>> pretty $ imap (\xs x -> x - sum xs) a
[[[0,0,0,0],
  [3,3,3,3],
  [6,6,6,6]],
 [[11,11,11,11],
  [14,14,14,14],
  [17,17,17,17]]]

With a function that takes dimensions and (type-level) parameters, apply the parameters to the initial dimensions. ie

rowWise f xs = f [0..rank xs - 1] xs

>>> toDynamic $ rowWise indexesT (S.SNats @[1,0]) a
UnsafeArray [4] [12,13,14,15]

With a function that takes dimensions and (type-level) parameters, apply the parameters to the the last dimensions. ie

colWise f xs = f (List.reverse [0 .. (rank a - 1)]) xs

>>> toDynamic $ colWise indexesT (S.SNats @[1,0]) a
UnsafeArray [2] [1,13]

Take the top-most elements across the specified dimension.

>>> pretty $ take (Dim @2) (SNat @1) a
[[[0],
  [4],
  [8]],
 [[12],
  [16],
  [20]]]

Take the bottom-most elements across the specified dimension.

>>> pretty $ takeB (Dim @2) (SNat @1) a
[[[3],
  [7],
  [11]],
 [[15],
  [19],
  [23]]]

Drop the top-most elements across the specified dimension.

>>> pretty $ drop (Dim @2) (SNat @1) a
[[[1,2,3],
  [5,6,7],
  [9,10,11]],
 [[13,14,15],
  [17,18,19],
  [21,22,23]]]

Drop the bottom-most elements across the specified dimension.

>>> pretty $ dropB (Dim @2) (SNat @1) a
[[[0,1,2],
  [4,5,6],
  [8,9,10]],
 [[12,13,14],
  [16,17,18],
  [20,21,22]]]

Select an index along a dimension.

>>> let s = select (Dim @2) (S.fin @4 3) a
>>> pretty s
[[3,7,11],
 [15,19,23]]

Insert along a dimension at a position.

>>> pretty $ insert (Dim @2) (UnsafeFin 0) a (konst @[2,3] 0 :: Array Vec.Vector [2,3] Int)
[[[0,0,1,2,3],
  [0,4,5,6,7],
  [0,8,9,10,11]],
 [[0,12,13,14,15],
  [0,16,17,18,19],
  [0,20,21,22,23]]]
>>> toDynamic $ insert (Dim @0) (UnsafeFin 0) (toScalar @Vec.Vector 1) (toScalar @Vec.Vector 2)
UnsafeArray [2] [2,1]

Delete along a dimension at a position.

>>> pretty $ delete (Dim @2) (UnsafeFin 3) a
[[[0,1,2],
  [4,5,6],
  [8,9,10]],
 [[12,13,14],
  [16,17,18],
  [20,21,22]]]

Insert along a dimension at the end.

>>> pretty $ append (Dim @2) a (konst @[2,3] 0 :: Array Vec.Vector [2,3] Int)
[[[0,1,2,3,0],
  [4,5,6,7,0],
  [8,9,10,11,0]],
 [[12,13,14,15,0],
  [16,17,18,19,0],
  [20,21,22,23,0]]]

Insert along a dimension at the beginning.

>>> pretty $ prepend (Dim @2) (konst @[2,3] 0 :: Array Vec.Vector [2,3] Int) a
[[[0,0,1,2,3],
  [0,4,5,6,7],
  [0,8,9,10,11]],
 [[0,12,13,14,15],
  [0,16,17,18,19],
  [0,20,21,22,23]]]

Concatenate along a dimension.

>>> shape $ concatenate (Dim @1) a a
[2,6,4]
>>> toDynamic $ concatenate (Dim @0) (toScalar @Vec.Vector 1) (toScalar @Vec.Vector 2)
UnsafeArray [2] [1,2]
>>> toDynamic $ concatenate (Dim @0) (array @Vec.Vector @'[1] [0]) (array @Vec.Vector @'[3] [1..3])
UnsafeArray [4] [0,1,2,3]

Combine two arrays as a new dimension of a new array.

>>> pretty $ couple (Dim @0) (array @Vec.Vector @'[3] [1,2,3]) (array @Vec.Vector @'[3] @Int [4,5,6])
[[1,2,3],
 [4,5,6]]
>>> couple (Dim @0) (toScalar @Vec.Vector @Int 0) (toScalar @Vec.Vector 1)
[0,1]

Slice along a dimension with the supplied offset & length.

>>> pretty $ slice (Dim @2) (SNat @1) (SNat @2) a
[[[1,2],
  [5,6],
  [9,10]],
 [[13,14],
  [17,18],
  [21,22]]]

Rotate an array along a dimension.

>>> pretty $ rotate (Dim @1) 2 a
[[[8,9,10,11],
  [0,1,2,3],
  [4,5,6,7]],
 [[20,21,22,23],
  [12,13,14,15],
  [16,17,18,19]]]

Across the specified dimensions, takes the top-most elements.

>>> pretty $ takes (Dims @[0,1]) (S.SNats @[1,2]) a
[[[0,1,2,3],
  [4,5,6,7]]]

Across the specified dimensions, takes the bottom-most elements.

>>> pretty (takeBs (Dims @[0,1]) (S.SNats @[1,2]) a)
[[[16,17,18,19],
  [20,21,22,23]]]

Across the specified dimensions, drops the top-most elements.

>>> pretty $ drops (Dims @[0,2]) (S.SNats @[1,3]) a
[[[15],
  [19],
  [23]]]

Across the specified dimensions, drops the bottom-most elements.

>>> pretty $ dropBs (Dims @[0,2]) (S.SNats @[1,3]) a
[[[0],
  [4],
  [8]]]

Select by dimensions and indexes.

>>> pretty $ indexes (Dims @[0,1]) (S.UnsafeFins [1,1]) a
[16,17,18,19]
>>> pretty $ indexes (Dims @'[1]) (S.fins @'[3] [1]) (range @Vec.Vector @[2,3])
[1,4]

Select by dimensions and indexes, supplying indexes as a type.

>>> pretty $ indexesT (Dims @[0,1]) (S.SNats @[1,1]) a
[16,17,18,19]

Slice along dimensions with the supplied offsets and lengths.

>>> pretty $ slices (Dims @'[2]) (S.SNats @'[1]) (S.SNats @'[2]) a
[[[1,2],
  [5,6],
  [9,10]],
 [[13,14],
  [17,18],
  [21,22]]]

Select the first element along the supplied dimensions.

>>> pretty $ heads (Dims @[0,2]) a
[0,4,8]

Select the last element along the supplied dimensions.

>>> pretty $ lasts (Dims @[0,2]) a
[15,19,23]

Select the tail elements along the supplied dimensions.

>>> pretty $ tails (Dims @[0,2]) a
[[[13,14,15],
  [17,18,19],
  [21,22,23]]]

Select the init elements along the supplied dimensions.

>>> pretty $ inits (Dims @[0,2]) a
[[[0,1,2],
  [4,5,6],
  [8,9,10]]]

Extracts specified dimensions to an outer layer.

>>> :t extracts (Dims @'[0]) (range @Vec.Vector @[2,3,4])
extracts (Dims @'[0]) (range @Vec.Vector @[2,3,4])
  :: Array Vec.Vector '[2] (Array Vec.Vector [3, 4] Int)

Reduce along specified dimensions, using the supplied fold.

>>> pretty $ reduces (Dims @'[0]) sum a
[66,210]
>>> pretty $ reduces (Dims @[0,2]) sum a
[[12,15,18,21],
 [48,51,54,57]]

Join inner and outer dimension layers by supplied dimensions.

>>> let e = extracts (Dims @[1,0]) a
>>> let j = joins (Dims @[1,0]) e
>>> a == j
True

Join inner and outer dimension layers in outer dimension order.

>>> a == join (extracts (Dims @[0,1]) a)
True

Traverse along specified dimensions.

>>> traverses (Dims @'[1]) print (range @Vec.Vector @[2,3])
0
3
1
4
2
5
[(),(),(),(),(),()]

Maps a function along specified dimensions.

>>> pretty $ maps (Dims @'[1]) transpose a
[[[0,12],
  [4,16],
  [8,20]],
 [[1,13],
  [5,17],
  [9,21]],
 [[2,14],
  [6,18],
  [10,22]],
 [[3,15],
  [7,19],
  [11,23]]]

Filters along specified dimensions (which are flattened as a dynamic array).

>>> pretty $ filters (Dims @[0,1]) (any ((==0) . (`mod` 7))) a
[[0,1,2,3],[4,5,6,7],[12,13,14,15],[20,21,22,23]]

Zips two arrays with a function along specified dimensions.

>>> pretty $ zips (Dims @[0,1]) (zipWith (,)) a (reverses (Dims @'[0]) a)
[[[(0,12),(1,13),(2,14),(3,15)],
  [(4,16),(5,17),(6,18),(7,19)],
  [(8,20),(9,21),(10,22),(11,23)]],
 [[(12,0),(13,1),(14,2),(15,3)],
  [(16,4),(17,5),(18,6),(19,7)],
  [(20,8),(21,9),(22,10),(23,11)]]]

Modify using the supplied function along dimensions and positions.

>>> pretty $ modifies (fmap (100+)) (Dims @'[2]) (S.UnsafeFins [0]) a
[[[100,1,2,3],
  [104,5,6,7],
  [108,9,10,11]],
 [[112,13,14,15],
  [116,17,18,19],
  [120,21,22,23]]]

Apply a binary function between successive slices, across dimensions and lags.

>>> pretty $ diffs (Dims @'[1]) (S.SNats @'[1]) (zipWith (-)) a
[[[4,4,4,4],
  [4,4,4,4]],
 [[4,4,4,4],
  [4,4,4,4]]]

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. The concept of a tensor product is a dense crossroad, and a complete treatment is elsewhere. To quote the wiki article:

... 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.

>>> x = array [1,2,3] :: Array Vec.Vector '[3] Int
>>> pretty $ expand (*) x x
[[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 @[2,2] :: Array Vec.Vector [2,2] [Int]
>>> pretty $ 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.

>>> pretty $ expand (,) v (fmap (+3) v)
[[(0,3),(0,4),(0,5)],
 [(1,3),(1,4),(1,5)],
 [(2,3),(2,4),(2,5)]]

>>> pretty $ coexpand (,) v (fmap (+3) v)
[[(0,3),(1,3),(2,3)],
 [(0,4),(1,4),(2,4)],
 [(0,5),(1,5),(2,5)]]

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.

>>> pretty $ contract (Dims @[1,2]) sum (expand (*) m (transpose m))
[[5,14],
 [14,50]]

Expand two arrays and then contract the result using the supplied matching dimensions.

>>> pretty $ prod (Dims @'[1]) (Dims @'[0]) sum (*) (range @Vec.Vector @[2,3]) (range @Vec.Vector @[3,2])
[[10,13],
 [28,40]]

With full laziness, this computation would be equivalent to:

f . diag <$> extracts (Dims @ds') (expand g a b)

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

matrix multiplication

>>> pretty $ dot sum (*) m (transpose m)
[[5,14],
 [14,50]]

inner product

>>> pretty $ dot sum (*) v v
5

matrix-vector multiplication Note that an Array with shape [3] is neither a row vector nor column vector.

>>> pretty $ dot sum (*) v (transpose m)
[5,14]

>>> pretty $ dot sum (*) m v
[5,14]

Array multiplication.

matrix multiplication

>>> pretty $ mult m (transpose m)
[[5,14],
 [14,50]]

inner product

>>> pretty $ mult v v
5

matrix-vector multiplication

>>> pretty $ mult v (transpose m)
[5,14]

>>> pretty $ mult m v
[5,14]

windows xs are xs-sized windows of an array

>>> shape $ windows (Dims @[2,2]) (range @Vec.Vector @[4,3,2])
[3,2,2,2,2]