Orthotope

Disclaimer

This is not an officially supported Google product.

Summary

This is a library for multi-dimensional arrays inspired by APL.

See also

The orthotope-hmatrix repo contains some more functionality.

Multi-dimensional arrays

Each array has a number of elements of the same type, and a shape. The shape can be described by a list of integers that gives the size for each of the dimensions. E.g. the array shape [2,3] is a 2x3 matrix (2 rows, 3 columns), and the shape [] is a single value (a scalar). The number of dimensions is called the rank of the array.

The shape may or may not be part of the type, depending on which version of the API you use.

API variants

The API comes in many variants, depending on how strongly typed it is and what the underlying storage is.

Types

• Dynamic, the shape is not part of the type, but is checked at runtime. E.g., Array Float is an array of Float which can have any shape.

• Ranked, the rank of the array is part of the type, but the actual sizes of the dimensions are checked at runtime. E.g., Array 2 Float is the type of 2-dimensional arrays (i.e., matrices) of Float.

• Shaped, the shape of the array is part of the type and is checked statically. E.g., Array [2,3] Float is the type of 2x3 arrays of Float.

Converting between these types is cheap since they all share the same underlying trepresentation.

Storage

Each of the type variants has several storage variants, indicated by a suffix of the module names.

• G The generic array type where you can provide your own storage.

• S Uses Data.Vector.Storable for storage.

• U Uses Data.Vector.Unboxed for storage.

• (empty suffix) Uses Data.Vector for storage.

Conversion between different storage types requires copying the data, so it is not a cheap operation.

API

The library API is mostly structural operations, i.e., operations that treat the elements in a uniform way. For more algorithmic operations, e.g., matrix multiplication, we suggest using a different library, like hmatrix.

Examples using Dynamic

Some preliminaries:

> import Data.Array.Dynamic
> import Text.PrettyPrint.HughesPJClass
> pp = putStrLn . prettyShow

An easy way to create an array from a list is to use fromList; the first argument is the shape of the array.

> m = fromList [2,3] [1..6]
> m
fromList [2,3] [1,2,3,4,5,6]
> shapeL m
[2,3]
> rank m
2
> size m
6

Arrays can be pretty printed. They are shown in the APL way: The innermost dimension on a line, the next dimension vertically, the next dimension vertically with an empty line in between, and so on. Normally there is a box drawn around the array, but this can be changed by lowering pretty printing level to pPrintPrec.

> pp m
┌─────┐
│1 2 3│
│4 5 6│
└─────┘

We can have an arbitrary number of dimensions.

> s = fromList [] [42]
> v = fromList [3] [7,8,9]
> a = fromList [2,3,4] [1..24]
> pp s
┌──┐
│42│
└──┘
> pp v
┌─────┐
│7 8 9│
└─────┘
> pp 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│
└───────────┘

Indexing into an array removes the outermost dimension of it by selecting a subarray with the given index.

> pp $ index v 1
┌─┐
│8│
└─┘
> shapeL $ index v 1
[]
> pp $ index a 1
┌───────────┐
│13 14 15 16│
│17 18 19 20│
│21 22 23 24│
└───────────┘
> pp $ a `index` 1 `index` 2 `index` 0
┌──┐
│21│
└──┘

The scalar and unScalar functions can be used to convert an element to/from and array.

> :type scalar 42
scalar 42 :: Num a => Array a
> :type index v 1
index v 1 :: Num a => Array a
> :type unScalar (index v 1)
unScalar (index v 1) :: Num a => a

The constant function makes an array with all identical elements.

> pp $ constant [2,3] 8
┌─────┐
│8 8 8│
│8 8 8│
└─────┘

Arrays are also instances of Functor, Foldable, and Traversable.

> pp $ fmap succ v
┌────────┐
│ 8  9 10│
└────────┘
> foldr (+) 0 a
300

The transpose operation can be used to rearrange the dimensions of an array. The first argument describes how to transpose.

> shapeL a
[2,3,4]
> shapeL (transpose [1,0,2] a)
[3,2,4]
> pp $ transpose [1,0,2] a
┌───────────┐
│ 1  2  3  4│
│13 14 15 16│
│           │
│ 5  6  7  8│
│17 18 19 20│
│           │
│ 9 10 11 12│
│21 22 23 24│
└───────────┘

The reshape operation keeps the elements of an array, but changes its shape.

> pp $ reshape [3,8] 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│
└───────────────────────┘

An array can be turned into an array of arrays, where the outermost array will have rank 1.

> pp $ unravel a
┌───────────────────────────┐
│┌───────────┐ ┌───────────┐│
││ 1  2  3  4│ │13 14 15 16││
││ 5  6  7  8│ │17 18 19 20││
││ 9 10 11 12│ │21 22 23 24││
│└───────────┘ └───────────┘│
└───────────────────────────┘

The foldr operation reduces an array to something of the element type. Using reduce you will instead get an array result.

> pp $ reduce (+) 0 a
┌───┐
│300│
└───┘

Note how this operated on the entire array. Using rerank it is possible to use a function "deeper down".

> pp $ rerank 1 (reduce (+) 0) a
┌───────┐
│ 78 222│
└───────┘
> pp $ rerank 2 (reduce (+) 0) a
┌────────┐
│10 26 42│
│58 74 90│
└────────┘
> pp $ rerank 3 (reduce (+) 0) 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│
└───────────┘

To reduce along some dimension(s) that are not the innermost we can make them innermost by transpostion. So to sum the columns:

> pp $ rerank 2 (reduce (+) 0) $ transpose [0,2,1] a
┌───────────┐
│15 18 21 24│
│51 54 57 60│
└───────────┘

Similar examples using Shaped

> import Data.Array.Shaped
> :set -XDataKinds
> :set -XTypeApplications

The shape is now given by the type.

> m :: Array [2,3] Integer; m = fromList [1..6]
> m
fromList @[2,3] [1,2,3,4,5,6]
> shapeL m
[2,3]
> rank m
2
> size m
6

The type information can be given in different ways.

> s :: Array '[] Integer; s = fromList [42]
> v = fromList [7,8,9] :: Array '[3] Integer
> m = fromList @[2,3,4] [1..24]

There are also numeric instances for shaped arrays. They allow pointwise arithmetic on arrays with the same shape. Numeric constants are automatically of the right shape.

> import Data.Array.Shaped.Instances
> pp $ v * 2
┌────────┐
│14 16 18│
└────────┘
> pp $ a + a
┌───────────┐
│ 2  4  6  8│
│10 12 14 16│
│18 20 22 24│
│           │
│26 28 30 32│
│34 36 38 40│
│42 44 46 48│
└───────────┘

What is value arguments for Dynamic arrays sometimes turn into type arguments for shaped arrays.

> pp $ reshape @[3,8] 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│
└───────────────────────┘