A scalar expression in Halide.

To have a nice experience writing arithmetic expressions in terms of Exprs, we want to derive Num, Floating etc. instances for Expr. Unfortunately, that means that we encode Expr, Var, RVar, and ScalarParam by the same type, and passing an Expr to a function that expects a Var will produce a runtime error.

A Var.

An RVar.

Either Var or RVar.

Specifies that a type is supported by Halide.

Create a scalar expression from a Haskell value.

Create a named index variable.

Create a named reduction variable.

For more information about reduction variables, see Halide::RDom.

Return an undef value of the given type.

For more information, see Halide::undef.

Cast a scalar expression to a different type.

Use TypeApplications with this function, e.g. cast @Float x.

Similar to the standard bool function from Prelude except that it's lifted to work with Expr types.

Convert expression to integer immediate.

Tries to extract the value of an expression if it is a compile-time constant. If the expression isn't known at compile-time of the Halide pipeline, returns Nothing.

Print the expression to stdout when it's evaluated.

This is useful for debugging Halide pipelines.

Evaluate a scalar expression.

It should contain no parameters. If it does contain parameters, an exception will be thrown.

== but lifted to return an Expr.

/= but lifted to return an Expr.

< but lifted to return an Expr.

<= but lifted to return an Expr.

> but lifted to return an Expr.

>= but lifted to return an Expr.

A function in Halide. Conceptually, it can be thought of as a lazy n-dimensional buffer of type a.

This is a wrapper around the Halide::Func C++ type.

Function type. It can either be FuncTy which means that we have defined the function ourselves, or ParamTy which means that it's a parameter to our pipeline.

A single definition of a Func.

Define a Halide function.

define "f" i e defines a Halide function called "f" such that f[i] = e.

Here, i is an n-element tuple of Var, i.e. the following are all valid:

>>> [x, y, z] <- mapM mkVar ["x", "y", "z"]
>>> f1 <- define "f1" x (0 :: Expr Float)
>>> f2 <- define "f2" (x, y) (0 :: Expr Float)
>>> f3 <- define "f3" (x, y, z) (0 :: Expr Float)

Create an update definition for a Halide function.

update f i e creates an update definition for f that performs f[i] = e.

Apply a Halide function. Conceptually, f ! i is equivalent to f[i], i.e. indexing into a lazy array.

Get the index arguments of the function.

The returned list contains exactly n elements.

Return True when the function has update definitions, False otherwise.

Get a handle to an update step for the purposes of scheduling it.

An n-dimensional buffer of elements of type a.

Most pipelines use Ptr (HalideBuffer n a) for input and output array arguments.

Temporary allocate a CPU buffer.

This is useful for testing and debugging when you need to allocate an output buffer for your pipeline. E.g.

allocaCpuBuffer [3, 3] $ out -> do
  myKernel out                -- fill the buffer
  print =<< peekToList out  -- print it for debugging

Specifies that a can be converted to a list. This is very similar to IsList except that we read the list from a Ptr rather than converting directly.

Specifies that a type t can be used as an n-dimensional Halide buffer with elements of type a.

Treat a type t as a HalideBuffer and use it in an IO action.

This function is a simple wrapper around withHalideBufferImpl, except that the order of type parameters is reversed. If you have TypeApplications extension enabled, this allows you to write withHalideBuffer 3 Float yourBuffer to specify that you want a 3-dimensional buffer of Float.

Construct a HalideBuffer from a pointer to the data, a list of extents, and a list of strides, and use it in an IO action.

This function throws a runtime error if the number of dimensions does not match n.

Similar to bufferFromPtrShapeStrides, but assumes column-major ordering of data.

Evaluate this function over a rectangular domain.

Wrap a buffer into a Func.

Suppose, we are defining a pipeline that adds together two vectors, and we'd like to call realize to evaluate it directly, how do we pass the vectors to the Func? asBufferParam allows to do exactly this.

asBuffer [1, 2, 3] $ \a ->
  asBuffer [4, 5, 6] $ \b -> do
    i <- mkVar "i"
    f <- define "vectorAdd" i $ a ! i + b ! i
    realize f [3] $ \result ->
      print =<< peekToList f

