Numerical grids, spectral derivatives and PDE solvers in a few lines of NumPy-friendly Python.
Computed with numgrids: a vibration mode of a circular drum, an eigenfunction of the Laplacian on the sphere,
and the eigenstates of the quantum harmonic oscillator
(code).
Setting up grids, differentiation matrices, boundary conditions and coordinate transformations by hand is tedious and error-prone. numgrids handles all of this, so you can focus on the physics or mathematics of your problem.
What are the vibration frequencies of a circular drum? They are the square roots of the eigenvalues of the Laplacian on a disk, with the rim clamped:
from numgrids import *
drum = PolarGrid(radial(30, 1.0), periodic(40)) # the full disk, including its center
eigenvalues, modes = (-drum.laplacian_operator()).eig(k=6, bcs=0)
print(eigenvalues ** 0.5)
# [2.40482556 3.83170597 3.83170597 5.1356223 5.1356223 5.52007811]These are the zeros of the Bessel functions, correct to 13 digits on a 30 × 40 grid. There's no mesh generation, no hand-assembled matrices and no special treatment of the center.
Grids and coordinates
- Grids in any dimension from Chebyshev, equidistant, periodic and logarithmic axes
- Unbounded domains: the half line and the whole real line, without cutting the domain off
- Polar, cylindrical, spherical (volume and surface), elliptic and spheroidal coordinates, or your own via scale factors
- Full disks, cylinders, spheres and balls: the center and the poles are handled without coordinate singularities
Calculus
- Derivatives with spectral accuracy (FFT, Chebyshev) or finite differences, chosen automatically per axis
- Gradient, divergence, curl and Laplacian; volume and surface integrals; inner products and norms; spectral interpolation
- Spectral coefficients and a resolution check that tells whether a function is resolved and how many points it needs
Solving equations
- Write operators like formulas (
-0.5 * D2 + V), thensolve()boundary value problems oreig()eigenvalue problems (also generalized:L u = λ M u) - Fast direct solvers, chosen automatically: problems on disks, spheres and balls decouple into small problems per Fourier mode;
factorize()reuses a factorization for many right-hand sides - Nonlinear boundary value problems with Newton's method:
solve_nonlinear()only needs the residual, andcontinuation()follows solution branches around folds - Dirichlet, Neumann and Robin conditions in one line:
bcs={"x_low": 0, "x_high": Neumann(1)} - Time evolution (method of lines) for heat, wave, reaction-diffusion and Schrödinger-type equations, with time-dependent boundary values and sources, and an exponential integrator without time stepping error
- Stiff nonlinear equations (Korteweg–de Vries, nonlinear Schrödinger, pattern formation) with exponential and implicit-explicit integrators
- Stability of steady states;
continuation()detects folds, branch points and Hopf bifurcations - Functions of operators, e.g. the fractional Laplacian
(-L).power(0.5, bcs=0)
Tools
- Adaptive mesh refinement, convergence studies, a multigrid solver for large finite-difference problems
- Plotting and animations, save/load, xarray/NetCDF, VTK export for ParaView; all operators export SciPy sparse matrices
pip install numgridsOptional extras: numgrids[plot] (matplotlib), numgrids[xarray] (xarray), or numgrids[all].
import numpy as np
from numgrids import *
grid = Grid(x=chebyshev(30, 0, 1), y=periodic(40)) # named axes
f = grid.evaluate(lambda x, y: x**2 * np.sin(y))
grid.diff(f, axis="x") # spectrally accurate partial derivative
grid.laplacian(f) # d²f/dx² + d²f/dy²
grid.integrate(f**2) # integral over the whole domain
grid.interpolate(f, (0.3, 1.2), method="spectral")# Poisson equation ∇²u = f on the unit square with u = 0 on the boundary
grid = Grid(x=chebyshev(30, 0, 1), y=chebyshev(30, 0, 1))
u = grid.laplacian_operator().solve(lambda x, y: np.sin(np.pi * x) * y, bcs=0)
# Heat equation u_t = 0.1 u_xx on a rod with fixed ends
rod = Grid(x=chebyshev(40, 0, 1))
result = evolve(rod, 0.1 * rod.laplacian_operator(), np.sin(np.pi * rod.coords),
t_span=(0, 1), bcs=0, method="BDF")
rod.plot(result.final)ball = SphericalGrid(radial(16, 1.0), colatitude(16), periodic(32))
X, Y, Z = ball.cartesian_coords
ball.integrate(np.ones(ball.shape)) # 4.18879... = 4π/3, the volume element is built in
ball.laplacian(X**2 + Y**2 + Z**2) # 6 everywhere, including the center and the poles
ball.faces["r_high"].integrate(Z**2) # surface integral over the sphere: 4π/3atom = Grid(r=semi_infinite(48, scale=10)) # the half line [0, ∞): no cutoff radius
r = atom.coords
V = np.append(0, -1 / r[1:]) # Coulomb potential (the node r = 0 is a boundary point)
H = -0.5 * atom.diff_operator(2) + V
energies, states = H.eig(k=3, bcs=0, which="SR")
# [-0.5, -0.125, -0.05555556]: the levels -1/(2n²) of the hydrogen atom, correct to 12 digitsgrid = Grid(x=periodic(512, -60, 60))
x = grid.coords
H = -0.5 * grid.diff_operator(2) + 2.5 * np.exp(-x**2) # a potential barrier
psi0 = np.exp(-(x + 20)**2 / 9 + 2j * x) # a wave packet moving towards it
result = evolve(grid, -1j * H, psi0, t_span=(0, 24), method="expm") # exact in time, conserves the norm
grid.norm(result.final) / grid.norm(psi0) # 1.0The documentation has a user guide for every feature and the full API reference.
![]() Operators and solvers Poisson, eigenmodes, time evolution |
![]() Nonlinear problems Newton's method, continuation, stability |
![]() Vibrations of a drum Eigenmodes of the full disk |
![]() Quantum dynamics Wave packets and tunneling |
![]() Solitons Korteweg–de Vries and nonlinear Schrödinger |
![]() Pattern formation Gray–Scott and Swift–Hohenberg |
![]() Hydrogen atom Unbounded domains |
![]() Spherical harmonics Laplacian on the full sphere |
![]() Quantum oscillator Schrödinger eigenvalue problem |
![]() Heat conduction Variable conductivity, moving boundary data |
![]() Poisson equation Boundary value problem in 2D |
![]() Heat equation Insulated, cooled and fixed ends |
![]() Is my function resolved? Spectral coefficients |
![]() Convergence study Spectral vs. finite differences |
![]() Adaptive refinement Resolution where it is needed |
If you use numgrids in a publication, please cite it. The Cite this repository button in the sidebar of the GitHub page provides APA and BibTeX entries, for example:
@software{numgrids,
author = {Baer, Matthias},
title = {{numgrids}: Working with numerical grids made easy},
url = {https://github.com/maroba/numgrids},
year = {2023}
}Contributions are welcome! See CONTRIBUTING.md for how to report bugs, propose features and set up a development environment.
numgrids is released under the MIT License.














