Skip to content
Snippets Groups Projects
Commit 54ff216b authored by Michael Kuron's avatar Michael Kuron :mortar_board:
Browse files

fix ffmpeg check in tests

parent af1f8aa9
Branches
Tags
No related merge requests found
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
from pystencils.session import * from pystencils.session import *
``` ```
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
# Tutorial 01: Getting Started # Tutorial 01: Getting Started
## Overview ## Overview
*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. *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. 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. 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.
![Stencil](../img/pystencils_stencil_four_points_with_arrows.svg) ![Stencil](../img/pystencils_stencil_four_points_with_arrows.svg)
As the name suggests, *pystencils* was developed for **stencil codes**, i.e. operations that update array elements using only a local neighborhood. 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. 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: 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: %% Cell type:code id: tags:
``` python ``` python
input_arr = np.random.rand(1024, 1024) input_arr = np.random.rand(1024, 1024)
output_arr = np.zeros_like(input_arr) output_arr = np.zeros_like(input_arr)
``` ```
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
We first implement a version of this algorithm using pure numpy and benchmark it. We first implement a version of this algorithm using pure numpy and benchmark it.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
def numpy_kernel(): def numpy_kernel():
output_arr[1:-1, 1:-1] = input_arr[2:, 1:-1] + input_arr[:-2, 1:-1] + \ output_arr[1:-1, 1:-1] = input_arr[2:, 1:-1] + input_arr[:-2, 1:-1] + \
input_arr[1:-1, 2:] + input_arr[1:-1, :-2] input_arr[1:-1, 2:] + input_arr[1:-1, :-2]
``` ```
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
%%timeit %%timeit
numpy_kernel() numpy_kernel()
``` ```
%% Output %% Output
3.93 ms ± 40 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) 3.93 ms ± 40 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
Now lets see how to run the same algorithm with *pystencils*. Now lets see how to run the same algorithm with *pystencils*.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
src, dst = ps.fields(src=input_arr, dst=output_arr) src, dst = ps.fields(src=input_arr, dst=output_arr)
symbolic_description = ps.Assignment(dst[0,0], symbolic_description = ps.Assignment(dst[0,0],
(src[1, 0] + src[-1, 0] + src[0, 1] + src[0, -1]) / 4) (src[1, 0] + src[-1, 0] + src[0, 1] + src[0, -1]) / 4)
symbolic_description symbolic_description
``` ```
%% Output %% Output
$\displaystyle {{dst}_{(0,0)}} \leftarrow \frac{{{src}_{(-1,0)}}}{4} + \frac{{{src}_{(0,-1)}}}{4} + \frac{{{src}_{(0,1)}}}{4} + \frac{{{src}_{(1,0)}}}{4}$ $\displaystyle {{dst}_{(0,0)}} \leftarrow \frac{{{src}_{(-1,0)}}}{4} + \frac{{{src}_{(0,-1)}}}{4} + \frac{{{src}_{(0,1)}}}{4} + \frac{{{src}_{(1,0)}}}{4}$
src_W src_S src_N src_E src_W src_S src_N src_E
dst_C := ───── + ───── + ───── + ───── dst_C := ───── + ───── + ───── + ─────
4 4 4 4 4 4 4 4
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
plt.figure(figsize=(3,3)) plt.figure(figsize=(3,3))
ps.stencil.plot_expression(symbolic_description.rhs) ps.stencil.plot_expression(symbolic_description.rhs)
``` ```
%% Output %% Output
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
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. 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 description is then compiled and loaded as a Python function.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
kernel = ps.create_kernel(symbolic_description).compile() kernel = ps.create_kernel(symbolic_description).compile()
``` ```
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
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. 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. Now finally lets benchmark the *pystencils* kernel.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
def pystencils_kernel(): def pystencils_kernel():
kernel(src=input_arr, dst=output_arr) kernel(src=input_arr, dst=output_arr)
``` ```
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
%%timeit %%timeit
pystencils_kernel() pystencils_kernel()
``` ```
%% Output %% Output
643 µs ± 8.66 µ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: %% Cell type:markdown id: tags:
This benchmark shows that *pystencils* is a lot faster than pure *numpy*, especially for large arrays. 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). 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: %% Cell type:markdown id: tags:
## Short *sympy* introduction ## 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. 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). You can also read the full [sympy documentation here](http://docs.sympy.org/latest/index.html).
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
import sympy as sp import sympy as sp
sp.init_printing() # enable nice LaTeX output sp.init_printing() # enable nice LaTeX output
``` ```
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
*sympy* is a package for symbolic calculation. So first we need some symbols: *sympy* is a package for symbolic calculation. So first we need some symbols:
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
x = sp.Symbol("x") x = sp.Symbol("x")
y = sp.Symbol("y") y = sp.Symbol("y")
type(x) type(x)
``` ```
%% Output %% Output
sympy.core.symbol.Symbol sympy.core.symbol.Symbol
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
The usual mathematical operations are defined for symbols: The usual mathematical operations are defined for symbols:
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
expr = x**2 * ( y + x + 5) + x**2 expr = x**2 * ( y + x + 5) + x**2
expr expr
``` ```
%% Output %% Output
$\displaystyle x^{2} \left(x + y + 5\right) + x^{2}$ $\displaystyle x^{2} \left(x + y + 5\right) + x^{2}$
2 2 2 2
x ⋅(x + y + 5) + x x ⋅(x + y + 5) + x
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
Now we can do all sorts of operations on these expressions: expand them, factor them, substitute variables: Now we can do all sorts of operations on these expressions: expand them, factor them, substitute variables:
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
expr.expand() expr.expand()
``` ```
%% Output %% Output
$\displaystyle x^{3} + x^{2} y + 6 x^{2}$ $\displaystyle x^{3} + x^{2} y + 6 x^{2}$
3 2 2 3 2 2
x + x ⋅y + 6⋅x x + x ⋅y + 6⋅x
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
expr.factor() expr.factor()
``` ```
%% Output %% Output
$\displaystyle x^{2} \left(x + y + 6\right)$ $\displaystyle x^{2} \left(x + y + 6\right)$
2 2
x ⋅(x + y + 6) x ⋅(x + y + 6)
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
expr.subs(y, sp.cos(x)) expr.subs(y, sp.cos(x))
``` ```
%% Output %% Output
$\displaystyle x^{2} \left(x + \cos{\left(x \right)} + 5\right) + x^{2}$ $\displaystyle x^{2} \left(x + \cos{\left(x \right)} + 5\right) + x^{2}$
2 2 2 2
x ⋅(x + cos(x) + 5) + x x ⋅(x + cos(x) + 5) + x
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
We can also built equations and solve them We can also built equations and solve them
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
eq = sp.Eq(expr, 1) eq = sp.Eq(expr, 1)
eq eq
``` ```
%% Output %% Output
$\displaystyle x^{2} \left(x + y + 5\right) + x^{2} = 1$ $\displaystyle x^{2} \left(x + y + 5\right) + x^{2} = 1$
2 2 2 2
x ⋅(x + y + 5) + x = 1 x ⋅(x + y + 5) + x = 1
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
sp.solve(sp.Eq(expr, 1), y) sp.solve(sp.Eq(expr, 1), y)
``` ```
%% Output %% Output
$\displaystyle \left[ - x - 6 + \frac{1}{x^{2}}\right]$ $\displaystyle \left[ - x - 6 + \frac{1}{x^{2}}\right]$
⎡ 1 ⎤ ⎡ 1 ⎤
⎢-x - 6 + ──⎥ ⎢-x - 6 + ──⎥
⎢ 2⎥ ⎢ 2⎥
⎣ x ⎦ ⎣ x ⎦
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
A *sympy* expression is represented by an abstract syntax tree (AST), which can be inspected and modified. A *sympy* expression is represented by an abstract syntax tree (AST), which can be inspected and modified.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
expr expr
``` ```
%% Output %% Output
$\displaystyle x^{2} \left(x + y + 5\right) + x^{2}$ $\displaystyle x^{2} \left(x + y + 5\right) + x^{2}$
2 2 2 2
x ⋅(x + y + 5) + x x ⋅(x + y + 5) + x
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
ps.to_dot(expr, graph_style={'size': "9.5,12.5"} ) ps.to_dot(expr, graph_style={'size': "9.5,12.5"} )
``` ```
%% Output %% Output
<graphviz.files.Source at 0x7ff8a018e7f0> <graphviz.files.Source at 0x7ff8a018e7f0>
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
Programatically the children node type is acessible as ``expr.func`` and its children as ``expr.args``. 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. With these members a tree can be traversed and modified.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
expr.func expr.func
``` ```
%% Output %% Output
sympy.core.add.Add sympy.core.add.Add
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
expr.args expr.args
``` ```
%% Output %% Output
$\displaystyle \left( x^{2}, \ x^{2} \left(x + y + 5\right)\right)$ $\displaystyle \left( x^{2}, \ x^{2} \left(x + y + 5\right)\right)$
⎛ 2 2 ⎞ ⎛ 2 2 ⎞
⎝x , x ⋅(x + y + 5)⎠ ⎝x , x ⋅(x + y + 5)⎠
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
## Using *pystencils* ## Using *pystencils*
### Fields ### Fields
*pystencils* is a module to generate code for stencil operations. *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. 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**. 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. 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: %% Cell type:code id: tags:
``` python ``` python
my_field = ps.fields("f(3) : double[2D]") my_field = ps.fields("f(3) : double[2D]")
``` ```
%% Cell type:markdown id: tags: %% 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. 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: %% Cell type:code id: tags:
``` python ``` python
field_access = my_field[1, 0](1) field_access = my_field[1, 0](1)
field_access field_access
``` ```
%% Output %% Output
$\displaystyle {{f}_{(1,0)}^{1}}$ $\displaystyle {{f}_{(1,0)}^{1}}$
f_E__1 f_E__1
%% Cell type:markdown id: tags: %% 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. 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: %% Cell type:code id: tags:
``` python ``` python
isinstance(field_access, sp.Symbol) isinstance(field_access, sp.Symbol)
``` ```
%% Output %% Output
True True
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
### Building our first stencil kernel ### 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. 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.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
img_field = ps.fields("img(4): [2D]") img_field = ps.fields("img(4): [2D]")
``` ```
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
w1, w2 = sp.symbols("w_1 w_2") w1, w2 = sp.symbols("w_1 w_2")
color = 2 color = 2
sobel_x = (-w2 * img_field[-1,0](color) - w1 * img_field[-1,-1](color) - w1 * img_field[-1, +1](color) \ sobel_x = (-w2 * img_field[-1,0](color) - w1 * img_field[-1,-1](color) - w1 * img_field[-1, +1](color) \
+w2 * img_field[+1,0](color) + w1 * img_field[+1,-1](color) - w1 * img_field[+1, +1](color))**2 +w2 * img_field[+1,0](color) + w1 * img_field[+1,-1](color) - w1 * img_field[+1, +1](color))**2
sobel_x sobel_x
``` ```
%% Output %% Output
$\displaystyle \left(- {{img}_{(-1,-1)}^{2}} w_{1} - {{img}_{(-1,0)}^{2}} w_{2} - {{img}_{(-1,1)}^{2}} w_{1} + {{img}_{(1,-1)}^{2}} w_{1} + {{img}_{(1,0)}^{2}} w_{2} - {{img}_{(1,1)}^{2}} w_{1}\right)^{2}$ $\displaystyle \left(- {{img}_{(-1,-1)}^{2}} w_{1} - {{img}_{(-1,0)}^{2}} w_{2} - {{img}_{(-1,1)}^{2}} w_{1} + {{img}_{(1,-1)}^{2}} w_{1} + {{img}_{(1,0)}^{2}} w_{2} - {{img}_{(1,1)}^{2}} w_{1}\right)^{2}$
(-img_SW__2⋅w₁ - img_W__2⋅w₂ - img_NW__2⋅w₁ + img_SE__2⋅w₁ + img_E__2⋅w₂ - img (-img_SW__2⋅w₁ - img_W__2⋅w₂ - img_NW__2⋅w₁ + img_SE__2⋅w₁ + img_E__2⋅w₂ - img
2 2
_NE__2⋅w₁) _NE__2⋅w₁)
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
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. 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.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
sobel_x = sobel_x.subs(w1, 0.5) sobel_x = sobel_x.subs(w1, 0.5)
sobel_x sobel_x
``` ```
%% Output %% Output
$\displaystyle \left(- 0.5 {{img}_{(-1,-1)}^{2}} - {{img}_{(-1,0)}^{2}} w_{2} - 0.5 {{img}_{(-1,1)}^{2}} + 0.5 {{img}_{(1,-1)}^{2}} + {{img}_{(1,0)}^{2}} w_{2} - 0.5 {{img}_{(1,1)}^{2}}\right)^{2}$ $\displaystyle \left(- 0.5 {{img}_{(-1,-1)}^{2}} - {{img}_{(-1,0)}^{2}} w_{2} - 0.5 {{img}_{(-1,1)}^{2}} + 0.5 {{img}_{(1,-1)}^{2}} + {{img}_{(1,0)}^{2}} w_{2} - 0.5 {{img}_{(1,1)}^{2}}\right)^{2}$
(-0.5⋅img_SW__2 - img_W__2⋅w₂ - 0.5⋅img_NW__2 + 0.5⋅img_SE__2 + img_E__2⋅w₂ - (-0.5⋅img_SW__2 - img_W__2⋅w₂ - 0.5⋅img_NW__2 + 0.5⋅img_SE__2 + img_E__2⋅w₂ -
2 2
0.5⋅img_NE__2) 0.5⋅img_NE__2)
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
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. 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.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
dst_field = ps.fields('dst: [2D]' ) dst_field = ps.fields('dst: [2D]' )
update_rule = ps.Assignment(dst_field[0,0], sobel_x) update_rule = ps.Assignment(dst_field[0,0], sobel_x)
update_rule update_rule
``` ```
%% Output %% Output
$\displaystyle {{dst}_{(0,0)}} \leftarrow \left(- 0.5 {{img}_{(-1,-1)}^{2}} - {{img}_{(-1,0)}^{2}} w_{2} - 0.5 {{img}_{(-1,1)}^{2}} + 0.5 {{img}_{(1,-1)}^{2}} + {{img}_{(1,0)}^{2}} w_{2} - 0.5 {{img}_{(1,1)}^{2}}\right)^{2}$ $\displaystyle {{dst}_{(0,0)}} \leftarrow \left(- 0.5 {{img}_{(-1,-1)}^{2}} - {{img}_{(-1,0)}^{2}} w_{2} - 0.5 {{img}_{(-1,1)}^{2}} + 0.5 {{img}_{(1,-1)}^{2}} + {{img}_{(1,0)}^{2}} w_{2} - 0.5 {{img}_{(1,1)}^{2}}\right)^{2}$
dst_C := (-0.5⋅img_SW__2 - img_W__2⋅w₂ - 0.5⋅img_NW__2 + 0.5⋅img_SE__2 + img_E dst_C := (-0.5⋅img_SW__2 - img_W__2⋅w₂ - 0.5⋅img_NW__2 + 0.5⋅img_SE__2 + img_E
2 2
__2⋅w₂ - 0.5⋅img_NE__2) __2⋅w₂ - 0.5⋅img_NE__2)
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
Next we can see *pystencils* in action which creates a kernel for us. Next we can see *pystencils* in action which creates a kernel for us.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
from pystencils import create_kernel from pystencils import create_kernel
ast = create_kernel(update_rule, cpu_openmp=False) ast = create_kernel(update_rule, cpu_openmp=False)
compiled_kernel = ast.compile() compiled_kernel = ast.compile()
``` ```
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
This compiled kernel is now just an ordinary Python function. This compiled kernel is now just an ordinary Python function.
Now lets grab an image to apply this filter to: Now lets grab an image to apply this filter to:
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
try: try:
import requests import requests
import imageio import imageio
from io import BytesIO from io import BytesIO
response = requests.get("https://www.python.org/static/img/python-logo.png") response = requests.get("https://www.python.org/static/img/python-logo.png")
img = imageio.imread(BytesIO(response.content)).astype(np.double) img = imageio.imread(BytesIO(response.content)).astype(np.double)
img /= img.max() img /= img.max()
plt.imshow(img); plt.imshow(img);
except ImportError: except ImportError:
print("No requests installed") print("No requests installed")
img = np.random.random((82, 290, 4)) img = np.random.random((82, 290, 4))
``` ```
%% Output %% Output
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
if img: filtered_image = np.zeros_like(img[..., 0])
filtered_image = np.zeros_like(img[..., 0]) # here we call the compiled stencil function
# here we call the compiled stencil function compiled_kernel(img=img, dst=filtered_image, w_2=0.5)
compiled_kernel(img=img, dst=filtered_image, w_2=0.5) plt.imshow(filtered_image, cmap='gray');
plt.imshow(filtered_image, cmap='gray');
``` ```
%% Output %% Output
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
### Digging into *pystencils* ### Digging into *pystencils*
On our way we have created an ``ast``-object. We can inspect this, to see what *pystencils* actually does. On our way we have created an ``ast``-object. We can inspect this, to see what *pystencils* actually does.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
ps.to_dot(ast, graph_style={'size': "9.5,12.5"}) ps.to_dot(ast, graph_style={'size': "9.5,12.5"})
``` ```
%% Output %% Output
<graphviz.files.Source at 0x7ff84a432e10> <graphviz.files.Source at 0x7ff84a432e10>
%% Cell type:markdown id: tags: %% 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: *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:
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
ps.show_code(ast) ps.show_code(ast)
``` ```
%% Output %% Output
FUNC_PREFIX void kernel(double * RESTRICT _data_dst, double * RESTRICT const _data_img, int64_t const _size_dst_0, int64_t const _size_dst_1, int64_t const _stride_dst_0, int64_t const _stride_dst_1, int64_t const _stride_img_0, int64_t const _stride_img_1, int64_t const _stride_img_2, double w_2) FUNC_PREFIX void kernel(double * RESTRICT _data_dst, double * RESTRICT const _data_img, int64_t const _size_dst_0, int64_t const _size_dst_1, int64_t const _stride_dst_0, int64_t const _stride_dst_1, int64_t const _stride_img_0, int64_t const _stride_img_1, int64_t const _stride_img_2, double w_2)
{ {
double * RESTRICT const _data_img_22 = _data_img + 2*_stride_img_2; double * RESTRICT const _data_img_22 = _data_img + 2*_stride_img_2;
for (int ctr_0 = 1; ctr_0 < _size_dst_0 - 1; ctr_0 += 1) for (int ctr_0 = 1; ctr_0 < _size_dst_0 - 1; ctr_0 += 1)
{ {
double * RESTRICT _data_dst_00 = _data_dst + _stride_dst_0*ctr_0; double * RESTRICT _data_dst_00 = _data_dst + _stride_dst_0*ctr_0;
double * RESTRICT const _data_img_22_01 = _stride_img_0*ctr_0 + _stride_img_0 + _data_img_22; double * RESTRICT const _data_img_22_01 = _stride_img_0*ctr_0 + _stride_img_0 + _data_img_22;
double * RESTRICT const _data_img_22_0m1 = _stride_img_0*ctr_0 - _stride_img_0 + _data_img_22; double * RESTRICT const _data_img_22_0m1 = _stride_img_0*ctr_0 - _stride_img_0 + _data_img_22;
for (int ctr_1 = 1; ctr_1 < _size_dst_1 - 1; ctr_1 += 1) for (int ctr_1 = 1; ctr_1 < _size_dst_1 - 1; ctr_1 += 1)
{ {
_data_dst_00[_stride_dst_1*ctr_1] = ((w_2*_data_img_22_01[_stride_img_1*ctr_1] - w_2*_data_img_22_0m1[_stride_img_1*ctr_1] - 0.5*_data_img_22_01[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 - _stride_img_1] + 0.5*_data_img_22_01[_stride_img_1*ctr_1 - _stride_img_1])*(w_2*_data_img_22_01[_stride_img_1*ctr_1] - w_2*_data_img_22_0m1[_stride_img_1*ctr_1] - 0.5*_data_img_22_01[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 - _stride_img_1] + 0.5*_data_img_22_01[_stride_img_1*ctr_1 - _stride_img_1])); _data_dst_00[_stride_dst_1*ctr_1] = ((w_2*_data_img_22_01[_stride_img_1*ctr_1] - w_2*_data_img_22_0m1[_stride_img_1*ctr_1] - 0.5*_data_img_22_01[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 - _stride_img_1] + 0.5*_data_img_22_01[_stride_img_1*ctr_1 - _stride_img_1])*(w_2*_data_img_22_01[_stride_img_1*ctr_1] - w_2*_data_img_22_0m1[_stride_img_1*ctr_1] - 0.5*_data_img_22_01[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 - _stride_img_1] + 0.5*_data_img_22_01[_stride_img_1*ctr_1 - _stride_img_1]));
} }
} }
} }
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
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. 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.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
ast = ps.create_kernel(update_rule) ast = ps.create_kernel(update_rule)
ps.cpu.add_openmp(ast, num_threads=2) ps.cpu.add_openmp(ast, num_threads=2)
ps.show_code(ast) ps.show_code(ast)
``` ```
%% Output %% Output
FUNC_PREFIX void kernel(double * RESTRICT _data_dst, double * RESTRICT const _data_img, int64_t const _size_dst_0, int64_t const _size_dst_1, int64_t const _stride_dst_0, int64_t const _stride_dst_1, int64_t const _stride_img_0, int64_t const _stride_img_1, int64_t const _stride_img_2, double w_2) FUNC_PREFIX void kernel(double * RESTRICT _data_dst, double * RESTRICT const _data_img, int64_t const _size_dst_0, int64_t const _size_dst_1, int64_t const _stride_dst_0, int64_t const _stride_dst_1, int64_t const _stride_img_0, int64_t const _stride_img_1, int64_t const _stride_img_2, double w_2)
{ {
#pragma omp parallel num_threads(2) #pragma omp parallel num_threads(2)
{ {
double * RESTRICT const _data_img_22 = _data_img + 2*_stride_img_2; double * RESTRICT const _data_img_22 = _data_img + 2*_stride_img_2;
#pragma omp for schedule(static) #pragma omp for schedule(static)
for (int ctr_0 = 1; ctr_0 < _size_dst_0 - 1; ctr_0 += 1) for (int ctr_0 = 1; ctr_0 < _size_dst_0 - 1; ctr_0 += 1)
{ {
double * RESTRICT _data_dst_00 = _data_dst + _stride_dst_0*ctr_0; double * RESTRICT _data_dst_00 = _data_dst + _stride_dst_0*ctr_0;
double * RESTRICT const _data_img_22_01 = _stride_img_0*ctr_0 + _stride_img_0 + _data_img_22; double * RESTRICT const _data_img_22_01 = _stride_img_0*ctr_0 + _stride_img_0 + _data_img_22;
double * RESTRICT const _data_img_22_0m1 = _stride_img_0*ctr_0 - _stride_img_0 + _data_img_22; double * RESTRICT const _data_img_22_0m1 = _stride_img_0*ctr_0 - _stride_img_0 + _data_img_22;
for (int ctr_1 = 1; ctr_1 < _size_dst_1 - 1; ctr_1 += 1) for (int ctr_1 = 1; ctr_1 < _size_dst_1 - 1; ctr_1 += 1)
{ {
_data_dst_00[_stride_dst_1*ctr_1] = ((w_2*_data_img_22_01[_stride_img_1*ctr_1] - w_2*_data_img_22_0m1[_stride_img_1*ctr_1] - 0.5*_data_img_22_01[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 - _stride_img_1] + 0.5*_data_img_22_01[_stride_img_1*ctr_1 - _stride_img_1])*(w_2*_data_img_22_01[_stride_img_1*ctr_1] - w_2*_data_img_22_0m1[_stride_img_1*ctr_1] - 0.5*_data_img_22_01[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 - _stride_img_1] + 0.5*_data_img_22_01[_stride_img_1*ctr_1 - _stride_img_1])); _data_dst_00[_stride_dst_1*ctr_1] = ((w_2*_data_img_22_01[_stride_img_1*ctr_1] - w_2*_data_img_22_0m1[_stride_img_1*ctr_1] - 0.5*_data_img_22_01[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 - _stride_img_1] + 0.5*_data_img_22_01[_stride_img_1*ctr_1 - _stride_img_1])*(w_2*_data_img_22_01[_stride_img_1*ctr_1] - w_2*_data_img_22_0m1[_stride_img_1*ctr_1] - 0.5*_data_img_22_01[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 + _stride_img_1] - 0.5*_data_img_22_0m1[_stride_img_1*ctr_1 - _stride_img_1] + 0.5*_data_img_22_01[_stride_img_1*ctr_1 - _stride_img_1]));
} }
} }
} }
} }
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
loops = list(ast.atoms(ps.astnodes.LoopOverCoordinate)) loops = list(ast.atoms(ps.astnodes.LoopOverCoordinate))
l1 = loops[0] l1 = loops[0]
l1.prefix_lines.append("#pragma someting") l1.prefix_lines.append("#pragma someting")
l1.is_outermost_loop l1.is_outermost_loop
``` ```
%% Output %% Output
False False
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
### Fixed array sizes ### Fixed array sizes
Since we already know the arrays to which the kernel should be applied, we can Since we already know the arrays to which the kernel should be applied, we can
create *Field* objects with fixed size, based on a numpy array: create *Field* objects with fixed size, based on a numpy array:
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
img_field, dst_field = ps.fields("I(4), dst : [2D]", I=img.astype(np.double), dst=filtered_image) img_field, dst_field = ps.fields("I(4), dst : [2D]", I=img.astype(np.double), dst=filtered_image)
sobel_x = -2 * img_field[-1,0](1) - img_field[-1,-1](1) - img_field[-1, +1](1) \ sobel_x = -2 * img_field[-1,0](1) - img_field[-1,-1](1) - img_field[-1, +1](1) \
+2 * img_field[+1,0](1) + img_field[+1,-1](1) - img_field[+1, +1](1) +2 * img_field[+1,0](1) + img_field[+1,-1](1) - img_field[+1, +1](1)
update_rule = ps.Assignment(dst_field[0,0], sobel_x) update_rule = ps.Assignment(dst_field[0,0], sobel_x)
ast = create_kernel(update_rule) ast = create_kernel(update_rule)
ps.show_code(ast) ps.show_code(ast)
``` ```
%% Output %% Output
FUNC_PREFIX void kernel(double * RESTRICT const _data_I, double * RESTRICT _data_dst) FUNC_PREFIX void kernel(double * RESTRICT const _data_I, double * RESTRICT _data_dst)
{ {
double * RESTRICT const _data_I_21 = _data_I + 1; double * RESTRICT const _data_I_21 = _data_I + 1;
for (int ctr_0 = 1; ctr_0 < 81; ctr_0 += 1) for (int ctr_0 = 1; ctr_0 < 81; ctr_0 += 1)
{ {
double * RESTRICT _data_dst_00 = _data_dst + 290*ctr_0; double * RESTRICT _data_dst_00 = _data_dst + 290*ctr_0;
double * RESTRICT const _data_I_21_01 = _data_I_21 + 1160*ctr_0 + 1160; double * RESTRICT const _data_I_21_01 = _data_I_21 + 1160*ctr_0 + 1160;
double * RESTRICT const _data_I_21_0m1 = _data_I_21 + 1160*ctr_0 - 1160; double * RESTRICT const _data_I_21_0m1 = _data_I_21 + 1160*ctr_0 - 1160;
for (int ctr_1 = 1; ctr_1 < 289; ctr_1 += 1) for (int ctr_1 = 1; ctr_1 < 289; ctr_1 += 1)
{ {
_data_dst_00[ctr_1] = -2*_data_I_21_0m1[4*ctr_1] + 2*_data_I_21_01[4*ctr_1] - _data_I_21_01[4*ctr_1 + 4] + _data_I_21_01[4*ctr_1 - 4] - _data_I_21_0m1[4*ctr_1 + 4] - _data_I_21_0m1[4*ctr_1 - 4]; _data_dst_00[ctr_1] = -2*_data_I_21_0m1[4*ctr_1] + 2*_data_I_21_01[4*ctr_1] - _data_I_21_01[4*ctr_1 + 4] + _data_I_21_01[4*ctr_1 - 4] - _data_I_21_0m1[4*ctr_1 + 4] - _data_I_21_0m1[4*ctr_1 - 4];
} }
} }
} }
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
Compare this code to the version above. In this code the loop bounds and array offsets are constants, which usually leads to faster kernels. 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: %% Cell type:markdown id: tags:
### Running on GPU ### 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. 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.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
gpu_ast = create_kernel(update_rule, target='gpu', gpu_indexing=ps.gpucuda.indexing.BlockIndexing, gpu_ast = create_kernel(update_rule, target='gpu', gpu_indexing=ps.gpucuda.indexing.BlockIndexing,
gpu_indexing_params={'blockSize': (8,8,4)}) gpu_indexing_params={'blockSize': (8,8,4)})
``` ```
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
ps.show_code(gpu_ast) ps.show_code(gpu_ast)
``` ```
%% Output %% Output
FUNC_PREFIX __launch_bounds__(256) void kernel(double * RESTRICT const _data_I, double * RESTRICT _data_dst) FUNC_PREFIX __launch_bounds__(256) void kernel(double * RESTRICT const _data_I, double * RESTRICT _data_dst)
{ {
if (blockDim.x*blockIdx.x + threadIdx.x + 1 < 81 && blockDim.y*blockIdx.y + threadIdx.y + 1 < 289) if (blockDim.x*blockIdx.x + threadIdx.x + 1 < 81 && blockDim.y*blockIdx.y + threadIdx.y + 1 < 289)
{ {
const int64_t ctr_0 = blockDim.x*blockIdx.x + threadIdx.x + 1; const int64_t ctr_0 = blockDim.x*blockIdx.x + threadIdx.x + 1;
const int64_t ctr_1 = blockDim.y*blockIdx.y + threadIdx.y + 1; const int64_t ctr_1 = blockDim.y*blockIdx.y + threadIdx.y + 1;
double * RESTRICT _data_dst_10 = _data_dst + ctr_1; double * RESTRICT _data_dst_10 = _data_dst + ctr_1;
double * RESTRICT const _data_I_11_21 = _data_I + 4*ctr_1 + 5; double * RESTRICT const _data_I_11_21 = _data_I + 4*ctr_1 + 5;
double * RESTRICT const _data_I_1m1_21 = _data_I + 4*ctr_1 - 3; double * RESTRICT const _data_I_1m1_21 = _data_I + 4*ctr_1 - 3;
double * RESTRICT const _data_I_10_21 = _data_I + 4*ctr_1 + 1; double * RESTRICT const _data_I_10_21 = _data_I + 4*ctr_1 + 1;
_data_dst_10[290*ctr_0] = -2*_data_I_10_21[1160*ctr_0 - 1160] + 2*_data_I_10_21[1160*ctr_0 + 1160] - _data_I_11_21[1160*ctr_0 + 1160] - _data_I_11_21[1160*ctr_0 - 1160] + _data_I_1m1_21[1160*ctr_0 + 1160] - _data_I_1m1_21[1160*ctr_0 - 1160]; _data_dst_10[290*ctr_0] = -2*_data_I_10_21[1160*ctr_0 - 1160] + 2*_data_I_10_21[1160*ctr_0 + 1160] - _data_I_11_21[1160*ctr_0 + 1160] - _data_I_11_21[1160*ctr_0 - 1160] + _data_I_1m1_21[1160*ctr_0 + 1160] - _data_I_1m1_21[1160*ctr_0 - 1160];
} }
} }
......
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
from pystencils.session import * from pystencils.session import *
import shutil
``` ```
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
# Plotting and Animation # Plotting and Animation
   
   
## 1) Stencils ## 1) Stencils
   
