accelerate-0.8.1.0: An embedded language for accelerated array processing

Portabilitynon-portable (GHC extensions)
Stabilityexperimental
MaintainerManuel M T Chakravarty <chak@cse.unsw.edu.au>

Data.Array.Accelerate

Contents

Description

This module defines an embedded language of array computations for high-performance computing. Computations on multi-dimensional, regular arrays are expressed in the form of parameterised collective operations (such as maps, reductions, and permutations). These computations are online compiled and executed on a range of architectures.

Abstract interface

The types representing array computations are only exported abstractly  i.e., client code can generate array computations and submit them for for execution, but it cannot inspect these computations. This is to allow for more flexibility for future extensions of this library.

Code execution

Access to the various backends is via a run function in backend-specific toplevel modules. Currently, we have the following:

Synopsis

Scalar element types

data Int

A fixed-precision integer type with at least the range [-2^29 .. 2^29-1]. The exact range for a given implementation can be determined by using Prelude.minBound and Prelude.maxBound from the Prelude.Bounded class.

Instances

Bounded Int 
Enum Int 
Eq Int 
Integral Int 
Num Int 
Ord Int 
Real Int 
Show Int 
Ix Int 
Typeable Int 
Storable Int 
Bits Int 
IsScalar Int 
IsBounded Int 
IsNum Int 
IsIntegral Int 
ArrayElem Int 
Ix Int 
Shape Int 
ShapeBase Int 
Elem Int 
IArray UArray Int 
MArray (STUArray s) Int (ST s) 
SliceIx sl => SliceIx (sl, Int) 
Ix ix => Ix (ix, Int) 
Ix (Int, Int) 
Ix (Int, Int, Int) 
Ix (Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int, Int, Int, Int, Int) 

data Word

A Word is an unsigned integral type, with the same size as Int.

data Float

Single-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE single-precision type.

data Double

Double-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE double-precision type.

Scalar type classes

Array data types

data Array dim e Source

Multi-dimensional arrays for array processing

  • If device and host memory are separate, arrays will be transferred to the device when necessary (if possible asynchronously and in parallel with other tasks) and cached on the device if sufficient memory is available.

Instances

Show (Array dim e) 
Delayable (Array dim e) 
Arrays (Array dim e) 

type Scalar e = Array DIM0 eSource

Scalars

type Vector e = Array DIM1 eSource

Vectors

type Segments = Vector IntSource

Segment descriptor

Array element types

class (Show a, Typeable a, Typeable (ElemRepr a), Typeable (ElemRepr' a), ArrayElem (ElemRepr a), ArrayElem (ElemRepr' a)) => Elem a Source

Class that characterises the types of values that can be array elements.

Instances

Elem Bool 
Elem Char 
Elem Double 
Elem Float 
Elem Int 
Elem Int8 
Elem Int16 
Elem Int32 
Elem Int64 
Elem Word 
Elem Word8 
Elem Word16 
Elem Word32 
Elem Word64 
Elem () 
Elem All 
(Elem a, Elem b) => Elem (a, b) 
(Elem a, Elem b, Elem c) => Elem (a, b, c) 
(Elem a, Elem b, Elem c, Elem d) => Elem (a, b, c, d) 
(Elem a, Elem b, Elem c, Elem d, Elem e) => Elem (a, b, c, d, e) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f) => Elem (a, b, c, d, e, f) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g) => Elem (a, b, c, d, e, f, g) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g, Elem h) => Elem (a, b, c, d, e, f, g, h) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g, Elem h, Elem i) => Elem (a, b, c, d, e, f, g, h, i) 

Array shapes & indices

class (Shape ix, Ix (ElemRepr ix)) => Ix ix whereSource

Shapes and indices of multi-dimensional arrays

Methods

dim :: ix -> IntSource

Number of dimensions of a shape or index (>= 0)

size :: ix -> IntSource

Instances

Ix Int 
Ix () 
Ix (Int, Int) 
Ix (Int, Int, Int) 
Ix (Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int, Int, Int, Int) 
Ix (Int, Int, Int, Int, Int, Int, Int, Int, Int) 

data All Source

Identifier for entire dimensions in slice descriptors

Constructors

All 

Instances

Show All 
Typeable All 
Shape All 
ShapeBase All 
Elem All 

