pystencils 2.0 Development Branch

You are currently viewing the development branch v2.0-dev for pystencils 2.0. This version marks a complete redesign of pystencil's internal structure. The type system, code generators, and just-in-time-compilers are being completely rebuilt here.

Early Adoption

The development version of pystencils is now ready for early adoption by users. Install the current pre-release version either directly through pip:

pip install "git+https://i10git.cs.fau.de/pycodegen/pystencils.git@v2.0-dev"

Or clone the repository locally and do an editable install:

git clone -b v2.0-dev https://i10git.cs.fau.de/pycodegen/pystencils.git
pip install -e pystencils

Documentation

Documentation for this development branch is currently served separately at https://da15siwa.pages.i10git.cs.fau.de/dev-docs/pystencils-nbackend/

Contributing

To contribute patches to pystencils 2.0, fork the repository as described in CONTRIBUTING and branch off from the v2.0-dev branch. Once you're finished coding, create a merge request onto that same branch and wait for it to be reviewed.

pystencils

Run blazingly fast stencil codes on numpy arrays.

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.

Here is a code snippet that computes the average of neighboring cells:

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:

import pystencils as ps
import sympy as sp

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)

Installation

pip install pystencils[interactive]

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

All options:

• gpu: use this if an NVIDIA or AMD GPU is available and CUDA or ROCm is installed
• 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.

pip install pystencils[interactive, gpu, doc]

pystencils is also fully compatible with Windows machines. If working with visual studio and cupy makes sure to run example files first to ensure that cupy can find the compiler's executable.

Documentation

Read the docs here and check out the Jupyter notebooks in doc/notebooks. The Changelog of pystencils can be found here.

Authors

Many thanks go to the contributors of pystencils.

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

Performance Modelling:

• D. Ernst et al, Analytical performance estimation during code generation on modern GPUs. Journal of Parallel and Distributed Computing, 2023. https://doi.org/10.1016/j.jpdc.2022.11.003