This section shows how to visualize stencils, i.e. lists of directions This section shows how to visualize stencils, i.e. lists of directions
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
stencil_5pt = [(0, 0), (1, 0), (-1, 0), (0, 1), (0, -1)] stencil_5pt = [(0, 0), (1, 0), (-1, 0), (0, 1), (0, -1)]
plt.figure(figsize=(2, 2)) plt.figure(figsize=(2, 2))
ps.stencil.plot(stencil_5pt) ps.stencil.plot(stencil_5pt)
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
By default the indices are shown the arrow endpoints. By default the indices are shown the arrow endpoints.
Custom data can also be plotted: Custom data can also be plotted:
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.figure(figsize=(2, 2)) plt.figure(figsize=(2, 2))
ps.stencil.plot(stencil_5pt, data=[2.0, 5, 'test', 42, 1]) ps.stencil.plot(stencil_5pt, data=[2.0, 5, 'test', 42, 1])
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
The stencil can also be given as an expression in a single field The stencil can also be given as an expression in a single field
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
f = ps.fields("f: [2D]") f = ps.fields("f: [2D]")
c = sp.symbols("c") c = sp.symbols("c")
expr = f[0, 0] + 2 * f[1, 0] + c * f[-1, 0] + 4 * f[0, 1] - c**2 * f[0, -1] expr = f[0, 0] + 2 * f[1, 0] + c * f[-1, 0] + 4 * f[0, 1] - c**2 * f[0, -1]
plt.figure(figsize=(2, 2)) plt.figure(figsize=(2, 2))
ps.stencil.plot_expression(expr) ps.stencil.plot_expression(expr)
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
There is also a function to simply plot sympy expressions depending on one variable only: There is also a function to simply plot sympy expressions depending on one variable only:
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
x = sp.symbols("x") x = sp.symbols("x")
plt.figure(figsize=(4, 4)) plt.figure(figsize=(4, 4))
plt.sympy_function(x**2 - 1, x_values=np.linspace(-2, 2)); plt.sympy_function(x**2 - 1, x_values=np.linspace(-2, 2));
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
Three dimensional stencils can be visualized in two different ways Three dimensional stencils can be visualized in two different ways
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
stencil_7pt = [(0, 0, 0), (1, 0, 0), (-1, 0, 0), (0, 1, 0), (0, -1, 0), (0, 0, 1), (0, 0, -1)] stencil_7pt = [(0, 0, 0), (1, 0, 0), (-1, 0, 0), (0, 1, 0), (0, -1, 0), (0, 0, 1), (0, 0, -1)]
ps.stencil.plot(stencil_7pt, data=[i for i in range(7)]) ps.stencil.plot(stencil_7pt, data=[i for i in range(7)])
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
This kind of plot works well for small stencils, for larger stencils this gets messy: This kind of plot works well for small stencils, for larger stencils this gets messy:
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
stencil_27pt = [(i, j, k) for i in (-1, 0, 1) for j in (-1, 0, 1) for k in (-1, 0, 1)] stencil_27pt = [(i, j, k) for i in (-1, 0, 1) for j in (-1, 0, 1) for k in (-1, 0, 1)]
ps.stencil.plot(stencil_27pt, data=[i for i in range(27)]) ps.stencil.plot(stencil_27pt, data=[i for i in range(27)])
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
Adding `slice=True` shows the three projections of the stencils instead Adding `slice=True` shows the three projections of the stencils instead
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
ps.stencil.plot(stencil_27pt, data=[i for i in range(27)], slice=True) ps.stencil.plot(stencil_27pt, data=[i for i in range(27)], slice=True)
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
## 2) Scalar fields ## 2) Scalar fields
   
