Debian Codegraph @

docs/source/overview.rst

raw
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>`_