0
# py-pde
1

2
A comprehensive Python library for solving partial differential equations (PDEs) with a focus on ease of use and performance. Provides classes for defining grids on which scalar and tensor fields can be represented, with differential operators computed using numba-compiled finite difference methods for high performance.
3

4
## Package Information
5

6
- **Package Name**: py-pde
7
- **Language**: Python
8
- **Installation**: `pip install py-pde`
9

10
## Core Imports
11

12
```python
13
import pde
14
```
15

16
Common usage imports:
17

18
```python
19
from pde import ScalarField, UnitGrid, CartesianGrid, DiffusionPDE, ExplicitSolver
20
```
21

22
## Basic Usage
23

24
```python
25
import pde
26

27
# Create a simple 1D grid
28
grid = pde.UnitGrid([64], periodic=False)
29

30
# Initialize a scalar field with random data
31
field = pde.ScalarField.random_uniform(grid)
32

33
# Define a simple diffusion PDE
34
eq = pde.DiffusionPDE(diffusivity=0.1)
35

36
# Set up boundary conditions
37
bc = {"derivative": 0}  # Neumann boundary conditions
38

39
# Solve the PDE using explicit time stepping
40
result = eq.solve(field, t_range=10, bc=bc)
41

42
print(f"Final field statistics: mean={result.average:.3f}, std={result.std:.3f}")
43
```
44

45
## Architecture
46

47
py-pde is built around several key components that work together:
48

49
- **Grids**: Define spatial domains with coordinate systems and discretization
50
- **Fields**: Represent data on grids (scalar, vector, tensor fields)
51
- **PDEs**: Mathematical descriptions of differential equations
52
- **Solvers**: Time integration algorithms for evolving fields
53
- **Trackers**: Monitor and analyze simulation progress
54
- **Storage**: Manage simulation data persistence
55

56
The numba compilation system provides high-performance finite difference operators, while the modular design allows easy customization and extension for specialized applications.
57

58
## Capabilities
59

60
### Fields
61

62
Define and manipulate scalar, vector, and tensor fields on discrete grids with automatic differentiation and mathematical operations.
63

64
```python { .api }
65
class ScalarField:
66
    def __init__(self, grid, data=None, *, label=None): ...
67
    @classmethod
68
    def random_uniform(cls, grid, vmin=0, vmax=1, **kwargs): ...
69
    def laplace(self, bc, **kwargs): ...
70
    def gradient(self, bc): ...
71

72
class VectorField:
73
    def __init__(self, grid, data=None, *, label=None): ...
74
    def divergence(self, bc): ...
75
    def curl(self, bc): ...
76

77
class Tensor2Field:
78
    def __init__(self, grid, data=None, *, label=None): ...
79
```
80

81
[Fields](./fields.md)
82

83
### Grids
84

85
Create spatial domains with various coordinate systems including Cartesian, polar, spherical, and cylindrical grids.
86

87
```python { .api }
88
class UnitGrid:
89
    def __init__(self, shape, periodic=True): ...
90

91
class CartesianGrid:
92
    def __init__(self, bounds, shape, periodic=False): ...
93

94
class PolarSymGrid:
95
    def __init__(self, radius, shape, periodic=True): ...
96

97
class SphericalSymGrid:
98
    def __init__(self, radius, shape): ...
99

100
class CylindricalSymGrid:
101
    def __init__(self, radius, bounds, shape, periodic_z=True): ...
102
```
103

104
[Grids](./grids.md)
105

106
### PDEs
107

108
Built-in partial differential equations and tools for defining custom PDEs with automatic operator compilation.
109

110
```python { .api }
111
class PDE:
112
    def __init__(self, rhs, *, noise=None, is_sde_value=None): ...
113

114
class DiffusionPDE:
115
    def __init__(self, diffusivity=1, *, noise=None, bc=None): ...
116

117
class AllenCahnPDE:
118
    def __init__(self, a=1, b=1, *, noise=None, bc=None): ...
119

120
class WavePDE:
121
    def __init__(self, speed=1, *, noise=None, bc=None): ...
122

123
def solve_laplace_equation(grid, bc, *, solver="auto"): ...
124
def solve_poisson_equation(grid, rhs, bc, *, solver="auto"): ...
125
```
126

127
[PDEs](./pdes.md)
128

129
### Solvers
130

131
Time integration algorithms for evolving PDE systems with adaptive time stepping and parallel computing support.
132

133
```python { .api }
134
class Controller:
135
    def __init__(self, sol_class, *, t_range, tracker=None): ...
136

137
class ExplicitSolver:
138
    def __init__(self, pde, *, scheme="euler", adaptive=False): ...
139

140
class ImplicitSolver:
141
    def __init__(self, pde, *, scheme="backward_euler"): ...
142

143
class CrankNicolsonSolver:
144
    def __init__(self, pde): ...
145

146
class ScipySolver:
147
    def __init__(self, pde, *, method="RK45"): ...
148
```
149

150
[Solvers](./solvers.md)
151

152
### Boundary Conditions
153

154
Comprehensive boundary condition system supporting Dirichlet, Neumann, mixed, and periodic conditions with expression-based inhomogeneous boundaries.
155

156
```python { .api }
157
class DirichletBC:
158
    def __init__(self, value, *, rank=0): ...
159

160
class NeumannBC:
161
    def __init__(self, value, *, rank=0): ...
162

163
class MixedBC:
164
    def __init__(self, value, const, *, rank=0): ...
165

166
def set_default_bc(bc): ...
167
```
168

169
[Boundary Conditions](./boundaries.md)
170

171
### Trackers
172

173
Monitor simulation progress, collect data, create visualizations, and implement custom analysis during time evolution.
174

175
```python { .api }
176
class DataTracker:
177
    def __init__(self, interrupts=1, *, filename=None): ...
178

179
class PlotTracker:
180
    def __init__(self, interrupts=1, *, filename=None): ...
181

182
class ProgressTracker:
183
    def __init__(self, interrupts="0:10"): ...
184

185
class SteadyStateTracker:
186
    def __init__(self, atol=1e-8, rtol=1e-5, interrupts=1): ...
187
```
188

189
[Trackers](./trackers.md)
190

191
### Storage
192

193
Manage simulation data with support for various storage backends including memory, files, and movie generation.
194

195
```python { .api }
196
class MemoryStorage:
197
    def __init__(self, *, write_mode="truncate_once"): ...
198

199
class FileStorage:
200
    def __init__(self, filename, *, info=None, write_mode="truncate_once"): ...
201

202
class MovieStorage:
203
    def __init__(self, filename, *, movie_writer="auto"): ...
204
```
205

206
[Storage](./storage.md)
207

208
### Visualization
209

210
Create movies and interactive plots from field data with automatic scaling and customizable styling.
211

212
```python { .api }
213
def movie(storage, filename=None, *, progress=True, **kwargs): ...
214
def plot_kymograph(storage, *, field_index=0, transpose=False): ...
215
def plot_interactive(field, title=None, *, fig_num=1): ...
216
```
217

218
[Visualization](./visualization.md)
219

220
## Types
221

222
```python { .api }
223
# Common type aliases used throughout the API
224
Real = Union[int, float]
225
ArrayLike = Union[np.ndarray, list, tuple]
226
GridAxes = Union[int, Sequence[int]]
227
BoundaryData = Union[str, dict, Callable]
228
InterruptData = Union[Real, str, Sequence]
229
```