*pystencils* also comes with helper functions to plot simulation data. *pystencils* also comes with helper functions to plot simulation data.
The plotting functions are simple but useful wrappers around basic Matplotlib functionality. The plotting functions are simple but useful wrappers around basic Matplotlib functionality.
*pystencils* imports all matplotlib functions as well, such that one can use *pystencils* imports all matplotlib functions as well, such that one can use
   
```import pystencils.plot as plt``` ```import pystencils.plot as plt```
   
instead of instead of
   
```import matplotlib.pyplot as plt``` ```import matplotlib.pyplot as plt```
   
The session import at the top of the notebook does this already, and also sets up inline plotting for notebooks. The session import at the top of the notebook does this already, and also sets up inline plotting for notebooks.
   
This section demonstrates how to plot 2D scalar fields. Internally `imshow` from matplotlib is used, however the coordinate system is changed such that (0,0) is in the lower left corner, the $x$-axis points to the right, and the $y$-axis upward. This section demonstrates how to plot 2D scalar fields. Internally `imshow` from matplotlib is used, however the coordinate system is changed such that (0,0) is in the lower left corner, the $x$-axis points to the right, and the $y$-axis upward.
   
The next function returns a scalar field for demonstration The next function returns a scalar field for demonstration
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
def example_scalar_field(t=0): def example_scalar_field(t=0):
x, y = np.meshgrid(np.linspace(0, 2 * np.pi, 100), np.linspace(0, 2 * np.pi, 100)) x, y = np.meshgrid(np.linspace(0, 2 * np.pi, 100), np.linspace(0, 2 * np.pi, 100))
z = np.cos(x + 0.1 * t) * np.sin(y + 0.1 * t) + 0.1 * x * y z = np.cos(x + 0.1 * t) * np.sin(y + 0.1 * t) + 0.1 * x * y
return z return z
``` ```
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
To show a single scalar field use `plt.scalar_field`: To show a single scalar field use `plt.scalar_field`:
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
arr = example_scalar_field() arr = example_scalar_field()
plt.scalar_field(arr) plt.scalar_field(arr)
plt.colorbar(); plt.colorbar();
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
A similar wrapper around `counter` from matplotlib A similar wrapper around `counter` from matplotlib
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.scalar_field_contour(arr); plt.scalar_field_contour(arr);
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
A 3D surface plot is also possible: A 3D surface plot is also possible:
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.scalar_field_surface(arr) plt.scalar_field_surface(arr)
``` ```
   