class (Shape sl, SliceIx (ElemRepr sl), Ix (Slice sl), Ix (CoSlice sl), Ix (SliceDim sl), SliceIxConv sl) => SliceIx sl whereSource

Slices -aka generalised indices- as n-tuples and mappings of slice indicies to slices, co-slices, and slice dimensions

Associated Types

type Slice sl :: *Source

type CoSlice sl :: *Source

type SliceDim sl :: *Source

Methods

sliceIndex :: sl -> SliceIndex (ElemRepr sl) (Slice (ElemRepr sl)) (CoSlice (ElemRepr sl)) (SliceDim (ElemRepr sl))Source

Instances

(Shape sl, SliceIx (ElemRepr sl), Ix (Slice sl), Ix (CoSlice sl), Ix (SliceDim sl), SliceIxConv sl) => SliceIx sl 

type DIM0 = ()Source

type DIM2 = (Int, Int)Source

type DIM3 = (Int, Int, Int)Source

type DIM4 = (Int, Int, Int, Int)Source

type DIM5 = (Int, Int, Int, Int, Int)Source

Operations to use Accelerate arrays from plain Haskell

arrayShape :: Ix dim => Array dim e -> dimSource

Array shape in plain Haskell code

indexArray :: Array dim e -> dim -> eSource

Array indexing in plain Haskell code

fromIArray :: (IArray a e, Ix dim, Ix dim, Elem e) => a dim e -> Array dim eSource

Convert an IArray to an accelerated array.

toIArray :: (IArray a e, Ix dim, Ix dim, Elem e) => Array dim e -> a dim eSource

Convert an accelerated array to an IArray

fromList :: (Ix dim, Elem e) => dim -> [e] -> Array dim eSource

Convert a list (with elements in row-major order) to an accelerated array.

toList :: forall dim e. Array dim e -> [e]Source

Convert an accelerated array to a list in row-major order.

The Accelerate language

Array and scalar expressions

data Acc a Source

Array-valued collective computations

Instances

Show (Acc as) 

data Exp t Source

Scalar expressions used to parametrise collective array operations

Instances

Elem a => Stencil DIM1 a (Exp a, Exp a, Exp a) 
Elem a => Stencil DIM1 a (Exp a, Exp a, Exp a, Exp a, Exp a) 
Elem a => Stencil DIM1 a (Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a) 
Elem a => Stencil DIM1 a (Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a) 
(Elem t, IsBounded t) => Bounded (Exp t) 
(Elem t, IsScalar t) => Enum (Exp t) 
(Elem t, IsScalar t) => Eq (Exp t) 
(Elem t, IsFloating t) => Floating (Exp t) 
(Elem t, IsFloating t) => Fractional (Exp t) 
(Elem t, IsIntegral t) => Integral (Exp t) 
(Elem t, IsNum t) => Num (Exp t) 
(Elem t, IsScalar t) => Ord (Exp t) 
(Elem t, IsNum t) => Real (Exp t) 
(Elem t, IsFloating t) => RealFloat (Exp t) 
(Elem t, IsFloating t) => RealFrac (Exp t) 
Show (Exp a) 
(Elem t, IsNum t, IsIntegral t) => Bits (Exp t) 
(Elem a, Elem b) => Tuple (Exp a, Exp b) 
(Elem a, Elem b, Elem c) => Tuple (Exp a, Exp b, Exp c) 
(Elem a, Elem b, Elem c, Elem d) => Tuple (Exp a, Exp b, Exp c, Exp d) 
(Elem a, Elem b, Elem c, Elem d, Elem e) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e, Exp f) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e, Exp f, Exp g) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g, Elem h) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e, Exp f, Exp g, Exp h) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g, Elem h, Elem i) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e, Exp f, Exp g, Exp h, Exp i) 

Stencil specification

data Boundary a Source

Boundary condition specification for stencil operations.

Constructors

Clamp

clamp coordinates to the extent of the array

Mirror

mirror coordinates beyond the array extent

Wrap

wrap coordinates around on each dimension

Constant a

use a constant value for outlying coordinates

Instances

Show a => Show (Boundary a) 

class (Elem (StencilRepr dim stencil), Stencil dim a (StencilRepr dim stencil)) => Stencil dim a stencil Source