Convert a function that builds a Halide Func into a normal Haskell function acccepting scalars and HalideBuffers.

For example:

builder :: Expr Float -> Func 'ParamTy 1 Float -> IO (Func 'FuncTy 1 Float)
builder scale inputVector = do
  i <- mkVar "i"
  scaledVector <- define "scaledVector" i $ scale * inputVector ! i
  pure scaledVector

The builder function accepts a scalar parameter and a vector and scales the vector by the given factor. We can now pass builder to compile:

scaler <- compile builder
withHalideBuffer 1 Float [1, 1, 1] $ inputVector ->
  allocaCpuBuffer [3] $ outputVector -> do
    -- invoke the kernel
    scaler 2.0 inputVector outputVector
    -- print the result
    print =<< peekToList outputVector

A view pattern to specify the name of a buffer argument.

Example usage:

>>> :{
_ <- compile $ \(buffer "src" -> src) -> do
  i <- mkVar "i"
  define "dest" i $ (src ! i :: Expr Float)
:}

or if we want to specify the dimension and type, we can use type applications:

>>> :{
_ <- compile $ \(buffer @1 @Float "src" -> src) -> do
  i <- mkVar "i"
  define "dest" i $ src ! i
:}

Similar to buffer, but for scalar parameters.

Example usage:

>>> :{
_ <- compile $ \(scalar @Float "a" -> a) -> do
  i <- mkVar "i"
  define "dest" i $ a
:}

Information about a buffer's dimension, such as the min, extent, and stride.

Get a particular dimension of a pipeline parameter.

Set the min in a given dimension to equal the given expression. Setting the mins to zero may simplify some addressing math.

For more info, see Halide::Internal::Dimension::set_min.

Set the extent in a given dimension to equal the given expression.

Halide will generate runtime errors for Buffers that fail this check.

For more info, see Halide::Internal::Dimension::set_extent.

Set the stride in a given dimension to equal the given expression.

This is particularly useful to set when vectorizing. Known strides for the vectorized dimensions generate better code.

For more info, see Halide::Internal::Dimension::set_stride.

Set estimates for autoschedulers.

The compilation target.

This is the Haskell counterpart of Halide::Target.

Return the target that Halide will use by default.

If the HL_TARGET environment variable is set, it uses that. Otherwise, it returns the target corresponding to the host machine.

Get the default GPU target. We first check for CUDA and then for OpenCL. If neither of the two is usable, Nothing is returned.

Similar to compile, but the first argument lets you explicitly specify the compilation target.

An enum describing the type of device API.

This is the Haskell counterpart of Halide::DeviceAPI.

Note: generated automatically using

cat $HALIDE_PATH/include/Halide.h | \
  grep -E '.* = halide_target_feature_.*' | \
  sed -E 's/^\s*(.*) = .*$/  | \1/g' | \
  grep -v FeatureEnd

Add a feature to target.

Return whether a GPU compute runtime is enabled.

Checks whether gpuBlocks and similar are going to work.

For more info, see Target::has_gpu_feature.

Attempt to sniff whether a given Target (and its implied DeviceAPI) is usable on the current host.

Note that a return value of True does not guarantee that future usage of that device will succeed; it is intended mainly as a simple diagnostic to allow early-exit when a desired device is definitely not usable.

Also note that this call is NOT threadsafe, as it temporarily redirects various global error-handling hooks in Halide.

Common scheduling functions

Different ways to handle a tail case in a split when the split factor does not provably divide the extent.

This is the Haskell counterpart of Halide::TailStrategy.

A reference to a site in a Halide statement at the top of the body of a particular for loop.

Different ways to handle the case when the start/end of the loops of stages computed with (fused) are not aligned.

Compute all of this function once ahead of time.

See Halide::Func::compute_root for more info.

Get the pure stage of a Func for the purposes of scheduling it.

Same as getLoopLevelAtStage except that the stage is -1.

Identify the loop nest corresponding to some dimension of some function.

Create and return a global identity wrapper, which wraps all calls to this Func by any other Func.

If a global wrapper already exists, returns it. The global identity wrapper is only used by callers for which no custom wrapper has been specified.

Creates and returns a new identity Func that wraps this Func.