%% Output %% Output
   
<mpl_toolkits.mplot3d.art3d.Poly3DCollection at 0x7f38908f9828> <mpl_toolkits.mplot3d.art3d.Poly3DCollection at 0x7f38908f9828>
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
For simulation results one often needs visualization of time dependent results. To show an evolving scalar field an animation can be created as shown in the next cell For simulation results one often needs visualization of time dependent results. To show an evolving scalar field an animation can be created as shown in the next cell
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
t = 0 t = 0
def run_func(): def run_func():
global t global t
t += 1 t += 1
return example_scalar_field(t) return example_scalar_field(t)
``` ```
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
if shutil.which("ffmpeg") is not None: if shutil.which("ffmpeg") is not None:
plt.figure() plt.figure()
animation = plt.scalar_field_animation(run_func, frames=60) animation = plt.scalar_field_animation(run_func, frames=60)
ps.jupyter.display_as_html_video(animation) ps.jupyter.display_as_html_video(animation)
else: else:
print("No ffmpeg installed") print("No ffmpeg installed")
``` ```
   
%% Output %% Output
   
<IPython.core.display.HTML object> <IPython.core.display.HTML object>
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
Another way to display animations is as an image sequence. While the `run_func` i.e. the simulation is running the current state is then displayed as HTML image. Use this method when your `run_func` takes a long time and you want to see the status while the simulation runs. The `frames` parameter specifies how often the run function will be called. Another way to display animations is as an image sequence. While the `run_func` i.e. the simulation is running the current state is then displayed as HTML image. Use this method when your `run_func` takes a long time and you want to see the status while the simulation runs. The `frames` parameter specifies how often the run function will be called.
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.figure() plt.figure()
animation = plt.scalar_field_animation(run_func, frames=30) animation = plt.scalar_field_animation(run_func, frames=30)
ps.jupyter.display_as_html_image(animation) ps.jupyter.display_as_html_image(animation)
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
For surface plots there is also an animated version: For surface plots there is also an animated version:
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
if shutil.which("ffmpeg") is not None: if shutil.which("ffmpeg") is not None:
animation = plt.surface_plot_animation(run_func, frames=60) animation = plt.surface_plot_animation(run_func, frames=60)
ps.jupyter.display_as_html_video(animation) ps.jupyter.display_as_html_video(animation)
else: else:
print("No ffmpeg installed") print("No ffmpeg installed")
``` ```
   