Smart constructors for stencil reification -------------------------------------------

Instances

(Stencil DIM2 a row1, Stencil DIM2 a row2, Stencil DIM2 a row3) => Stencil DIM3 a (row1, row2, row3) 
(Stencil DIM1 a row2, Stencil DIM1 a row1, Stencil DIM1 a row0) => Stencil DIM2 a (row2, row1, row0) 
Elem a => Stencil DIM1 a (Exp a, Exp a, Exp a) 
(Stencil DIM2 a row1, Stencil DIM2 a row2, Stencil DIM2 a row3, Stencil DIM2 a row4, Stencil DIM2 a row5) => Stencil DIM3 a (row1, row2, row3, row4, row5) 
(Stencil DIM1 a row1, Stencil DIM1 a row2, Stencil DIM1 a row3, Stencil DIM1 a row4, Stencil DIM1 a row5) => Stencil DIM2 a (row1, row2, row3, row4, row5) 
Elem a => Stencil DIM1 a (Exp a, Exp a, Exp a, Exp a, Exp a) 
(Stencil DIM2 a row1, Stencil DIM2 a row2, Stencil DIM2 a row3, Stencil DIM2 a row4, Stencil DIM2 a row5, Stencil DIM2 a row6, Stencil DIM2 a row7) => Stencil DIM3 a (row1, row2, row3, row4, row5, row6, row7) 
(Stencil DIM1 a row1, Stencil DIM1 a row2, Stencil DIM1 a row3, Stencil DIM1 a row4, Stencil DIM1 a row5, Stencil DIM1 a row6, Stencil DIM1 a row7) => Stencil DIM2 a (row1, row2, row3, row4, row5, row6, row7) 
Elem a => Stencil DIM1 a (Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a) 
(Stencil DIM2 a row1, Stencil DIM2 a row2, Stencil DIM2 a row3, Stencil DIM2 a row4, Stencil DIM2 a row5, Stencil DIM2 a row6, Stencil DIM2 a row7, Stencil DIM2 a row8, Stencil DIM2 a row9) => Stencil DIM3 a (row1, row2, row3, row4, row5, row6, row7, row8, row9) 
(Stencil DIM1 a row1, Stencil DIM1 a row2, Stencil DIM1 a row3, Stencil DIM1 a row4, Stencil DIM1 a row5, Stencil DIM1 a row6, Stencil DIM1 a row7, Stencil DIM1 a row8, Stencil DIM1 a row9) => Stencil DIM2 a (row1, row2, row3, row4, row5, row6, row7, row8, row9) 
Elem a => Stencil DIM1 a (Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a) 

Common stencil types

type Stencil3 a = (Exp a, Exp a, Exp a)Source

type Stencil5 a = (Exp a, Exp a, Exp a, Exp a, Exp a)Source

type Stencil7 a = (Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a)Source

type Stencil9 a = (Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a, Exp a)Source

Scalar introduction

constant :: Elem t => t -> Exp tSource

Constant scalar expression

Array introduction

use :: (Ix dim, Elem e) => Array dim e -> Acc (Array dim e)Source

Array inlet: makes an array available for processing using the Accelerate language; triggers asynchronous host->device transfer if necessary.

unit :: Elem e => Exp e -> Acc (Scalar e)Source

Scalar inlet: injects a scalar (or a tuple of scalars) into a singleton array for use in the Accelerate language.

Shape manipulation

reshape :: (Ix dim, Ix dim', Elem e) => Exp dim -> Acc (Array dim' e) -> Acc (Array dim e)Source

Change the shape of an array without altering its contents, where

 precondition: size dim == size dim'

Collective array operations

slice :: (SliceIx slix, Elem e) => Acc (Array (SliceDim slix) e) -> Exp slix -> Acc (Array (Slice slix) e)Source

Index an array with a *generalised* array index (supplied as the second argument). The result is a new array (possibly a singleton) containing all dimensions in their entirety.

replicate :: (SliceIx slix, Elem e) => Exp slix -> Acc (Array (Slice slix) e) -> Acc (Array (SliceDim slix) e)Source

Replicate an array across one or more dimensions as specified by the *generalised* array index provided as the first argument.

For example, assuming arr is a vector (one-dimensional array),

 replicate (2, All, 3) arr

