*pystencils* is a package that can speed up computations on *numpy* arrays. All computations are carried out fully parallel on CPUs (single node with OpenMP, multiple nodes with MPI) or on GPUs.
It is suited for applications that run the same operation on *numpy* arrays multiple times. It can be used to accelerate computations on images or voxel fields. Its main application, however, are numerical simulations using finite differences, finite volumes, or lattice Boltzmann methods.
There already exist a variety of packages to speed up numeric Python code. One could use pure numpy or solutions that compile your code, like *Cython* and *numba*. See [this page](demo_benchmark.ipynb) for a comparison of these tools.
As the name suggests, *pystencils* was developed for **stencil codes**, i.e. operations that update array elements using only a local neighborhood.
It generates C code, compiles it behind the scenes, and lets you call the compiled C function as if it was a native Python function.
But lets not dive too deep into the concepts of *pystencils* here, they are covered in detail in the following tutorials. Let's instead look at a simple example, that computes the average neighbor values of a *numpy* array. Therefor we first create two rather large arrays for input and output:
%% Cell type:code id: tags:
``` python
input_arr=np.random.rand(1024,1024)
output_arr=np.zeros_like(input_arr)
```
%% Cell type:markdown id: tags:
We first implement a version of this algorithm using pure numpy and benchmark it.
Here we first have created a symbolic notation of the stencil itself. This representation is built on top of *sympy* and is explained in detail in the next section.
This description is then compiled and loaded as a Python function.
This whole process might seem overly complicated. We have already spent more lines of code than we needed for the *numpy* implementation and don't have anything running yet! However, this multi-stage process of formulating the algorithm symbolically, and just in the end actually running it, is what makes *pystencils* faster and more flexible than other approaches.
Now finally lets benchmark the *pystencils* kernel.
%% Cell type:code id: tags:
``` python
defpystencils_kernel():
kernel(src=input_arr,dst=output_arr)
```
%% Cell type:code id: tags:
``` python
%%timeit
pystencils_kernel()
```
%% Output
639 µs ± 35 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each)
643 µs ± 8.66 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each)
%% Cell type:markdown id: tags:
This benchmark shows that *pystencils* is a lot faster than pure *numpy*, especially for large arrays.
If you are interested in performance details and comparison to other packages like Cython, have a look at [this page](demo_benchmark.ipynb).
%% Cell type:markdown id: tags:
## Short *sympy* introduction
In this tutorial we continue with a short *sympy* introduction, since the symbolic kernel definition is built on top of this package. If you already know *sympy* you can skip this section.
You can also read the full [sympy documentation here](http://docs.sympy.org/latest/index.html).
%% Cell type:code id: tags:
``` python
importsympyassp
sp.init_printing()# enable nice LaTeX output
```
%% Cell type:markdown id: tags:
*sympy* is a package for symbolic calculation. So first we need some symbols:
%% Cell type:code id: tags:
``` python
x=sp.Symbol("x")
y=sp.Symbol("y")
type(x)
```
%% Output
sympy.core.symbol.Symbol
%% Cell type:markdown id: tags:
The usual mathematical operations are defined for symbols:
%% Cell type:code id: tags:
``` python
expr=x**2*(y+x+5)+x**2
expr
```
%% Output
$\displaystyle x^{2} \left(x + y + 5\right) + x^{2}$
2 2
x ⋅(x + y + 5) + x
%% Cell type:markdown id: tags:
Now we can do all sorts of operations on these expressions: expand them, factor them, substitute variables:
$\displaystyle \left[ - x - 6 + \frac{1}{x^{2}}\right]$
⎡ 1 ⎤
⎢-x - 6 + ──⎥
⎢ 2⎥
⎣ x ⎦
%% Cell type:markdown id: tags:
A *sympy* expression is represented by an abstract syntax tree (AST), which can be inspected and modified.
%% Cell type:code id: tags:
``` python
expr
```
%% Output
$\displaystyle x^{2} \left(x + y + 5\right) + x^{2}$
2 2
x ⋅(x + y + 5) + x
%% Cell type:code id: tags:
``` python
ps.to_dot(expr,graph_style={'size':"9.5,12.5"})
```
%% Output
<graphviz.files.Source at 0x7fc7dc51b2e8>
<graphviz.files.Source at 0x7ff8a018e7f0>
%% Cell type:markdown id: tags:
Programatically the children node type is acessible as ``expr.func`` and its children as ``expr.args``.
With these members a tree can be traversed and modified.
%% Cell type:code id: tags:
``` python
expr.func
```
%% Output
sympy.core.add.Add
%% Cell type:code id: tags:
``` python
expr.args
```
%% Output
$\displaystyle \left( x^{2}, \ x^{2} \left(x + y + 5\right)\right)$
⎛ 2 2 ⎞
⎝x , x ⋅(x + y + 5)⎠
%% Cell type:markdown id: tags:
## Using *pystencils*
### Fields
*pystencils* is a module to generate code for stencil operations.
One has to specify an update rule for each element of an array, with optional dependencies to neighbors.
This is done use pure *sympy* with one addition: **Fields**.
Fields represent a multidimensional array, where some dimensions are considered *spatial*, and some as *index* dimensions. Spatial coordinates are given relative (i.e. one can specify "the current cell" and "the left neighbor") whereas index dimensions are used to index multiple values per cell.
%% Cell type:code id: tags:
``` python
my_field=ps.fields("f(3) : double[2D]")
```
%% Cell type:markdown id: tags:
Neighbors are labeled according to points on a compass where the first coordinate is west/east, second coordinate north/south and third coordinate top/bottom.
%% Cell type:code id: tags:
``` python
field_access=my_field[1,0](1)
field_access
```
%% Output
$\displaystyle {{f}_{(1,0)}^{1}}$
f_E__1
%% Cell type:markdown id: tags:
The result of indexing a field is an instance of ``Field.Access``. This class is a subclass of a *sympy* Symbol and thus can be used whereever normal symbols can be used. It is just like a normal symbol with some additional information attached to it.
%% Cell type:code id: tags:
``` python
isinstance(field_access,sp.Symbol)
```
%% Output
True
%% Cell type:markdown id: tags:
### Building our first stencil kernel
Lets start by building a simple filter kernel. We create a field representing an image, then define a edge detection filter on the third pixel component which is blue for an RGB image.
We have mixed some standard *sympy* symbols into this expression to possibly give the different directions different weights. The complete expression is still a valid *sympy* expression, so all features of *sympy* work on it. Lets for example now fix one weight by substituting it with a constant.
Now lets built an executable kernel out of it, which writes the result to a second field. Assignments are created using *pystencils*`Assignment` class, that gets the left- and right hand side of the assignment.
On our way we have created an ``ast``-object. We can inspect this, to see what *pystencils* actually does.
%% Cell type:code id: tags:
``` python
ps.to_dot(ast,graph_style={'size':"9.5,12.5"})
```
%% Output
<graphviz.files.Source at 0x7fc798393fd0>
<graphviz.files.Source at 0x7ff84a432e10>
%% Cell type:markdown id: tags:
*pystencils* also builds a tree structure of the program, where each `Assignment` node internally again has a *sympy* AST which is not printed here. Out of this representation *C* code can be generated:
Behind the scenes this code is compiled into a shared library and made available as a Python function. Before compiling this function we can modify the AST object, for example to parallelize it with OpenMP.
Compare this code to the version above. In this code the loop bounds and array offsets are constants, which usually leads to faster kernels.
%% Cell type:markdown id: tags:
### Running on GPU
If you have a CUDA enabled graphics card and [pycuda](https://mathema.tician.de/software/pycuda/) installed, *pystencils* can run your kernel on the GPU as well. You can find more details about this in the GPU tutorial.
In this tutorial we demonstrate how to use the discretization layer on top of *pystencils*, that defines how continuous differential operators are discretized. The result of this discretization layer are stencil equations which are used to generated C or CUDA code.
We are going to discretize the [advection diffusion equation](https://en.wikipedia.org/wiki/Convection%E2%80%93diffusion_equation) without reaction terms:
It describes how the concentration $c$ of a passive substance, which does not influence the flow field, behaves in a fluid with given velocity $v$.
To illustrate the two effects here, image we release a constant stream of dye at some point in a river. The dye is transported with the flow (advection) but also the trace gets wider and wider normal to the flow direction due to diffusion.