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`.