%% Output %% Output
   
<IPython.core.display.HTML object> <IPython.core.display.HTML object>
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
## 3) Vector Fields ## 3) Vector Fields
   
*pystencils* provides another set of plotting functions for vector fields, e.g. velocity fields. *pystencils* provides another set of plotting functions for vector fields, e.g. velocity fields.
They have three index dimensions, where the last coordinate has to have 2 entries, representing the $x$ and $y$ component of the vector. They have three index dimensions, where the last coordinate has to have 2 entries, representing the $x$ and $y$ component of the vector.
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
def example_vector_field(t=0, shape=(40, 40)): def example_vector_field(t=0, shape=(40, 40)):
result = np.empty(shape + (2,)) result = np.empty(shape + (2,))
x, y = np.meshgrid(np.linspace(0, 2 * np.pi, shape[0]), np.linspace(0, 2 * np.pi, shape[1])) x, y = np.meshgrid(np.linspace(0, 2 * np.pi, shape[0]), np.linspace(0, 2 * np.pi, shape[1]))
result[..., 0] = np.cos(x + 0.1 * t) * np.sin(y + 0.1 * t) + 0.01 * x * y result[..., 0] = np.cos(x + 0.1 * t) * np.sin(y + 0.1 * t) + 0.01 * x * y
result[..., 1] = np.cos(0.001 * y) result[..., 1] = np.cos(0.001 * y)
return result return result
``` ```
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
Vector fields can either be plotted using quivers (arrows) Vector fields can either be plotted using quivers (arrows)
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.figure() plt.figure()
data = example_vector_field() data = example_vector_field()
plt.vector_field(data, step=1); plt.vector_field(data, step=1);
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
The `step` parameter can be used to display only every $n$'th arrow: The `step` parameter can be used to display only every $n$'th arrow:
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.figure() plt.figure()
plt.vector_field(data, step=2); plt.vector_field(data, step=2);
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
or by displaying their magnitude in a colormap or by displaying their magnitude in a colormap
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.figure() plt.figure()
plt.vector_field_magnitude(data); plt.vector_field_magnitude(data);
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
There are also functions to animate both variants, quiver plots.. There are also functions to animate both variants, quiver plots..
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
t = 0 t = 0
def run_func(): def run_func():
global t global t
t += 1 t += 1
return example_vector_field(t) return example_vector_field(t)
``` ```
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
if shutil.which("ffmpeg") is not None: if shutil.which("ffmpeg") is not None:
plt.figure() plt.figure()
animation = plt.vector_field_animation(run_func, frames=60) animation = plt.vector_field_animation(run_func, frames=60)
ps.jupyter.display_as_html_video(animation) ps.jupyter.display_as_html_video(animation)
else: else:
print("No ffmpeg installed") print("No ffmpeg installed")
``` ```
   