yields a three dimensional array, where arr is replicated twice across the first and three times across the third dimension.

zip :: (Ix dim, Elem a, Elem b) => Acc (Array dim a) -> Acc (Array dim b) -> Acc (Array dim (a, b))Source

Combine the elements of two arrays pairwise. The shape of the result is the intersection of the two argument shapes.

unzip :: (Ix dim, Elem a, Elem b) => Acc (Array dim (a, b)) -> (Acc (Array dim a), Acc (Array dim b))Source

The converse of zip, but the shape of the two results is identical to the shape of the argument.

map :: (Ix dim, Elem a, Elem b) => (Exp a -> Exp b) -> Acc (Array dim a) -> Acc (Array dim b)Source

Apply the given function elementwise to the given array.

zipWith :: (Ix dim, Elem a, Elem b, Elem c) => (Exp a -> Exp b -> Exp c) -> Acc (Array dim a) -> Acc (Array dim b) -> Acc (Array dim c)Source

Apply the given binary function elementwise to the two arrays. The extent of the resulting array is the intersection of the extents of the two source arrays.

scanl :: Elem a => (Exp a -> Exp a -> Exp a) -> Exp a -> Acc (Vector a) -> (Acc (Vector a), Acc (Scalar a))Source

Prescan of a vector. The type a together with the binary function (first argument) and value (second argument) must form a monoid; i.e., the function must be associative and the value must be its neutral element.

The resulting vector of prescan values has the same size as the argument vector. The resulting scalar is the reduction value.

scanr :: Elem a => (Exp a -> Exp a -> Exp a) -> Exp a -> Acc (Vector a) -> (Acc (Vector a), Acc (Scalar a))Source

The right-to-left dual of scanl.

fold :: (Ix dim, Elem a) => (Exp a -> Exp a -> Exp a) -> Exp a -> Acc (Array dim a) -> Acc (Scalar a)Source

Reduction of an array. The type a together with the binary function (first argument) and value (second argument) must form a monoid; i.e., the function must be associative and the value must be its neutral element.

foldSeg :: Elem a => (Exp a -> Exp a -> Exp a) -> Exp a -> Acc (Vector a) -> Acc Segments -> Acc (Vector a)Source

Segmented reduction.

permuteSource

Arguments

