README.md 2.75 KB
Newer Older
1
2
3
pystencils
==========

4
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/mabau/pystencils/master?filepath=doc%2Fnotebooks)
Markus Holzer's avatar
Markus Holzer committed
5
[![Docs](https://img.shields.io/badge/read-the_docs-brightgreen.svg)](https://pycodegen.pages.i10git.cs.fau.de/pystencils)
Stephan Seitz's avatar
Stephan Seitz committed
6
[![pypi-package](https://badge.fury.io/py/pystencils.svg)](https://badge.fury.io/py/pystencils)
Martin Bauer's avatar
Martin Bauer committed
7
[![pipeline status](https://i10git.cs.fau.de/pycodegen/pystencils/badges/master/pipeline.svg)](https://i10git.cs.fau.de/pycodegen/pystencils/commits/master)
Markus Holzer's avatar
Markus Holzer committed
8
[![coverage report](https://i10git.cs.fau.de/pycodegen/pystencils/badges/master/coverage.svg)](http://pycodegen.pages.i10git.cs.fau.de/pystencils/coverage_report)
Martin Bauer's avatar
Martin Bauer committed
9

10
Run blazingly fast stencil codes on numpy arrays.
11

12
13
*pystencils* uses sympy to define stencil operations, that can be executed on numpy arrays.
Exploiting the stencil structure makes *pystencils* run faster than normal numpy code and even as Cython and numba,
Markus Holzer's avatar
Markus Holzer committed
14
[as demonstrated in this notebook](https://pycodegen.pages.i10git.cs.fau.de/pystencils/notebooks/demo_benchmark.html).
15

Martin Bauer's avatar
Martin Bauer committed
16
17
18
19
20
21
22
23

Here is a code snippet that computes the average of neighboring cells:
```python
import pystencils as ps
import numpy as np

f, g = ps.fields("f, g : [2D]")
stencil = ps.Assignment(g[0, 0],
Markus Holzer's avatar
Markus Holzer committed
24
                       (f[1, 0] + f[-1, 0] + f[0, 1] + f[0, -1]) / 4)
Martin Bauer's avatar
Martin Bauer committed
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
kernel = ps.create_kernel(stencil).compile()

f_arr = np.random.rand(1000, 1000)
g_arr = np.empty_like(f_arr)
kernel(f=f_arr, g=g_arr)
```

*pystencils* is mostly used for numerical simulations using finite difference or finite volume methods.
It comes with automatic finite difference discretization for PDEs:

```python
c, v = ps.fields("c, v(2): [2D]")
adv_diff_pde = ps.fd.transient(c) - ps.fd.diffusion(c, sp.symbols("D")) + ps.fd.advection(c, v)
discretize = ps.fd.Discretization2ndOrder(dx=1, dt=0.01)
discretization = discretize(adv_diff_pde)
```

42
43
44
45
46
47
48
49
50
51
Installation
------------

```bash
pip install pystencils[interactive]
```

Without `[interactive]` you get a minimal version with very little dependencies.

All options:
52
-  `gpu`: use this if an NVIDIA GPU is available and CUDA is installed
53
-  `opencl`: basic OpenCL support (experimental)
54
55
56
- `alltrafos`: pulls in additional dependencies for loop simplification e.g. libisl
- `bench_db`: functionality to store benchmark result in object databases
- `interactive`: installs dependencies to work in Jupyter including image I/O, plotting etc.
Stephan Seitz's avatar
Stephan Seitz committed
57
- `autodiff`: enable derivation of adjoint kernels and generation of Torch/Tensorflow operations
58
59
60
61
62
63
64
65
66
67
68
- `doc`: packages to build documentation

Options can be combined e.g.
```bash
pip install pystencils[interactive,gpu,doc]
```    


Documentation
-------------

Markus Holzer's avatar
Markus Holzer committed
69
Read the docs [here](https://pycodegen.pages.i10git.cs.fau.de/pystencils) and
Martin Bauer's avatar
Martin Bauer committed
70
check out the Jupyter notebooks in `doc/notebooks`.