During compilation, Halide replaces all calls to this Func done by f with calls to the wrapper. If this Func is already wrapped for use in f, will return the existing wrapper.

For more info, see Halide::Func::in.

Declare that this function should be implemented by a call to halide_buffer_copy with the given target device API.

Asserts that the Func has a pure definition which is a simple call to a single input, and no update definitions. The wrapper Funcs returned by asUsed are suitable candidates. Consumes all pure variables, and rewrites the Func to have an extern definition that calls halide_buffer_copy.

Same as copyToDevice DeviceHost

Allocate storage for this function within a particular loop level.

Scheduling storage is optional, and can be used to separate the loop level at which storage is allocated from the loop level at which computation occurs to trade off between locality and redundant work.

For more info, see Halide::Func::store_at.

Schedule a function to be computed within the iteration over a given loop level.

For more info, see Halide::Func::compute_at.

Split a dimension by the given factor, then unroll the inner dimension.

This is how you unroll a loop of unknown size by some constant factor. After this call, var refers to the outer dimension of the split. unroll :: (KnownNat n, IsHalideType a) => TailStrategy -> Func t n a -> Expr Int32 -- ^ Variable var to vectorize -> Expr Int32 -- ^ Split factor -> IO () unroll strategy func var factor = withFunc func $ f -> asVarOrRVar var $ x -> asExpr factor $ n -> [C.throwBlock| void { $(Halide::Func* f)->unroll(*$(Halide::VarOrRVar* x), *$(Halide::Expr* n), static_castHalide::TailStrategy($(int tail))); } |] where tail = fromIntegral (fromEnum strategy)

Reorder variables to have the given nesting order, from innermost out. reorder :: forall t n a i ts . ( IsTuple (Arguments ts) i , All ((~) (Expr Int32)) ts , Length ts ~ n , KnownNat n , IsHalideType a ) => Func t n a -> i -> IO () reorder func args = asVectorOf @((~) (Expr Int32)) asVarOrRVar (fromTuple args) $ v -> do withFunc func $ f -> [C.throwBlock| void { $(Halide::Func* f)->reorder(*$(std::vectorHalide::VarOrRVar* v)); } |]

Statically declare the range over which the function will be evaluated in the general case.

This provides a basis for the auto scheduler to make trade-offs and scheduling decisions. The auto generated schedules might break when the sizes of the dimensions are very different from the estimates specified. These estimates are used only by the auto scheduler if the function is a pipeline output.

Statically declare the range over which a function should be evaluated.

This can let Halide perform some optimizations. E.g. if you know there are going to be 4 color channels, you can completely vectorize the color channel dimension without the overhead of splitting it up. If bounds inference decides that it requires more of this function than the bounds you have stated, a runtime error will occur when you try to run your pipeline.

Write out the loop nests specified by the schedule for this function.

Helpful for understanding what a schedule is doing.

For more info, see Halide::Func::print_loop_nest printLoopNest :: (KnownNat n, IsHalideType r) => Func n r -> IO () printLoopNest func = withFunc func $ f -> [C.exp| void { $(Halide::Func* f)->print_loop_nest() } |]

Get the loop nests specified by the schedule for this function.

Helpful for understanding what a schedule is doing.

For more info, see Halide::Func::print_loop_nest

Get the internal representation of lowered code.

Useful for analyzing and debugging scheduling. Can emit HTML or plain text.

Format in which to return the lowered code.

Haskell counterpart of halide_trace_event_code_t.

Specifies that there is an isomorphism between a type a and a tuple t.

We use this class to convert between Arguments and normal tuples.

Type family that maps Arguments ts to the corresponding tuple type.

Type family that maps tuples to the corresponding Arguments ts type. This is essentially the inverse of ToTuple.

Specifies that i is a tuple of Expr Int32.

ts are deduced from i, so you don't have to specify them explicitly.

A type family that returns the length of a type-level list.

Apply constraint to all types in a list.

A test that tries to compile and run a Halide pipeline using FeatureCUDA.

This is implemented fully in C++ to make sure that we test the installation rather than our Haskell code.

On non-NixOS systems one should do the following:

nixGLNvidia cabal repl --ghc-options='-fobject-code -O0'
ghci> testCUDA

Similar to testCUDA but for FeatureOpenCL.