%% Output %% Output
   
<IPython.core.display.HTML object> <IPython.core.display.HTML object>
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
...and magnitude plots ...and magnitude plots
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
if shutil.which("ffmpeg") is not None: if shutil.which("ffmpeg") is not None:
animation = plt.vector_field_magnitude_animation(run_func, frames=60) animation = plt.vector_field_magnitude_animation(run_func, frames=60)
ps.jupyter.display_as_html_video(animation) ps.jupyter.display_as_html_video(animation)
else: else:
print("No ffmpeg installed") print("No ffmpeg installed")
``` ```
   
%% Output %% Output
   
<IPython.core.display.HTML object> <IPython.core.display.HTML object>
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
## 4) Phase Fields ## 4) Phase Fields
   
A third group of plotting functions helps to display arrays as they occur in phase-field simulations. However these function may also be useful for other kinds of simulations. A third group of plotting functions helps to display arrays as they occur in phase-field simulations. However these function may also be useful for other kinds of simulations.
They expect arrays where the last coordinate indicates the fraction of a certain component, i.e. `arr[x, y, 2]` should be a value between $0$ and $1$ and specifies the fraction of the third phase at $(x, y)$. The plotting functions expect that sum over the last coordinate gives $1$ for all cells. They expect arrays where the last coordinate indicates the fraction of a certain component, i.e. `arr[x, y, 2]` should be a value between $0$ and $1$ and specifies the fraction of the third phase at $(x, y)$. The plotting functions expect that sum over the last coordinate gives $1$ for all cells.
   
