halide 19.0.0__cp38-cp38-macosx_11_0_x86_64.whl

halide/share/tools/halide_benchmark.h

@@ -0,0 +1,240 @@
+#ifndef BENCHMARK_H
+#define BENCHMARK_H
+
+#include <algorithm>
+#include <cassert>
+#include <chrono>
+#include <functional>
+#include <limits>
+
+#if defined(__EMSCRIPTEN__)
+#include <emscripten.h>
+#endif
+
+namespace Halide {
+namespace Tools {
+
+#if !(defined(__EMSCRIPTEN__) && defined(HALIDE_BENCHMARK_USE_EMSCRIPTEN_GET_NOW))
+
+// Prefer high_resolution_clock, but only if it's steady...
+template<bool HighResIsSteady = std::chrono::high_resolution_clock::is_steady>
+struct SteadyClock {
+    using type = std::chrono::high_resolution_clock;
+};
+
+// ...otherwise use steady_clock.
+template<>
+struct SteadyClock<false> {
+    using type = std::chrono::steady_clock;
+};
+
+inline SteadyClock<>::type::time_point benchmark_now() {
+    return SteadyClock<>::type::now();
+}
+
+inline double benchmark_duration_seconds(
+    SteadyClock<>::type::time_point start,
+    SteadyClock<>::type::time_point end) {
+    return std::chrono::duration_cast<std::chrono::duration<double>>(end - start).count();
+}
+
+#else  // __EMSCRIPTEN__
+
+// Emscripten's std::chrono::steady_clock and/or high_resolution_clock
+// can throw an exception (!) if the runtime doesn't have a truly
+// steady clock available. Advice from emscripten-discuss suggested
+// that emscripten_get_now() is the best bet, as it is milliseconds
+// (but returned as a double, with microseconds in the fractional portion),
+// using either performance.now() or performance.hrtime() depending on the
+// environment. Unfortunately, it's not guaranteed to be steady, and the
+// auto-benchmark algorithm reacts badly to negative times, so we'll leave this
+// disabled for now; you can opt-in to this by defining HALIDE_BENCHMARK_USE_EMSCRIPTEN_GET_NOW
+// if you need to build for a wasm runtime with the exception behavior above.
+inline double benchmark_now() {
+    return emscripten_get_now();
+}
+
+inline double benchmark_duration_seconds(double start, double end) {
+    // emscripten_get_now is *not* guaranteed to be steady.
+    // Clamping to a positive value is arguably better than nothing,
+    // but still produces unpredictable results in the adaptive case
+    // (which is why this is disabled by default).
+    return std::max((end - start) / 1000.0, 1e-9);
+}
+
+#endif
+
+// Benchmark the operation 'op'. The number of iterations refers to
+// how many times the operation is run for each time measurement, the
+// result is the minimum over a number of samples runs. The result is the
+// amount of time in seconds for one iteration.
+//
+// NOTE: it is usually simpler and more accurate to use the adaptive
+// version of benchmark() later in this file; this function is provided
+// for legacy code.
+//
+// IMPORTANT NOTE: Using this tool for timing GPU code may be misleading,
+// as it does not account for time needed to synchronize to/from the GPU;
+// if the callback doesn't include calls to device_sync(), the reported
+// time may only be that to queue the requests; if the callback *does*
+// include calls to device_sync(), it might exaggerate the sync overhead
+// for real-world use. For now, callers using this to benchmark GPU
+// code should measure with extreme caution.
+
+inline double benchmark(uint64_t samples, uint64_t iterations, const std::function<void()> &op) {
+    double best = std::numeric_limits<double>::infinity();
+    for (uint64_t i = 0; i < samples; i++) {
+        auto start = benchmark_now();
+        for (uint64_t j = 0; j < iterations; j++) {
+            op();
+        }
+        auto end = benchmark_now();
+        double elapsed_seconds = benchmark_duration_seconds(start, end);
+        best = std::min(best, elapsed_seconds);
+    }
+    return best / iterations;
+}
+
+// Benchmark the operation 'op': run the operation until at least min_time
+// has elapsed; the number of iterations is expanded as we
+// progress (based on initial runs of 'op') to minimize overhead. The time
+// reported will be that of the best single iteration.
+//
+// Most callers should be able to get good results without needing to specify
+// custom BenchmarkConfig values.
+//
+// IMPORTANT NOTE: Using this tool for timing GPU code may be misleading,
+// as it does not account for time needed to synchronize to/from the GPU;
+// if the callback doesn't include calls to device_sync(), the reported
+// time may only be that to queue the requests; if the callback *does*
+// include calls to device_sync(), it might exaggerate the sync overhead
+// for real-world use. For now, callers using this to benchmark GPU
+// code should measure with extreme caution.
+
+constexpr uint64_t kBenchmarkMaxIterations = 1000000000;
+
+struct BenchmarkConfig {
+    // Attempt to use this much time (in seconds) for the meaningful samples
+    // taken; initial iterations will be done to find an iterations-per-sample
+    // count that puts the total runtime in this ballpark.
+    double min_time{0.1};
+
+    // Set an absolute upper time limit. Defaults to min_time * 4.
+    double max_time{0.1 * 4};
+
+    // Maximum value for the computed iters-per-sample.
+    // We need this for degenerate cases in which we have a
+    // very coarse-grained timer (e.g. some Emscripten/browser environments),
+    // and a very short operation being benchmarked; in these cases,
+    // we can get timings that are effectively zero, which can explode
+    // the predicted next-iter into ~100B or more. It should be unusual
+    // that client code needs to adjust this value.
+    uint64_t max_iters_per_sample{1000000};
+
+    // Terminate when the relative difference between the best runtime
+    // seen and the third-best runtime seen is no more than
+    // this. Controls accuracy. The closer to zero this gets the more
+    // reliable the answer, but the longer it may take to run.
+    double accuracy{0.03};
+};
+
+struct BenchmarkResult {
+    // Best elapsed wall-clock time per iteration (seconds).
+    double wall_time;
+
+    // Number of samples used for measurement.
+    // (There might be additional samples taken that are not used
+    // for measurement.)
+    uint64_t samples;
+
+    // Total number of iterations across all samples.
+    // (There might be additional iterations taken that are not used
+    // for measurement.)
+    uint64_t iterations;
+
+    // Measured accuracy between the best and third-best result.
+    // Will be <= config.accuracy unless max_time is exceeded.
+    double accuracy;
+
+    operator double() const {
+        return wall_time;
+    }
+};
+
+inline BenchmarkResult benchmark(const std::function<void()> &op, const BenchmarkConfig &config = {}) {
+    BenchmarkResult result{0, 0, 0};
+
+    const double min_time = std::max(10 * 1e-6, config.min_time);
+    const double max_time = std::max(config.min_time, config.max_time);
+
+    const double accuracy = 1.0 + std::min(std::max(0.001, config.accuracy), 0.1);
+
+    // We will do (at least) kMinSamples samples; we will do additional
+    // samples until the best the kMinSamples'th results are within the
+    // accuracy tolerance (or we run out of iterations).
+    constexpr int kMinSamples = 3;
+    double times[kMinSamples + 1] = {0};
+
+    double total_time = 0;
+    uint64_t iters_per_sample = 1;
+    for (;;) {
+        result.samples = 0;
+        result.iterations = 0;
+        total_time = 0;
+        for (int i = 0; i < kMinSamples; i++) {
+            times[i] = benchmark(1, iters_per_sample, op);
+            result.samples++;
+            result.iterations += iters_per_sample;
+            total_time += times[i] * iters_per_sample;
+        }
+        std::sort(times, times + kMinSamples);
+
+        // Any time result <= to this is considered 'zero' here.
+        const double kTimeEpsilon = 1e-9;
+        if (times[0] < kTimeEpsilon) {
+            // If the fastest time is tiny, then trying to use it to predict next_iters
+            // can just explode into something unpredictably huge, which could take far too
+            // long to complete. Just double iters_per_sample and try again (or terminate if
+            // we're over the max).
+            iters_per_sample *= 2;
+        } else {
+            const double time_factor = std::max(times[0] * kMinSamples, kTimeEpsilon);
+            if (time_factor * iters_per_sample >= min_time) {
+                break;
+            }
+            // Use an estimate based on initial times to converge faster.
+            const double next_iters = std::max(min_time / time_factor,
+                                               iters_per_sample * 2.0);
+            iters_per_sample = (uint64_t)(next_iters + 0.5);
+        }
+
+        // Ensure we never explode beyond the max.
+        if (iters_per_sample >= config.max_iters_per_sample) {
+            iters_per_sample = config.max_iters_per_sample;
+            break;
+        }
+    }
+
+    // - Keep taking samples until we are accurate enough (even if we run over min_time).
+    // - If we are already accurate enough but have time remaining, keep taking samples.
+    // - No matter what, don't go over max_time; this is important, in case
+    // we happen to get faster results for the first samples, then happen to transition
+    // to throttled-down CPU state.
+    while ((times[0] * accuracy < times[kMinSamples - 1] || total_time < min_time) &&
+           total_time < max_time) {
+        times[kMinSamples] = benchmark(1, iters_per_sample, op);
+        result.samples++;
+        result.iterations += iters_per_sample;
+        total_time += times[kMinSamples] * iters_per_sample;
+        std::sort(times, times + kMinSamples + 1);
+    }
+    result.wall_time = times[0];
+    result.accuracy = (times[kMinSamples - 1] / times[0]) - 1.0;
+
+    return result;
+}
+
+}  // namespace Tools
+}  // namespace Halide
+
+#endif

