Version 52 (modified by chak, 7 months 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.

We have got two exceptions to this rule. Firstly, if the body of a function f is scalar —i.e., it does not involve any parallel array computations— then we leave it as is and omit the generation of f_v. Whether a function is scalar is determined by the rules described in the Vectorisation Avoidance paper.

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

This pragma can also be used for imported functions f. In this case, f_v and a suitable vectorisation mapping of f to f_v is exported implicitly — just like RULES applied to imported identifiers. By vectorising imported functions, we can vectorise functions of modules that have not been compiled with -fvectorise. This is crucial to using the standard Prelude in vectorised code.

IMPLEMENTATION RESTRICTION: Currently the right-hand side of the equation —i.e., e— may only be a simple identifier and it must be at the correct type instance. More precisely, the Core type of the right-hand side must be identical to the vectorised version of t.

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

This pragma can only be used for bindings in the current module (exactly like an INLINE pragma).

Caveat: If f's definition contains bindings that are being floated to the toplevel, those bindings may still be vectorised. (TODO: We might want to ensure that we never float anything out of (at least, those) bindings before the vectoriser is invoked.)

Removed.

## The basic VECTORISE pragma for type constructors

### Without right-hand side

For a type constructor T, the pragma

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

indicates that the type T should be automatically vectorised even if it is imported. This is the default for all data types declared in the current module. If the type embeds no parallel arrays, no special vectorised representation will be generated.

The type constructor T must be in scope, but it may be imported. PData and PRepr instances are automatically generated by the vectoriser.

Examples are the vectorisation of types, such as Maybe and [], defined in the Prelude.

### With right-hand side

For a type constructor T, the pragma

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

directs the vectoriser to replace T by T' in vectorised code. Vectorisation of T is abstract in that constructors of T may not occur in vectorised code.

The type constructor T must be in scope, but it may be imported. PData and PRepr instances must be explicitly defined — they are not automatically generated.

An example is the vectorisation of parallel arrays, where [::] is replaced by PArray during vectorisation, but the vectoriser never looks at the representation of [::].

## The VECTORISE SCALAR pragma for type constructors

All types imported from modules that have not been vectorised are regarded to be scalar types, and they can be used in encapsulated scalar code. If custom instances for the PData and PRepr classes are provided, these types can also be used in vectorisation code. The latter types have no specialised vectorised representation (as they are scalar) and are abstract; i.e., their constructors cannot be used in vectorised code. An example is the treatment of Int. Ints can be used in vectorised code and remain unchanged by vectorisation. However, the representation of Int by the I# data constructor wrapping an Int# is not exposed in vectorised code. Instead, computations involving the representation need to be confined to scalar code.

### Without right-hand side

For a type constructor T, the pragma

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

indicates that the type T is scalar; i.e., it cannot have any embedded arrays. Hence, the type T represents itself in vectorised code. (No special vectorised version needs to be generated.)

The type constructor T must be in scope, but it may be imported. PData and PRepr instances for T need to be manually defined if needed at all. (This is the fundamental difference to types for which the vectoriser determines automatically that they don't need a vectorised version: for the latter, the vectoriser automatically generates instances for PData and PRepr.)

An example is the handling of Bool, which is scalar and represents itself in vectorised code, but we want to use the custom instances of 'PData' and 'PRepr' defined in the DPH libraries.

### With right-hand side

For a type constructor T, the pragma

```{-# VECTORISE SCALAR type T = T' #-}
```

directs the vectoriser to replace T by T' in vectorised code, but the type is abstract — i.e., its constructors cannot be used in vectorised code. Although, the representation of the type changes during vectorisation, it is still regarded as scalar, and hence, can be used in encapsulated scalar code.

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.

An example is the handling of (->), which the vectoriser maps to (:->), but it never looks at the implementation of (->) and allows its use in encapsulated scalar code.

## The NOVECTORISE pragma for types

If a type constructor T is accompanied by a pragma

```{-# NOVECTORISE type T #-}
```

then it is ignored by the vectoriser — i.e., no type T_v and no class instances are generated.

This pragma can only be used for definitions in the current module.

TODO:

• Not implemented yet.

## The VECTORISE pragma for type classes

For a type class C, the pragma

```{-# VECTORISE class C #-}
```

indicates that the class C should be automatically vectorised, even if it is imported. This is the default for all classes declared in the current module.

The class C must be in scope, but it may be imported. 'PData' and 'PRepr' instances are generally not used for type classes and their dictionary representations.

An example is the handling of Eq.

TODO:

• We want something like {-# VECTORISE class C = C' #-} (but what about the instances?)

## The VECTORISE SCALAR pragma for class instances

For a class instance C t, the pragma

```{-# VECTORISE SCALAR instance C t #-}
```

indicates that the instance dfun C t should vectorised by proceeding as for VECTORISE SCALAR on each individual class method of C.

C t must exactly match a single instance declaration provided for C.

An example is {-# VECTORISE SCALAR instance Num Int #-}.

RESTRICTION: Instance dictionaries vectorised with this pragma can not be mutually recursive. (They may be recursive.)

TODO:

• This pragma should now be redundant, as uses of unvectorised class instances should just be encapsulated. (Do we still need the VECTRORISE class pragma? Probably only if we want to allow custom instances in vectorised modules.)

## Vectorising imported definitions

The various VECTORISE pragmas can be applied to imported identifiers (both variables and types). The resulting vectorisation mappings and the vectorised version of the identifier will be implicitly exported — much like it is the case for RULES defined on imported identifiers.