| 1 |
An overview |
| 2 |
============== |
| 3 |
|
| 4 |
Compyle allows users to execute a restricted subset of Python (almost similar |
| 5 |
to C) on a variety of HPC platforms. Currently we support multi-core execution |
| 6 |
using Cython, and OpenCL and CUDA for GPU devices. |
| 7 |
|
| 8 |
An introduction to compyle in the context of writing a molecular dynamics |
| 9 |
simulator is available in our `SciPy 2020 paper`_. You may also `try Compyle`_ |
| 10 |
online on a Google Colab notebook if you wish. |
| 11 |
|
| 12 |
Users start with code implemented in a very restricted Python syntax, this |
| 13 |
code is then automatically transpiled, compiled and executed to run on either |
| 14 |
one CPU core, or multiple CPU cores or on a GPU. Compyle offers source-to-source |
| 15 |
transpilation, making it a very convenient tool for writing HPC libraries. |
| 16 |
|
| 17 |
Compyle is not a magic bullet, |
| 18 |
|
| 19 |
- Do not expect that you may get a tremendous speedup. |
| 20 |
- Performance optimization can be hard and is platform specific. What works on |
| 21 |
the CPU may not work on the GPU and vice-versa. Compyle does not do anything |
| 22 |
to make this aspect easier. All the issues with memory bandwidth, cache, false |
| 23 |
sharing etc. still remain. Differences between memory architectures of CPUs |
| 24 |
and GPUs are not avoided at all -- you still have to deal with it. But you can |
| 25 |
do so from the comfort of one simple programming language, Python. |
| 26 |
- Compyle makes it easy to write everything in pure Python and generate the |
| 27 |
platform specific code from Python. It provides a low-level tool to make it |
| 28 |
easy for you to generate whatever appropriate code. |
| 29 |
- The restrictions Compyle imposes make it easy for you to think about your |
| 30 |
algorithms in that context and thereby allow you to build functionality that |
| 31 |
exploits the hardware as you see fit. |
| 32 |
- Compyle hides the details of the backend to the extent possible. You can write |
| 33 |
your code in Python, you can reuse your functions and decompose your problem |
| 34 |
to maximize reuse. Traditionally you would end up implementing some code in C, |
| 35 |
some in Python, some in OpenCL/CUDA, some in string fragments that you put |
| 36 |
together. Then you'd have to manage each of the runtimes yourself, worry about |
| 37 |
compilation etc. Compyle minimizes that pain. |
| 38 |
- By being written in Python, we make it easy to assemble these building blocks |
| 39 |
together to do fairly sophisticated things relatively easily from the same |
| 40 |
language. |
| 41 |
- Compyle is fairly simple and does source translation making it generally |
| 42 |
easier to understand and debug. The core code-base is less than 7k lines of |
| 43 |
code. |
| 44 |
- Compyle has relatively simple dependencies, for CPU support it requires |
| 45 |
Cython_ and a C-compiler which supports OpenMP_. On the GPU you need either |
| 46 |
PyOpenCL_ or PyCUDA_. In addition it depends on NumPy_ and Mako_. |
| 47 |
|
| 48 |
|
| 49 |
.. _Cython: http://www.cython.org |
| 50 |
.. _OpenMP: http://openmp.org/ |
| 51 |
.. _PyOpenCL: https://documen.tician.de/pyopencl/ |
| 52 |
.. _PyCUDA: https://documen.tician.de/pycuda/ |
| 53 |
.. _OpenCL: https://www.khronos.org/opencl/ |
| 54 |
.. _NumPy: http://numpy.scipy.org |
| 55 |
.. _Mako: https://pypi.python.org/pypi/Mako |
| 56 |
.. _SciPy 2020 paper: http://conference.scipy.org/proceedings/scipy2020/compyle_pr_ab.html |
| 57 |
.. _try Compyle: https://colab.research.google.com/drive/1SGRiArYXV1LEkZtUeg9j0qQ21MDqQR2U?usp=sharing |
| 58 |
|
| 59 |
While Compyle is simple and modest, it is quite powerful and convenient. In |
| 60 |
fact, Compyle has its origins in PySPH_ which is a powerful Python package |
| 61 |
supporting SPH, molecular dynamics, and other particle-based algorithms. The |
| 62 |
basic elements of Compyle are used in PySPH_ to automatically generate HPC code |
| 63 |
from code written in pure Python and execute it on multiple cores, and on GPUs |
| 64 |
without the user having to change any of their code. Compyle generalizes this |
| 65 |
code generation to make it available as a general tool. |
| 66 |
|
| 67 |
.. _PySPH: http://pysph.readthedocs.io |
| 68 |
|
| 69 |
|
| 70 |
These are the restrictions on the Python language that Compyle poses: |
| 71 |
|
| 72 |
- Functions with a C-syntax. |
| 73 |
- Function arguments must be declared using either type annotation or with a |
| 74 |
decorator or with default arguments. |
| 75 |
- No Python data structures, i.e. no lists, tuples, or dictionaries. |
| 76 |
- Contiguous Numpy arrays are supported but must be one dimensional. |
| 77 |
- No memory allocation is allowed inside these functions. |
| 78 |
- On OpenCL no recursion is supported. |
| 79 |
- All function calls must not use dotted names, i.e. don't use ``math.sin``, |
| 80 |
instead just use ``sin``. This is because we do not perform any kind of name |
| 81 |
mangling of the generated code to make it easier to read. |
| 82 |
|
| 83 |
Basically think of it as good old FORTRAN. |
| 84 |
|
| 85 |
Technically we do support structs internally (we use it heavily in PySPH_) but |
| 86 |
this is not yet exposed at the high-level and is very likely to be supported |
| 87 |
in the future. |
| 88 |
|
| 89 |
|
| 90 |
Simple example |
| 91 |
-------------- |
| 92 |
|
| 93 |
Enough talk, lets look at some code. Here is a very simple example:: |
| 94 |
|
| 95 |
from compyle.api import Elementwise, annotate, wrap, get_config |
| 96 |
import numpy as np |
| 97 |
|
| 98 |
@annotate(i='int', x='doublep', y='doublep', double='a,b') |
| 99 |
def axpb(i, x, y, a, b): |
| 100 |
y[i] = a*sin(x[i]) + b |
| 101 |
|
| 102 |
x = np.linspace(0, 1, 10000) |
| 103 |
y = np.zeros_like(x) |
| 104 |
a = 2.0 |
| 105 |
b = 3.0 |
| 106 |
|
| 107 |
backend = 'cython' |
| 108 |
get_config().use_openmp = True |
| 109 |
x, y = wrap(x, y, backend=backend) |
| 110 |
e = Elementwise(axpb, backend=backend) |
| 111 |
e(x, y, a, b) |
| 112 |
|
| 113 |
This will execute the elementwise operation in parallel using OpenMP with |
| 114 |
Cython. The code is auto-generated, compiled and called for you transparently. |
| 115 |
The first time this runs, it will take a bit of time to compile everything but |
| 116 |
the next time, this is cached and will run much faster. |
| 117 |
|
| 118 |
If you just change the ``backend = 'opencl'``, the same exact code will be |
| 119 |
executed using PyOpenCL_ and if you change the backend to ``'cuda'``, it will |
| 120 |
execute via CUDA without any other changes to your code. This is obviously a |
| 121 |
very trivial example, there are more complex examples available as well. |
| 122 |
|
| 123 |
To see the source code that is automatically generated for the above |
| 124 |
elementwise operation example use:: |
| 125 |
|
| 126 |
e.source |
| 127 |
|
| 128 |
This will contain the sources that are generated based on the user code alone. |
| 129 |
To see all the sources created, use:: |
| 130 |
|
| 131 |
e.all_source |
| 132 |
|
| 133 |
A word of warning though that this can be fairly long especially on a GPU and |
| 134 |
for other kind of operations may actually include multiple GPU kernels. This |
| 135 |
is largely for reference and debugging. |
| 136 |
|
| 137 |
|
| 138 |
More examples |
| 139 |
-------------- |
| 140 |
|
| 141 |
More complex examples (but still fairly simple) are available in the `examples |
| 142 |
<https://github.com/pypr/compyle/tree/main/examples>`_ directory. |
| 143 |
|
| 144 |
- `axpb.py <https://github.com/pypr/compyle/tree/main/examples/axpb.py>`_: the |
| 145 |
above example but for openmp and opencl compared with serial showing that in |
| 146 |
some cases serial is actually faster than parallel! |
| 147 |
|
| 148 |
- `vm_elementwise.py |
| 149 |
<https://github.com/pypr/compyle/tree/main/examples/vm_elementwise.py>`_: |
| 150 |
shows a simple N-body code with two-dimensional point vortices. The code uses |
| 151 |
a simple elementwise operation and works with OpenMP and OpenCL. |
| 152 |
|
| 153 |
- `vm_numba.py |
| 154 |
<https://github.com/pypr/compyle/tree/main/examples/vm_numba.py>`_: shows |
| 155 |
the same code written in numba for comparison. In our benchmarks, Compyle is |
| 156 |
actually faster even in serial and in parallel it can be much faster when you |
| 157 |
use all cores. |
| 158 |
|
| 159 |
- `vm_kernel.py |
| 160 |
<https://github.com/pypr/compyle/tree/main/examples/vm_kernel.py>`_: shows |
| 161 |
how one can write a low-level OpenCL kernel in pure Python and use that. This |
| 162 |
also shows how you can allocate and use local (or shared) memory which is |
| 163 |
often very important for performance on GPGPUs. This code will only run via |
| 164 |
PyOpenCL. |
| 165 |
|
| 166 |
- `bench_vm.py |
| 167 |
<https://github.com/pypr/compyle/tree/main/examples/bench_vm.py>`_: |
| 168 |
Benchmarks the various vortex method results above for a comparison with |
| 169 |
numba. |
| 170 |
|
| 171 |
|
| 172 |
Read on for more details about Compyle. |
| 173 |
|
| 174 |
|
| 175 |
Citing Compyle |
| 176 |
--------------- |
| 177 |
|
| 178 |
If you find Compyle useful or just want to read a paper on it, please see: |
| 179 |
|
| 180 |
- Aditya Bhosale and Prabhu Ramachandran, "Compyle: Python once, parallel |
| 181 |
computing anywhere", Proceedings of the 19th Python in Science Conference |
| 182 |
(SciPy 2020), July, 2020, Austin, Texas, USA. |
| 183 |
`doi:10.25080/Majora-342d178e-005 |
| 184 |
<https://doi.org/10.25080/Majora-342d178e-005>`_ **Won best poster** `SciPy |
| 185 |
2020 Paper`_. |
| 186 |
|
| 187 |
Accompanying the paper is the |
| 188 |
|
| 189 |
- `Compyle poster presentation <https://docs.google.com/presentation/d/1LS9XO5pQXz8G5d27RP5oWLFxUA-Fr5OvfVUGsgg86TQ/edit#slide=id.p>`_ |
| 190 |
- and the `Compyle poster video <https://www.youtube.com/watch?v=h2YpPPL6nEY>`_ |