halide/share/tools/halide_image.h

@@ -0,0 +1,31 @@
+#ifndef HALIDE_TOOLS_IMAGE_H
+#define HALIDE_TOOLS_IMAGE_H
+
+/** \file
+ *
+ * This allows code that relied on halide_image.h and
+ * Halide::Tools::Image to continue to work with newer versions of
+ * Halide where HalideBuffer.h and Halide::Buffer are the way to work
+ * with data.
+ *
+ * Besides mapping Halide::Tools::Image to Halide::Buffer, it defines
+ * USING_HALIDE_BUFFER to allow code to conditionally compile for one
+ * or the other.
+ *
+ * It is intended as a stop-gap measure until the code can be updated.
+ */
+
+#include "HalideBuffer.h"
+
+namespace Halide {
+namespace Tools {
+
+#define USING_HALIDE_BUFFER
+
+template<typename T>
+using Image = Buffer<T>;
+
+}  // namespace Tools
+}  // namespace Halide
+
+#endif  // #ifndef HALIDE_TOOLS_IMAGE_H

halide/share/tools/halide_image_info.h

@@ -0,0 +1,318 @@
+// This header defines several methods useful for debugging programs that
+// operate on the Buffer class supporting images with arbitrary dimensions.
+//
+//   Buffer<uint16_t> input = load_image(argv[1]);
+//
+//   info(input, "input");  // Output the Buffer header info
+//   dump(input, "input");  // Dump the Buffer data
+//   stats(input, "input"); // Report statistics for the Buffer
+//
+//
+#ifndef HALIDE_TOOLS_IMAGE_INFO_H
+#define HALIDE_TOOLS_IMAGE_INFO_H
+
+#include <cassert>
+#include <cstdlib>
+#include <iomanip>
+#include <iostream>
+#include <limits>
+#include <memory>
+#include <sstream>
+#include <stdint.h>
+#include <vector>
+
+#include "HalideBuffer.h"
+#include "HalideRuntime.h"
+
+namespace Halide {
+namespace Tools {
+
+static inline void print_dimid(int d, int val) {
+    static const char *dimid[] = {"x", "y", "z", "w"};
+    int numdimid = 4;
+    if (d < numdimid) {
+        std::cout << " " << dimid[d] << ":" << val;
+    } else {
+        std::cout << " extent[" << d << "]:" << val;
+    }
+}
+
+static inline void print_loc(const std::vector<int32_t> &loc, int dim, const halide_buffer_t *buf) {
+    for (int d = 0; d < dim; d++) {
+        if (d) {
+            std::cout << ",";
+        }
+        std::cout << loc[d] + buf->dim[d].min;
+    }
+}
+
+static inline void print_memalign(intptr_t val) {
+    intptr_t align_chk = 1024 * 1024;
+    while (align_chk > 0) {
+        if ((val & (align_chk - 1)) == 0) {
+            char aunit = ' ';
+            if (align_chk >= 1024) {
+                align_chk >>= 10;
+                aunit = 'K';
+            }
+            if (align_chk >= 1024) {
+                align_chk >>= 10;
+                aunit = 'M';
+            }
+            std::cout << "align:" << align_chk;
+            if (aunit != ' ') {
+                std::cout << aunit;
+            }
+            break;
+        }
+        align_chk >>= 1;
+    }
+}
+
+template<typename T>
+void info(Runtime::Buffer<T> &img, const char *tag = "Buffer") {
+    halide_buffer_t *buf = &(*img);
+    int dim = img.dimensions();
+    int img_bpp = buf->type.bytes();
+    int img_tsize = sizeof(T);
+    int img_csize = sizeof(Runtime::Buffer<T>);
+    int img_bsize = sizeof(halide_buffer_t);
+    int32_t size = 1;
+    uint64_t dev = buf->device;
+    bool host_dirty = buf->host_dirty();
+    bool dev_dirty = buf->device_dirty();
+
+    std::cout << std::endl
+              << "-----------------------------------------------------------------------------";
+    std::cout << std::endl
+              << "Buffer info: " << tag
+              << " dim:" << dim << " bpp:" << img_bpp;
+    for (int d = 0; d < dim; d++) {
+        print_dimid(d, buf->dim[d].extent);
+        size *= buf->dim[d].extent;
+    }
+    std::cout << std::endl;
+    std::cout << tag << " class       = 0x" << std::left << std::setw(10) << (void *)img
+              << std::right << " # ";
+    print_memalign((intptr_t)&img);
+    std::cout << std::endl;
+    std::cout << tag << " class size  = " << img_csize
+              << " (0x" << std::hex << img_csize << std::dec << ")\n";
+    std::cout << tag << "-class => [ 0x" << (void *)&img
+              << ", 0x" << (void *)(((char *)&img) + img_csize - 1)
+              << " ], # size:" << img_csize << ", ";
+    print_memalign((intptr_t)&img);
+    std::cout << std::endl;
+    std::cout << tag << " buf_t size  = " << img_bsize
+              << " (0x" << std::hex << img_bsize << std::dec << ")\n";
+    std::cout << tag << "-buf_t => [ 0x" << (void *)&buf
+              << ", 0x" << (void *)(((char *)&buf) + img_bsize - 1)
+              << " ], # size:" << img_bsize << ", ";
+    print_memalign((intptr_t)&buf);
+    std::cout << std::endl;
+    if (img_bpp != img_tsize) {
+        std::cout << tag << " sizeof(T)   = " << img_tsize << std::endl;
+    }
+    std::cout << tag << " host_dirty  = " << host_dirty << std::endl;
+    std::cout << tag << " dev_dirty   = " << dev_dirty << std::endl;
+    std::cout << tag << " dev handle  = " << dev << std::endl;
+    std::cout << tag << " elem_size   = " << img_bpp << std::endl;
+    std::cout << tag << " img_dim     = " << dim << std::endl;
+    std::cout << tag << " width       = " << img.width() << std::endl;
+    std::cout << tag << " height      = " << img.height() << std::endl;
+    std::cout << tag << " channels    = " << img.channels() << std::endl;
+    std::cout << tag << " extent[]    = ";
+    for (int d = 0; d < dim; d++) {
+        std::cout << buf->dim[d].extent << " ";
+    }
+    std::cout << std::endl;
+    std::cout << tag << " min[]       = ";
+    for (int d = 0; d < dim; d++) {
+        std::cout << buf->dim[d].min << " ";
+    }
+    std::cout << std::endl;
+    std::cout << tag << " stride[]    = ";
+    for (int d = 0; d < dim; d++) {
+        std::cout << buf->dim[d].stride << " ";
+    }
+    std::cout << std::endl;
+    if (img_bpp > 1) {
+        for (int d = 0; d < dim; d++) {
+            std::cout << tag << " str[" << d << "]*bpp  = "
+                      << std::left << std::setw(12) << buf->dim[d].stride * img_bpp
+                      << std::right << " # ";
+            print_memalign(buf->dim[d].stride * img_bpp);
+            std::cout << std::endl;
+        }
+    }
+
+    const T *img_data = img.data();
+    const T *img_next = img_data + size;
+    int32_t img_size = size * img_bpp;
+    int32_t data_size = (char *)img_next - (char *)img_data;
+    std::cout << tag << " size        = " << size << " (0x"
+              << std::hex << size << ")" << std::dec << std::endl;
+    std::cout << tag << " img_size    = " << img_size << " (0x"
+              << std::hex << img_size << ")" << std::dec << std::endl;
+    std::cout << tag << " data        = 0x" << std::left << std::setw(10) << (void *)img_data
+              << std::right << " # ";
+    print_memalign((intptr_t)img_data);
+    std::cout << std::endl;
+    std::cout << tag << " next        = 0x" << std::left << std::setw(10) << (void *)img_next
+              << std::right << " # ";
+    print_memalign((intptr_t)img_next);
+    std::cout << std::endl;
+    std::cout << tag << " data_size   = " << data_size << " (0x"
+              << std::hex << data_size << ")" << std::dec << std::endl;
+    std::cout << tag << " => [ 0x" << (void *)img_data
+              << ", 0x" << (void *)(((char *)img_next) - 1)
+              << "], # size:" << data_size << ", ";
+    print_memalign((intptr_t)img_data);
+    std::cout << std::endl;
+}
+
+template<typename T>
+void dump(Runtime::Buffer<T> &img, const char *tag = "Buffer") {
+    halide_buffer_t *buf = &(*img);
+    int dim = img.dimensions();
+    int bpp = buf->type.bytes();
+    int32_t size = 1;
+
+    std::cout << std::endl
+              << "Buffer dump: " << tag
+              << " dim:" << dim << " bpp:" << bpp;
+    for (int d = 0; d < dim; d++) {
+        print_dimid(d, buf->dim[d].extent);
+        size *= buf->dim[d].extent;
+    }
+
+    // Arbitrary dimension image traversal
+    const T *ptr = img.data();
+    std::vector<int32_t> curloc(dim);
+    for (int d = 1; d < dim; d++) {
+        curloc[d] = -1;
+    }
+    curloc[0] = 0;
+
+    for (int32_t i = 0; i < size; i++) {
+        // Track changes in position in higher dimensions
+        for (int d = 1; d < dim; d++) {
+            if ((i % buf->dim[d].stride) == 0) {
+                curloc[d]++;
+                for (int din = 0; din < d; din++) {
+                    curloc[din] = 0;
+                }
+                std::cout << std::endl;
+                // Print separators for dimensions beyond (x0,y1)
+                if (d > 1) {
+                    print_dimid(d, curloc[d] + buf->dim[d].min);
+                    std::cout << "\n==========================================";
+                }
+            }
+        }
+
+        // Check for start of row (or wrap due to width)
+        if ((curloc[0] % 16) == 0) {
+            int widx = 0;
+            std::ostringstream idx;
+            if (dim > 1) {  // Multi-dim, just report (x0,y1) on each row
+                idx << "(" << curloc[0] + buf->dim[0].min << "," << curloc[1] + buf->dim[1].min << ")";
+                widx = 12;
+            } else {  // Single-dim
+                idx << curloc[0] + buf->dim[0].min;
+                widx = 4;
+            }
+            std::cout << std::endl
+                      << std::setw(widx) << idx.str() << ": ";
+        }
+
+        // Display data
+        std::cout << std::setw(4) << *ptr++ + 0 << " ";
+
+        curloc[0]++;  // Track position in row
+    }
+    std::cout << std::endl;
+}
+
+template<typename T>
+void stats(Runtime::Buffer<T> &img, const char *tag = "Buffer") {
+    halide_buffer_t *buf = &(*img);
+    int dim = img.dimensions();
+    int bpp = buf->type.bytes();
+    int32_t size = 1;
+    std::cout << std::endl
+              << "Buffer stats: " << tag
+              << " dim:" << dim << " bpp:" << bpp;
+    for (int d = 0; d < dim; d++) {
+        print_dimid(d, buf->dim[d].extent);
+        size *= buf->dim[d].extent;
+    }
+
+    // Arbitrary dimension image traversal
+    const T *ptr = img.data();
+    std::vector<int32_t> curloc(dim);
+    for (int d = 1; d < dim; d++) {
+        curloc[d] = -1;
+    }
+    curloc[0] = 0;
+
+    // Statistics
+    int32_t cnt = 0;
+    double sum = 0;
+    T minval = *ptr;
+    T maxval = *ptr;
+    std::vector<int32_t> minloc(dim);
+    std::vector<int32_t> maxloc(dim);
+    for (int d = 0; d < dim; d++) {
+        minloc[d] = 0;
+        maxloc[d] = 0;
+    }
+
+    for (int32_t i = 0; i < size; i++) {
+        // Track changes in position in higher dimensions
+        for (int d = 1; d < dim; d++) {
+            if ((i % buf->dim[d].stride) == 0) {
+                curloc[d]++;
+                for (int din = 0; din < d; din++) {
+                    curloc[din] = 0;
+                }
+            }
+        }
+
+        // Collect data
+        T val = *ptr++;
+        sum += val;
+        cnt++;
+        if (val < minval) {
+            minval = val;
+            for (int d = 0; d < dim; d++) {
+                minloc[d] = curloc[d];
+            }
+        }
+        if (val > maxval) {
+            maxval = val;
+            for (int d = 0; d < dim; d++) {
+                maxloc[d] = curloc[d];
+            }
+        }
+
+        curloc[0]++;  // Track position in row
+    }
+
+    double avg = sum / cnt;
+    std::cout << std::endl;
+    std::cout << "min        = " << minval + 0 << " @ (";
+    print_loc(minloc, dim, buf);
+    std::cout << ")" << std::endl;
+    std::cout << "max        = " << maxval + 0 << " @ (";
+    print_loc(maxloc, dim, buf);
+    std::cout << ")" << std::endl;
+    std::cout << "mean       = " << avg << std::endl;
+    std::cout << "N          = " << cnt << std::endl;
+    std::cout << std::endl;
+}
+
+}  // namespace Tools
+}  // namespace Halide
+
+#endif  // HALIDE_TOOLS_IMAGE_INFO_H