Version 12 (modified by chak, 2 years ago)

--

# The VECTORISE pragma

The vectoriser needs to know about all types and functions whose vectorised variants are directly implemented by the DPH library (instead of generated by the vectoriser), and it needs to know what the vectorised versions are. That is the purpose of the VECTORISE pragma (which comes in in number of flavours).

## The basic VECTORISE pragma for values

Given a function f, the vectoriser generates a vectorised version f_v, which comprises the original, scalar version of the function and a second version lifted into array space. The lifted version operates on arrays of inputs and produces arrays of results in one parallel computation. The original function name is, then, rebound to use the scalar version referred to by f_v. This differs from the original in that it uses vectorised versions for any embedded parallel array computations.

However, if a variable f is accompanied by a pragma of the form

```{-# VECTORISE f = e #-}
```

then the vectoriser defines f_v = e and refrains from rebinding f. This implies that for f :: t, e's type is the t vectorised (in particular), e's type uses the array closure type (:->) instead of the vanilla function space (->). The vectoriser checks that e has the appropriate type.

Caveat: Currently, the type is indeed checked by the vectoriser by comparing Core types. It would be better to perform that check in the type checker to instantiate the type of f_v appropriately if it is overly general. At the moment, the vectorised version of t and the inferred type of e need to exactly match up (including all dictionaries and their order).

## The NOVECTORISE pragma for values

If a variable f is accompanied by a pragma

```{-# NOVECTORISE f #-}
```

then it is ignored by the vectoriser — i.e., no function f_v is generated and f is left untouched.

Caveat: If f's definition contains bindings that are being floated to the toplevel, those bindings will still be vectorised.

## The VECTORISE SCALAR pragma for functions

Functions that contain no array computations, especially if they are cheap (such as (+)), should not be vectorised, but applied by simply mapping them over an array. This could be achieved by using the VECTORISE pragma with an appropriate right-hand side, but leads to repetitive code that we rather like the compiler to generate.

If a unary function f is accompanied by a pragma

```{-# VECTORISE SCALAR f #-}
```

then the vectoriser generates

```f_v = closure1 f (scalar_map f)
```

and keeps f unchanged.

For a binary function, it generates

```f_v = closure2 f (scalar_zipWith f)
```

for a tertiary function, it generates

```f_v = closure3 f (scalar_zipWith3 f)
```

and so on. (The variable f must have a proper function type.)

## The basic VECTORISE pragma for type constructors

```{-# VECTORISE type T = ty #-}
```

TODO:

• This isn' fully implemented yet.
• We probably want two variants: one which just gives a tycon to vectorise and one also giving the vectorised tycon/type. The first variant matches the default behaviour for locally defined data types, but enables to vectorise imported data types in subsequent modules. (Eg, to vectorise data types from the Prelude without changing —or vectorising— the Prelude itself.)
• Maybe don't have a rhs, but make this pragma mean that T should be vectorised as if the module containing T would have been vectorised. (Post-hoc vectorisation of a data type.)

## The VECTORISE SCALAR pragma for type constructors

For a type constructor T, the pragma

```{-# VECTORISE SCALAR T #-}
```

indicates that the type is scalar; i.e., it has no embedded arrays. Note that the type cannot be parameterised (as we could not rule out that any of the type parameters at a usage site is an array type.)

The type constructor T must be in scope, but it may be imported. The PData and PRepr instances for T need to be manually defined. (For types that the vectorised automatically determines that they don't need a vectorised version instances for PData and PRepr are still generated automatically.)

TODO:

• For type constructors identified with this pragma, can we generate an instance of the Scalar type class automatically (instead of relying on it being in the library)?