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

4
5
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/mabau/pystencils/master?filepath=doc%2Fnotebooks)
[![Docs](https://img.shields.io/badge/read-the_docs-brightgreen.svg)](http://pycodegen.pages.walberla.net/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)
Martin Bauer's avatar
Martin Bauer committed
8
[![coverage report](https://i10git.cs.fau.de/pycodegen/pystencils/badges/master/coverage.svg)](http://pycodegen.pages.walberla.net/pystencils/coverage_report)
Martin Bauer's avatar
Martin Bauer committed
9

10
Run blazingly fast stencil codes on numpy arrays.
11

12
13
14
15
*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,
[as demonstrated in this notebook](http://pycodegen.pages.walberla.net/pystencils/notebooks/demo_benchmark.html).

Martin Bauer's avatar
Martin Bauer committed
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

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],
                        (f[1, 0] + f[-1, 0] + f[0, 1] + f[0, -1]) / 4)
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)
```

Look at the [documentation](http://pycodegen.pages.walberla.net/pystencils) to learn more.
43

44
45
46
47
48
49
50
51
52
53
54

Installation
------------

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

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

All options:
55
-  `gpu`: use this if an NVIDIA GPU is available and CUDA is installed
56
-  `opencl`: basic OpenCL support (experimental)
57
58
59
- `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
60
- `autodiff`: enable derivation of adjoint kernels and generation of Torch/Tensorflow operations
61
62
63
64
65
66
67
68
69
70
71
- `doc`: packages to build documentation

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


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

Martin Bauer's avatar
Martin Bauer committed
72
73
Read the docs [here](http://pycodegen.pages.walberla.net/pystencils) and
check out the Jupyter notebooks in `doc/notebooks`.