readme.md
1## Differences from C++ API
2
3The Python bindings attempt to mimic the Halide C++ API as closely as possible,
4with some differences where the C++ idiom is either inappropriate or impossible:
5
6- Most APIs that take a variadic argumentlist of ints in C++ take an explicit
7 list in Python. For instance, the usual version of the `Buffer` ctor in C++
8 offers variadic and list versions:
9 `Buffer<>(Type t, int extent_dim_0, int extent_dim_1, ...., extent_dim_N, string name = "") Buffer<>(Type t, vector<int> extents, string name = "")`
10 in Python, only the second variant is provided.
11- `Func` and `Buffer` access is done using `[]` rather than `()`
12- Some classes in the Halide API aren't provided because they are 'wrapped' with
13 standard Python idioms:
14 - `Halide::Tuple` doesn't exist in the Python bindings; an ordinary Python
15 tuple of `Halide::Expr` is used instead.
16 - `Halide::Realization` doesn't exist in the Python bindings; an ordinary
17 Python tuple of `Halide::Buffer` is used instead.
18 - `Halide::Error` and friends don't exist; standard Python error handling is
19 used instead.
20- static and instance method overloads with the same name in the same class
21 aren't allowed, so some convenience methods are missing from `Halide::Var`
22- Templated types (notably `Halide::Buffer<>` and `Halide::Param<>`) aren't
23 provided, for obvious reasons; only the equivalents of `Halide::Buffer<void>`
24 and `Halide::Param<void>` are supported.
25- Only things in the `Halide` namespace are supported; classes and methods that
26 involve using the `Halide::Internal` namespace are not provided.
27- The functions in `Halide::ConciseCasts` are present in the toplevel Halide
28 module in Python, rather than a submodule: e.g., use `hl.i8_sat()`, not
29 `hl.ConciseCasts.i8_sat()`.
30- No mechanism is provided for overriding any runtime functions from Python.
31- No mechanism is provided for supporting `Func::define_extern`.
32- `Buffer::for_each_value()` is hard to implement well in Python; it's omitted
33 entirely for now.
34- `Func::in` becomes `Func.in_` because `in` is a Python keyword.
35
36## Enhancements to the C++ API
37
38- The `Buffer` supports the Python Buffer Protocol
39 (https://www.python.org/dev/peps/pep-3118/) and thus is easily and cheaply
40 converted to and from other compatible objects (e.g., NumPy's `ndarray`), with
41 storage being shared.
42
43## Prerequisites
44
45The bindings (and demonstration applications) should work well for Python 3.4
46(or higher), on Linux and OSX platforms. Windows is not yet supported, but could
47be with CMake work. (We have dropped support for Python 2.x and will not accept
48patches to re-enable it.)
49
50#### Python requirements:
51
52See requirements.txt (to be used with `pip`:
53`pip install --user requirements.txt`)
54
55#### C++ requirements:
56
57- Halide compiled to a distribution (e.g. `make distrib` or similar), with the
58 `HALIDE_DISTRIB_PATH` env var pointing to it
59
60## Compilation instructions
61
62Build using: `make`
63
64## Documentation and Examples
65
66The Python API reflects directly the
67[C++ Halide API](http://halide-lang.org/docs).
68
69Check out the code for the example applications in the `apps/` and `tutorial/`
70subdirectory.
71
72You can run them as a batch via `make test_apps` or `make test_tutorial`.
73
74To run these examples, make sure the `PYTHONPATH` environment variable points to
75your build directory (e.g.
76`export PYTHONPATH=halide_source/python_bindings/bin:$PYTHONPATH`).
77
78## License
79
80The Python bindings use the same
81[MIT license](https://github.com/halide/Halide/blob/master/LICENSE.txt) as
82Halide.
83
84Python bindings provided by Connelly Barnes (2012-2013), Fred Rotbart (2014),
85Rodrigo Benenson (2015) and the Halide open-source community.
86