1 Getting started

1.1 When (not) to use the package

py-pde provides a straight-forward way to simulate partial differential equations (PDEs) using a finite-difference scheme. Advantages of this approach include:

• Supports non-linear PDEs with complex boundary conditions.

• Direct specification of the evolution equations using a syntax that is similar to the underlying mathematical equations.

• Supports collections of multiple fields of vectorial or tensorial character.

However, there are of course also disadvantages to the approach taken by py-pde:

• Only suited for simple geometries (like rectangles, disks, or cylinders) with a fixed discretization.

• Optimized for PDEs that describe the time-evolution of a physical system. Neither time-independent systems nor integro-differential equation are fully supported.

• Finite-differences can lead to numerical instabilities.

• Provided generic solvers might not be most suitable choice for particular equations.

1.2 Installation

The py-pde package is developed for python 3.9 and has been tested up to version 3.12 under Linux, Windows, and macOS. Before you can start using the package, you need to install it using one of the following methods.

1.2.1 Install using pip

The package is available on pypi, so you should be able to install it by running

pip install py-pde

In order to have all features of the package available, you might also want to install the following optional packages:

pip install h5py pandas pyfftw tqdm

Moreover, ffmpeg needs to be installed and for creating movies.

1.2.2 Install using conda

The py-pde package is also available on conda using the conda-forge channel. You can thus install it using

conda install -c conda-forge py-pde

This installation includes many dependencies to have most features of py-pde.

1.2.3 Install from source

Installing from source can be necessary if the pypi installation does not work or if the latest source code should be installed from github.

1.2.3.1 Required prerequisites

The code builds on other python packages, which need to be installed for py-pde to function properly. The required packages are listed in the table below:

Package	Minimal version	Usage
matplotlib	3.1	Visualizing results
numba	0.59	Just-in-time compilation to accelerate numerics
numpy	1.22	Handling numerical data
scipy	1.10	Miscellaneous scientific functions
sympy	1.9	Dealing with user-defined mathematical expressions
tqdm	4.66	Display progress bars during calculations

The simplest way to install these packages is to use the requirements.txt in the base folder:

pip install -r requirements.txt

Alternatively, these package can be installed via your operating system’s package manager, e.g. using macports, homebrew, or conda. The package versions given above are minimal requirements, although this is not tested systematically. Generally, it should help to install the latest version of the package.

1.2.3.2 Optional packages

The following packages should be installed to use some miscellaneous features:

Package	Minimal version	Usage
ffmpeg-python	0.2	Reading and writing videos
h5py	2.10	Storing data in the hierarchical file format
ipywidgets	8	Jupyter notebook support
mpi4py	3	Parallel processing using MPI
napari	0.4.8	Displaying images interactively
numba-mpi	0.22	Parallel processing using MPI+numba
pandas	2	Handling tabular data
py-modelrunner	0.18	Running simulations and handling I/O
pyfftw	0.12	Faster Fourier transforms
rocket-fft	0.2.4	Numba-compiled fast Fourier transforms

For making movies, the ffmpeg should be available. Additional packages might be required for running the tests in the folder tests and to build the documentation in the folder docs. These packages are listed in the files requirements.txt in the respective folders.

1.2.3.3 Downloading py-pde

The package can be simply checked out from github.com/zwicker-group/py-pde. To import the package from any python session, it might be convenient to include the root folder of the package into the PYTHONPATH environment variable.

This documentation can be built by calling the make html in the docs folder. The final documentation will be available in docs/build/html. Note that a LaTeX documentation can be build using make latexpdf.

1.3 Package overview

The main aim of the pde package is to simulate partial differential equations in simple geometries. Here, the time evolution of a PDE is determined using the method of lines by explicitly discretizing space using fixed grids. The differential operators are implemented using the finite difference method. For simplicity, we consider only regular, orthogonal grids, where each axis has a uniform discretization and all axes are (locally) orthogonal. Currently, we support simulations on CartesianGrid, PolarSymGrid, SphericalSymGrid, and CylindricalSymGrid, with and without periodic boundaries where applicable.

Fields are defined by specifying values at the grid points using the classes ScalarField, VectorField, and Tensor2Field. These classes provide methods for applying differential operators to the fields, e.g., the result of applying the Laplacian to a scalar field is returned by calling the method laplace(), which returns another instance of ScalarField, whereas gradient() returns a VectorField. Combining these functions with ordinary arithmetics on fields allows to represent the right hand side of many partial differential equations that appear in physics. Importantly, the differential operators work with flexible boundary conditions.

The PDEs to solve are represented as a separate class inheriting from PDEBase. One example defined in this package is the diffusion equation implemented as DiffusionPDE, but more specific situations need to be implemented by the user. Most notably, PDEs can be specified by their expression using the convenient PDE class.

The PDEs are solved using solver classes, where a simple explicit solver is implemented by ExplicitSolver, but more advanced implementations can be done. To obtain more details during the simulation, trackers can be attached to the solver instance, which analyze intermediate states periodically. Typical trackers include ProgressTracker (display simulation progress), PlotTracker (display images of the simulation), and SteadyStateTracker (aborting simulation when a stationary state is reached). Others can be found in the trackers module. Moreover, we provide MemoryStorage and FileStorage, which can be used as trackers to store the intermediate state to memory and to a file, respectively.