:: (Ix dim, Ix dim', Elem a) 
=> (Exp a -> Exp a -> Exp a)

combination function

-> Acc (Array dim' a)

array of default values

-> (Exp dim -> Exp dim')

permutation

-> Acc (Array dim a)

permuted array

-> Acc (Array dim' a) 

Forward permutation specified by an index mapping. The result array is initialised with the given defaults and any further values that are permuted into the result array are added to the current value using the given combination function.

The combination function must be associative. Elements that are mapped to the magic value ignore by the permutation function are being dropped.

backpermuteSource

Arguments

:: (Ix dim, Ix dim', Elem a) 
=> Exp dim'

shape of the result array

-> (Exp dim' -> Exp dim)

permutation

-> Acc (Array dim a)

permuted array

-> Acc (Array dim' a) 

Backward permutation

stencilSource

Arguments

:: (Ix dim, Elem a, Elem b, Stencil dim a stencil) 
=> (stencil -> Exp b)

stencil function

-> Boundary a

boundary condition

-> Acc (Array dim a)

source array

-> Acc (Array dim b)

destination array

Map a stencil over an array. In contrast to map, the domain of a stencil function is an entire neighbourhood of each array element. Neighbourhoods are sub-arrays centred around a focal point. They are not necessarily rectangular, but they are symmetric in each dimension and have an extent of at least three in each dimensions  due to the symmetry requirement, the extent is necessarily odd. The focal point is the array position that is determined by the stencil.

For those array positions where the neighbourhood extends past the boundaries of the source array, a boundary condition determines the contents of the out-of-bounds neighbourhood positions.

stencil2Source

Arguments

:: (Ix dim, Elem a, Elem b, Elem c, Stencil dim a stencil1, Stencil dim b stencil2) 
=> (stencil1 -> stencil2 -> Exp c)

binary stencil function

-> Boundary a

boundary condition #1

-> Acc (Array dim a)

source array #1

-> Boundary b

boundary condition #2

-> Acc (Array dim b)

source array #2

-> Acc (Array dim c)

destination array

Map a binary stencil of an array. The extent of the resulting array is the intersection of the extents of the two source arrays.

Tuple construction and destruction

class Tuple tup whereSource

Associated Types

type TupleT tup Source

Methods

tuple :: tup -> TupleT tupSource

Turn a tuple of scalar expressions into a scalar expressions that yields a tuple.

untuple :: TupleT tup -> tupSource

Turn a scalar expression that yields a tuple into a tuple of scalar expressions.

Instances

(Elem a, Elem b) => Tuple (Exp a, Exp b) 
(Elem a, Elem b, Elem c) => Tuple (Exp a, Exp b, Exp c) 
(Elem a, Elem b, Elem c, Elem d) => Tuple (Exp a, Exp b, Exp c, Exp d) 
(Elem a, Elem b, Elem c, Elem d, Elem e) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e, Exp f) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e, Exp f, Exp g) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g, Elem h) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e, Exp f, Exp g, Exp h) 
(Elem a, Elem b, Elem c, Elem d, Elem e, Elem f, Elem g, Elem h, Elem i) => Tuple (Exp a, Exp b, Exp c, Exp d, Exp e, Exp f, Exp g, Exp h, Exp i) 

fst :: forall a b. (Elem a, Elem b) => Exp (a, b) -> Exp aSource

Extract the first component of a pair

snd :: forall a b. (Elem a, Elem b) => Exp (a, b) -> Exp bSource

Extract the second component of a pair

curry :: (Elem a, Elem b) => (Exp (a, b) -> Exp c) -> Exp a -> Exp b -> Exp cSource

Converts an uncurried function to a curried function

uncurry :: (Elem a, Elem b) => (Exp a -> Exp b -> Exp c) -> Exp (a, b) -> Exp cSource

Converts a curried function to a function on pairs

Conditional expressions

(?) :: Elem t => Exp Bool -> (Exp t, Exp t) -> Exp tSource

Conditional expression.

Array operations with a scalar result

(!) :: (Ix dim, Elem e) => Acc (Array dim e) -> Exp dim -> Exp eSource

Expression form that extracts a scalar from an array.

shape :: (Ix dim, Elem dim) => Acc (Array dim e) -> Exp dimSource

Methods of H98 classes that we need to redefine as their signatures change

(==*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp BoolSource

Equality lifted into Accelerate expressions.

(/=*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp BoolSource

Inequality lifted into Accelerate expressions.

(<*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp BoolSource

Smaller-than lifted into Accelerate expressions.

(<=*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp BoolSource

Smaller-or-equal lifted into Accelerate expressions.

(>*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp BoolSource

Greater-than lifted into Accelerate expressions.

(>=*) :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp BoolSource

Greater-or-equal lifted into Accelerate expressions.

max :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp tSource

Determine the maximum of two scalars.

min :: (Elem t, IsScalar t) => Exp t -> Exp t -> Exp tSource

Determine the minimum of two scalars.

bit :: (Elem t, IsIntegral t) => Exp Int -> Exp tSource

setBit :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp tSource

clearBit :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp tSource

shift :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp tSource

shiftL :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp tSource

shiftR :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp tSource

rotate :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp tSource

rotateL :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp tSource

rotateR :: (Elem t, IsIntegral t) => Exp t -> Exp Int -> Exp tSource

Standard functions that we need to redefine as their signatures change

(&&*) :: Exp Bool -> Exp Bool -> Exp BoolSource

Conjunction

(||*) :: Exp Bool -> Exp Bool -> Exp BoolSource

Disjunction

not :: Exp Bool -> Exp BoolSource

Negation

Conversions

boolToInt :: Exp Bool -> Exp IntSource

Convert a Boolean value to an Int, where False turns into '0' and True into '1'.

intToFloat :: Exp Int -> Exp FloatSource

Convert an Int to a Float

roundFloatToInt :: Exp Float -> Exp IntSource

Round Float to Int

truncateFloatToInt :: Exp Float -> Exp IntSource

Truncate Float to Int

Constants

ignore :: Ix dim => Exp dimSource

Magic value identifying elements that are ignored in a forward permutation

Instances of Bounded, Enum, Eq, Ord, Bits, Num, Real, Floating,