Lets again generate some example data Lets again generate some example data
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
def example_phase_field(): def example_phase_field():
from scipy.ndimage.filters import gaussian_filter from scipy.ndimage.filters import gaussian_filter
   
shape=(80, 80) shape=(80, 80)
result = np.zeros(shape + (4,)) result = np.zeros(shape + (4,))
result[20:40, 20:40, 0] = 1 result[20:40, 20:40, 0] = 1
gaussian_filter(result[..., 0], sigma=3, output=result[..., 0]) gaussian_filter(result[..., 0], sigma=3, output=result[..., 0])
result[50:70, 30:50, 1] = 1 result[50:70, 30:50, 1] = 1
gaussian_filter(result[..., 1], sigma=3, output=result[..., 1]) gaussian_filter(result[..., 1], sigma=3, output=result[..., 1])
   
result[:, :10, 2] = 1 result[:, :10, 2] = 1
result[:, :, 3] = 1 - np.sum(result, axis=2) result[:, :, 3] = 1 - np.sum(result, axis=2)
return result return result
data = example_phase_field() data = example_phase_field()
``` ```
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
The `scalar_field_alpha_value` function uses the last entry, i.e. the value between 0 and 1 as alpha value of the specified color to show where the phase is located. This visualization makes it easy to distinguish between smooth and sharp transitions. The `scalar_field_alpha_value` function uses the last entry, i.e. the value between 0 and 1 as alpha value of the specified color to show where the phase is located. This visualization makes it easy to distinguish between smooth and sharp transitions.
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.scalar_field_alpha_value(data[..., 0], color='b') plt.scalar_field_alpha_value(data[..., 0], color='b')
plt.scalar_field_alpha_value(data[..., 1], color='r'); plt.scalar_field_alpha_value(data[..., 1], color='r');
plt.scalar_field_alpha_value(data[..., 2], color='k'); plt.scalar_field_alpha_value(data[..., 2], color='k');
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
To see all existing phases the `phase_plot` function uses this alpha-value representation for all phases. To see all existing phases the `phase_plot` function uses this alpha-value representation for all phases.
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.phase_plot(data) plt.phase_plot(data)
``` ```
   
%% Output %% Output
   
   
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
   
Another option to display each field separately in a subplot Another option to display each field separately in a subplot
   
%% Cell type:code id: tags: %% Cell type:code id: tags:
   
``` python ``` python
plt.multiple_scalar_fields(data) plt.multiple_scalar_fields(data)
``` ```
   
%% Output %% Output
   
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment