README.md 3.37 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
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
Markus Holzer's avatar
Markus Holzer committed
36
37
38
import pystencils as ps
import sympy as sp

Martin Bauer's avatar
Martin Bauer committed
39
40
41
42
43
44
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)
```

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:
Markus Holzer's avatar
Markus Holzer committed
55
- `gpu`: use this if an NVIDIA GPU is available and CUDA is installed
56
57
58
59
60
61
62
- `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.
- `doc`: packages to build documentation

Options can be combined e.g.
```bash
Markus Holzer's avatar
Markus Holzer committed
63
64
65
pip install pystencils[interactive, gpu, doc]
```

Markus Holzer's avatar
Markus Holzer committed
66
pystencils is also fully compatible with Windows machines. If working with visual studio and pycuda makes sure to run example files first to ensure that pycuda can find the compiler's executable.
67
68
69
70

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

Markus Holzer's avatar
Markus Holzer committed
71
Read the docs [here](https://pycodegen.pages.i10git.cs.fau.de/pystencils) and
Markus Holzer's avatar
Markus Holzer committed
72
check out the Jupyter notebooks in `doc/notebooks`. The **Changelog** of pystencils can be found [here](https://i10git.cs.fau.de/pycodegen/pystencils/-/blob/master/CHANGELOG.md).
73
74
75
76

Authors
-------

Markus Holzer's avatar
Markus Holzer committed
77
Many thanks go to the [contributors](https://i10git.cs.fau.de/pycodegen/pystencils/-/blob/master/AUTHORS.txt) of pystencils.
78
79
80
81
82
83
84

### Please cite us

If you use pystencils in a publication, please cite the following articles:

Overview:
  - M. Bauer et al, Code Generation for Massively Parallel Phase-Field Simulations. Association for Computing Machinery, 2019. https://doi.org/10.1145/3295500.3356186