public static int Main(string[] args) { // We're going to define and schedule our gradient function in // several different ways, and see what order pixels are computed // in. var x = new HSVar("x"); var y = new HSVar("y"); // First we observe the default ordering. { var gradient = new HSFunc("gradient"); gradient[x, y] = x + y; gradient.TraceStores(); // By default we walk along the rows and then down the // columns. This means x varies quickly, and y varies // slowly. x is the column and y is the row, so this is a // row-major traversal. Console.WriteLine("Evaluating gradient row-major"); var output = gradient.Realize <int>(4, 4); // See figures/lesson_05_row_major.gif for a visualization of // what this did. // The equivalent C is: Console.WriteLine("Equivalent C:"); for (int yy = 0; yy < 4; yy++) { for (int xx = 0; xx < 4; xx++) { Console.WriteLine($"Evaluating at x = {xx}, y = {yy}: {xx + yy}"); } } Console.WriteLine("\n"); // Tracing is one useful way to understand what a schedule is // doing. You can also ask Halide to print out pseudocode // showing what loops Halide is generating: Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); // Because we're using the default ordering, it should print: // compute gradient: // for y: // for x: // gradient(...) = ... } // Reorder variables. { var gradient = new HSFunc("gradient_col_major"); gradient[x, y] = x + y; gradient.TraceStores(); // If we reorder x and y, we can walk down the columns // instead. The reorder call takes the arguments of the func, // and sets a new nesting order for the for loops that are // generated. The arguments are specified from the innermost // loop out, so the following call puts y in the inner loop: gradient.Reorder(y, x); // This means y (the row) will vary quickly, and x (the // column) will vary slowly, so this is a column-major // traversal. Console.WriteLine("Evaluating gradient column-major"); var output = gradient.Realize <int>(4, 4); // See figures/lesson_05_col_major.gif for a visualization of // what this did. Console.WriteLine("Equivalent C:"); for (int xx = 0; xx < 4; xx++) { for (int yy = 0; yy < 4; yy++) { Console.WriteLine($"Evaluating at x = {xx}, y = {yy}: {xx + yy}"); } } Console.WriteLine(); // If we print pseudo-code for this schedule, we'll see that // the loop over y is now inside the loop over x. Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); } // Split a variable into two. { var gradient = new HSFunc("gradient_split"); gradient[x, y] = x + y; gradient.TraceStores(); // The most powerful primitive scheduling operation you can do // to a var is to split it into inner and outer sub-variables: var x_outer = new HSVar("x_outer"); var x_inner = new HSVar("x_inner"); gradient.Split(x, x_outer, x_inner, 2); // This breaks the loop over x into two nested loops: an outer // one over x_outer, and an inner one over x_inner. The last // argument to split was the "split factor". The inner loop // runs from zero to the split factor. The outer loop runs // from zero to the extent required of x (4 in this case) // divided by the split factor. Within the loops, the old // variable is defined to be outer * factor + inner. If the // old loop started at a value other than zero, then that is // also added within the loops. Console.WriteLine("Evaluating gradient with x split into x_outer and x_inner "); var output = gradient.Realize <int>(4, 4); Console.WriteLine("Equivalent C:"); for (int yy = 0; yy < 4; yy++) { for (int xOuter = 0; xOuter < 2; xOuter++) { for (int xInner = 0; xInner < 2; xInner++) { int xx = xOuter * 2 + xInner; Console.WriteLine($"Evaluating at x = {xx}, y = {yy}: {xx + yy}"); } } } Console.WriteLine(); Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); // Note that the order of evaluation of pixels didn't actually // change! Splitting by itself does nothing, but it does open // up all of the scheduling possibilities that we will explore // below. } // Fuse two variables into one. { var gradient = new HSFunc("gradient_fused"); gradient[x, y] = x + y; // The opposite of splitting is 'fusing'. Fusing two variables // merges the two loops into a single for loop over the // product of the extents. Fusing is less important than // splitting, but it also sees use (as we'll see later in this // lesson). Like splitting, fusing by itself doesn't change // the order of evaluation. var fused = new HSVar("fused"); gradient.Fuse(x, y, fused); Console.WriteLine("Evaluating gradient with x and y fused"); var output = gradient.Realize <int>(4, 4); Console.WriteLine("Equivalent C:"); for (int f = 0; f < 4 * 4; f++) { int yy = f / 4; int xx = f % 4; Console.WriteLine($"Evaluating at x = {xx}, y = {yy}: {xx + yy}"); } Console.WriteLine(); Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); } // Evaluating in tiles. { var gradient = new HSFunc("gradient_tiled"); gradient[x, y] = x + y; gradient.TraceStores(); // Now that we can both split and reorder, we can do tiled // evaluation. Let's split both x and y by a factor of four, // and then reorder the vars to express a tiled traversal. // // A tiled traversal splits the domain into small rectangular // tiles, and outermost iterates over the tiles, and within // that iterates over the points within each tile. It can be // good for performance if neighboring pixels use overlapping // input data, for example in a blur. We can express a tiled // traversal like so: var x_outer = new HSVar("x_outer"); var x_inner = new HSVar("x_inner"); var y_outer = new HSVar("y_outer"); var y_inner = new HSVar("y_inner"); gradient.Split(x, x_outer, x_inner, 4); gradient.Split(y, y_outer, y_inner, 4); gradient.Reorder(x_inner, y_inner, x_outer, y_outer); // This pattern is common enough that there's a shorthand for it: // gradient.tile(x, y, x_outer, y_outer, x_inner, y_inner, 4, 4); Console.WriteLine("Evaluating gradient in 4x4 tiles"); var output = gradient.Realize <int>(8, 8); // See figures/lesson_05_tiled.gif for a visualization of this // schedule. Console.WriteLine("Equivalent C:"); for (int yOuter = 0; yOuter < 2; yOuter++) { for (int xOuter = 0; xOuter < 2; xOuter++) { for (int yInner = 0; yInner < 4; yInner++) { for (int xInner = 0; xInner < 4; xInner++) { int xx = xOuter * 4 + xInner; int yy = yOuter * 4 + yInner; Console.WriteLine($"Evaluating at x = {xx}, y = {yy}: {xx + yy}"); } } } } Console.WriteLine(); Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); } // Evaluating in vectors. { var gradient = new HSFunc("gradient_in_vectors"); gradient[x, y] = x + y; gradient.TraceStores(); // The nice thing about splitting is that it guarantees the // inner variable runs from zero to the split factor. Most of // the time the split-factor will be a compile-time constant, // so we can replace the loop over the inner variable with a // single vectorized computation. This time we'll split by a // factor of four, because on X86 we can use SSE to compute in // 4-wide vectors. var x_outer = new HSVar("x_outer"); var x_inner = new HSVar("x_inner"); gradient.Split(x, x_outer, x_inner, 4); gradient.Vectorize(x_inner); // Splitting and then vectorizing the inner variable is common // enough that there's a short-hand for it. We could have also // said: // // gradient.vectorize(x, 4); // // which is equivalent to: // // gradient.split(x, x, x_inner, 4); // gradient.vectorize(x_inner); // // Note that in this case we reused the name 'x' as the new // outer variable. Later scheduling calls that refer to x // will refer to this new outer variable named x. // This time we'll evaluate over an 8x4 box, so that we have // more than one vector of work per scanline. Console.WriteLine("Evaluating gradient with x_inner vectorized "); var output = gradient.Realize <int>(8, 4); // See figures/lesson_05_vectors.gif for a visualization. Console.WriteLine("Equivalent C:"); for (int yy = 0; yy < 4; yy++) { for (int xOuter = 0; xOuter < 2; xOuter++) { // The loop over x_inner has gone away, and has been // replaced by a vectorized version of the // expression. On x86 processors, Halide generates SSE // for all of this. int[] x_vec = { xOuter * 4 + 0, xOuter * 4 + 1, xOuter * 4 + 2, xOuter * 4 + 3 }; int[] val = { x_vec[0] + yy, x_vec[1] + yy, x_vec[2] + yy, x_vec[3] + yy }; Console.WriteLine($"Evaluating at " + $"<{x_vec[0]}, {x_vec[1]}, {x_vec[2]}, {x_vec[3]}>, " + $"<{yy}, {yy}, {yy}, {yy}>: " + $"<{val[0]}, {val[1]}, {val[2]}, {val[3]}>"); } } Console.WriteLine(); Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); } // Unrolling a loop. { var gradient = new HSFunc("gradient_unroll"); gradient[x, y] = x + y; gradient.TraceStores(); // If multiple pixels share overlapping data, it can make // sense to unroll a computation so that shared values are // only computed or loaded once. We do this similarly to how // we expressed vectorizing. We split a dimension and then // fully unroll the loop of the inner variable. Unrolling // doesn't change the order in which things are evaluated. var x_outer = new HSVar("x_outer"); var x_inner = new HSVar("x_inner"); gradient.Split(x, x_outer, x_inner, 2); gradient.Unroll(x_inner); // The shorthand for this is: // gradient.unroll(x, 2); Console.WriteLine("Evaluating gradient unrolled by a factor of two"); var result = gradient.Realize <int>(4, 4); Console.WriteLine("Equivalent C:"); for (int yy = 0; yy < 4; yy++) { for (int xOuter = 0; xOuter < 2; xOuter++) { // Instead of a for loop over x_inner, we get two // copies of the innermost statement. { int xInner = 0; int xx = xOuter * 2 + xInner; Console.WriteLine($"Evaluating at x = {xx}, y = {yy}: {xx + yy}"); } { int xInner = 1; int xx = xOuter * 2 + xInner; Console.WriteLine($"Evaluating at x = {xx}, y = {yy}: {xx + yy}"); } } } Console.WriteLine(); Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); } // Splitting by factors that don't divide the extent. { var gradient = new HSFunc("gradient_split_7x2"); gradient[x, y] = x + y; gradient.TraceStores(); // Splitting guarantees that the inner loop runs from zero to // the split factor, which is important for the uses we saw // above. So what happens when the total extent we wish to // evaluate x over isn't a multiple of the split factor? We'll // split by a factor three, and we'll evaluate gradient over a // 7x2 box instead of the 4x4 box we've been using. var x_outer = new HSVar("x_outer"); var x_inner = new HSVar("x_inner"); gradient.Split(x, x_outer, x_inner, 3); Console.WriteLine("Evaluating gradient over a 7x2 box with x split by three "); var output = gradient.Realize <int>(7, 2); // See figures/lesson_05_split_7_by_3.gif for a visualization // of what happened. Note that some points get evaluated more // than once! Console.WriteLine("Equivalent C:"); for (int yy = 0; yy < 2; yy++) { for (int xOuter = 0; xOuter < 3; xOuter++) // Now runs from 0 to 2 { for (int xInner = 0; xInner < 3; xInner++) { int xx = xOuter * 3; // Before we add x_inner, make sure we don't // evaluate points outside of the 7x2 box. We'll // clamp x to be at most 4 (7 minus the split // factor). if (xx > 4) { xx = 4; } xx += xInner; Console.WriteLine($"Evaluating at x = {xx}, y = {yy}: {xx + yy}"); } } } Console.WriteLine(); Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); // If you read the output, you'll see that some coordinates // were evaluated more than once. That's generally OK, because // pure Halide functions have no side-effects, so it's safe to // evaluate the same point multiple times. If you're calling // out to C functions like we are, it's your responsibility to // make sure you can handle the same point being evaluated // multiple times. // The general rule is: If we require x from x_min to x_min + x_extent, and // we split by a factor 'factor', then: // // x_outer runs from 0 to (x_extent + factor - 1)/factor // x_inner runs from 0 to factor // x = min(x_outer * factor, x_extent - factor) + x_inner + x_min // // In our example, x_min was 0, x_extent was 7, and factor was 3. // However, if you write a Halide function with an update // definition (see lesson 9), then it is not safe to evaluate // the same point multiple times, so we won't apply this // trick. Instead the range of values computed will be rounded // up to the next multiple of the split factor. } // Fusing, tiling, and parallelizing. { // We saw in the previous lesson that we can parallelize // across a variable. Here we combine it with fusing and // tiling to express a useful pattern - processing tiles in // parallel. // This is where fusing shines. Fusing helps when you want to // parallelize across multiple dimensions without introducing // nested parallelism. Nested parallelism (parallel for loops // within parallel for loops) is supported by Halide, but // often gives poor performance compared to fusing the // parallel variables into a single parallel for loop. var gradient = new HSFunc("gradient_fused_tiles"); gradient[x, y] = x + y; gradient.TraceStores(); // First we'll tile, then we'll fuse the tile indices and // parallelize across the combination. var x_outer = new HSVar("x_outer"); var y_outer = new HSVar("y_outer"); var x_inner = new HSVar("x_inner"); var y_inner = new HSVar("y_inner"); var tile_index = new HSVar("tile_index"); gradient.Tile(x, y, x_outer, y_outer, x_inner, y_inner, 4, 4); gradient.Fuse(x_outer, y_outer, tile_index); gradient.Parallel(tile_index); // The scheduling calls all return a reference to the Func, so // you can also chain them together into a single statement to // make things slightly clearer: // // gradient // .tile(x, y, x_outer, y_outer, x_inner, y_inner, 2, 2) // .fuse(x_outer, y_outer, tile_index) // .parallel(tile_index); Console.WriteLine("Evaluating gradient tiles in parallel"); var output = gradient.Realize <int>(8, 8); // The tiles should occur in arbitrary order, but within each // tile the pixels will be traversed in row-major order. See // figures/lesson_05_parallel_tiles.gif for a visualization. Console.WriteLine("Equivalent (serial) C:\n"); // This outermost loop should be a parallel for loop, but that's hard in C. for (int ti = 0; ti < 4; ti++) { int yOuter = ti / 2; int xOuter = ti % 2; for (int j_inner = 0; j_inner < 4; j_inner++) { for (int i_inner = 0; i_inner < 4; i_inner++) { int j = yOuter * 4 + j_inner; int i = xOuter * 4 + i_inner; Console.WriteLine($"Evaluating at x = {i}, y = {j}: {i + j}"); } } } Console.WriteLine(); Console.WriteLine("Pseudo-code for the schedule:"); gradient.PrintLoopNest(); Console.WriteLine(); } // Putting it all together. { // Are you ready? We're going to use all of the features above now. var gradient_fast = new HSFunc("gradient_fast"); gradient_fast[x, y] = x + y; // We'll process 64x64 tiles in parallel. var x_outer = new HSVar("x_outer"); var y_outer = new HSVar("y_outer"); var x_inner = new HSVar("x_inner"); var y_inner = new HSVar("y_inner"); var tile_index = new HSVar("tile_index"); gradient_fast .Tile(x, y, x_outer, y_outer, x_inner, y_inner, 64, 64) .Fuse(x_outer, y_outer, tile_index) .Parallel(tile_index); // We'll compute two scanlines at once while we walk across // each tile. We'll also vectorize in x. The easiest way to // express this is to recursively tile again within each tile // into 4x2 subtiles, then vectorize the subtiles across x and // unroll them across y: var x_inner_outer = new HSVar("x_inner_outer"); var y_inner_outer = new HSVar("y_inner_outer"); var x_vectors = new HSVar("x_vectors"); var y_pairs = new HSVar("y_pairs"); gradient_fast .Tile(x_inner, y_inner, x_inner_outer, y_inner_outer, x_vectors, y_pairs, 4, 2) .Vectorize(x_vectors) .Unroll(y_pairs); // Note that we didn't do any explicit splitting or // reordering. Those are the most important primitive // operations, but mostly they are buried underneath tiling, // vectorizing, or unrolling calls. // Now let's evaluate this over a range which is not a // multiple of the tile size. // If you like you can turn on tracing, but it's going to // produce a lot of printfs. Instead we'll compute the answer // both in C and Halide and see if the answers match. var result = gradient_fast.Realize <int>(350, 250); // See figures/lesson_05_fast.mp4 for a visualization. Console.WriteLine("Checking Halide result against equivalent C..."); for (int tileIndex = 0; tileIndex < 6 * 4; tileIndex++) { int yOuter = tileIndex / 4; int xOuter = tileIndex % 4; for (int yInnerOuter = 0; yInnerOuter < 64 / 2; yInnerOuter++) { for (int xInnerOuter = 0; xInnerOuter < 64 / 4; xInnerOuter++) { // We're vectorized across x int xx = Math.Min(xOuter * 64, 350 - 64) + xInnerOuter * 4; int[] xVec = { xx + 0, xx + 1, xx + 2, xx + 3 }; // And we unrolled across y int yBase = Math.Min(yOuter * 64, 250 - 64) + yInnerOuter * 2; { // y_pairs = 0 int yy = yBase + 0; int[] yVec = { yy, yy, yy, yy }; int[] val = { xVec[0] + yVec[0], xVec[1] + yVec[1], xVec[2] + yVec[2], xVec[3] + yVec[3] }; // Check the result. for (int i = 0; i < 4; i++) { if (result[xVec[i], yVec[i]] != val[i]) { Console.WriteLine($"There was an error at {xVec[i]} {yVec[i]}!"); return(-1); } } } { // y_pairs = 1 int yy = yBase + 1; int[] yVec = { yy, yy, yy, yy }; int[] val = { xVec[0] + yVec[0], xVec[1] + yVec[1], xVec[2] + yVec[2], xVec[3] + yVec[3] }; // Check the result. for (int i = 0; i < 4; i++) { if (result[xVec[i], yVec[i]] != val[i]) { Console.WriteLine($"There was an error at {xVec[i]} {yVec[i]}!"); return(-1); } } } } } } Console.WriteLine(); Console.WriteLine("Pseudo-code for the schedule:"); gradient_fast.PrintLoopNest(); Console.WriteLine(); // Note that in the Halide version, the algorithm is specified // once at the top, separately from the optimizations, and there // aren't that many lines of code total. Compare this to the C // version. There's more code (and it isn't even parallelized or // vectorized properly). More annoyingly, the statement of the // algorithm (the result is x plus y) is buried in multiple places // within the mess. This C code is hard to write, hard to read, // hard to debug, and hard to optimize further. This is why Halide // exists. } Console.WriteLine("Success!"); return(0); }